@signalcore/ui 0.1.0 → 1.0.0-beta.1

package/src/client.ts

@@ -0,0 +1,397 @@
+import type { AboutOut, MemoryFact } from "./about";
+import type { Automation, AutomationView, RunRecord, Task } from "./automation/types";
+import { signerOf, type Credentials, type Speaker } from "./credentials";
+import type {
+  AgentFace,
+  WidgetConfig,
+  CallToken,
+  Channel,
+  Conversation,
+  ConversationDetail,
+  ConversationFile,
+  FileAt,
+  FileLink,
+  FilePreview,
+  StoredFile,
+} from "./types";
+
+/**
+ * What the API answered when it was not a success: its status, its sentence (`detail`, written
+ * to be shown) and its `code`, for a host to word in its own language.
+ */
+export class ApiError extends Error {
+  readonly status: number;
+  readonly detail: string;
+  /** What went wrong, by name (`not_found`, `no_calls`); null when the answer named nothing. */
+  readonly code: string | null;
+
+  constructor(status: number, detail: string, code: string | null = null) {
+    super(detail);
+    this.name = "ApiError";
+    this.status = status;
+    this.detail = detail;
+    this.code = code;
+  }
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+const isIssue = (value: unknown): value is { msg: string } =>
+  isRecord(value) && typeof value.msg === "string";
+
+/**
+ * Reads an error body: `{code, detail: "message"}`, or FastAPI's 422 `{detail: [{msg, …}, …]}`
+ * (the first issue speaks for all). A body with neither is named by its status alone.
+ */
+export function parseError(status: number, body: unknown): ApiError {
+  const detail = isRecord(body) ? body.detail : undefined;
+  const code = isRecord(body) && typeof body.code === "string" ? body.code : null;
+  if (typeof detail === "string" && detail !== "") return new ApiError(status, detail, code);
+  if (Array.isArray(detail)) {
+    const issue = detail.find(isIssue);
+    if (issue) return new ApiError(status, issue.msg);
+  }
+  return new ApiError(status, `HTTP ${status}`);
+}
+
+/** A body read as JSON, or null when it is not. */
+function readJson(text: string): unknown {
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Where the API is, and who calls it (`Credentials`: the cookie, a person's token, a token asked
+ * of the host's backend, or a publishable key and its visitor).
+ */
+export type ClientOptions = Credentials & {
+  /**
+   * The API's origin and prefix: `/api` in our own app (the cookie's, on the page's origin), the
+   * public `https://…/v1` from a host's page.
+   */
+  baseUrl: string;
+  /** A host's own `fetch`, when the global one is not the right one. */
+  fetch?: typeof fetch | undefined;
+};
+
+/** The files under one owner: the organization's, or an agent's own. */
+export interface Files {
+  /** Every file, by path. */
+  list: () => Promise<StoredFile[]>;
+  /**
+   * Stores the bytes under the path (replacing a file of the same name), with the blob's type
+   * as the file's; `searchable` makes it knowledge `search_files` reads (text, PDF).
+   */
+  put: (path: string, blob: Blob, searchable: boolean) => Promise<StoredFile>;
+  delete: (path: string) => Promise<void>;
+}
+
+/** How an upload goes: how much of it has gone, and how to let it go. */
+export interface UploadOptions {
+  /** Hears the share sent so far, from 0 to 1, as it goes. */
+  onProgress?: ((share: number) => void) | undefined;
+  /** Aborting it stops the upload, and the promise rejects with an `AbortError`. */
+  signal?: AbortSignal | undefined;
+}
+
+/** The API, as far as this package reaches it. */
+export interface Client {
+  /**
+   * The widget's agent and look, by the publishable key it speaks with (a web channel's key).
+   */
+  widget: () => Promise<WidgetConfig>;
+  /**
+   * Who the page speaks for, by its credentials: the business (our own app's cookie) or a person
+   * it serves (a token, a publishable key's visitor). What waits for the business's yes is
+   * answered by the business alone.
+   */
+  who: Speaker;
+  agents: {
+    /** What a person may know of the agent: its name, role, mark, and whether it takes calls. */
+    face: (id: string) => Promise<AgentFace>;
+    /** What the agent says about itself (null until it has written it) and the facts it rests on. */
+    about: (id: string) => Promise<AboutOut>;
+    /** Has the agent write about itself anew (a model call, a few seconds); answers like `about`. */
+    describe: (id: string) => Promise<AboutOut>;
+    /** The agent's own files, by path. */
+    files: (id: string) => Promise<StoredFile[]>;
+    /** Stores a file of the agent's own; see `Files.put`. */
+    putFile: (id: string, path: string, blob: Blob, searchable: boolean) => Promise<StoredFile>;
+    deleteFile: (id: string, path: string) => Promise<void>;
+    /** What the agent remembered, newest first. */
+    memories: (id: string) => Promise<MemoryFact[]>;
+    /** Takes one memory from it. */
+    forget: (id: string, memoryId: string) => Promise<void>;
+    /**
+     * The owner's call with the agent, from the browser (v3/VOICE.md): the call and its
+     * conversation (a test) made now, and where to join it (`VoiceCall`'s `connect`).
+     */
+    call: (id: string) => Promise<CallToken>;
+  };
+  /**
+   * The organization's files, shared by every agent; and the preview of any file the caller may
+   * read, the organization's, an agent's own or a conversation's (`preview`).
+   */
+  files: Files & {
+    /** What a viewer draws of the file, by its `kind` (v3/FILES.md, Preview). */
+    preview: (at: FileAt) => Promise<FilePreview>;
+  };
+  /** What an agent does on its own (v3/AUTOMATIONS.md). */
+  automations: {
+    /** The agent's automations, each as it stands now with its newest run. */
+    list: (agentId: string) => Promise<Automation[]>;
+    /** One of them by its name, with its newest runs. */
+    get: (agentId: string, name: string) => Promise<AutomationView>;
+  };
+  runs: {
+    /** One run of an automation with its record: every call it made, step by step. */
+    get: (id: string) => Promise<RunRecord>;
+  };
+  /**
+   * The tasks an agent runs for contacts, each with its newest runs: a person's own only (what
+   * they asked the agent for in their conversations); the business's, every one.
+   */
+  tasks: {
+    list: (agentId: string) => Promise<Task[]>;
+    /** Pauses it, or turns it on again; answers it as it stands. */
+    switch: (agentId: string, taskId: string, on: boolean) => Promise<Task>;
+    remove: (agentId: string, taskId: string) => Promise<void>;
+  };
+  /** Where people write to the organization's agents (v3/CHANNELS.md). */
+  channels: {
+    /** The organization's channels, or one agent's: the disconnected ones too. */
+    list: (agentId?: string) => Promise<Channel[]>;
+  };
+  conversations: {
+    /** One conversation with its messages. */
+    get: (id: string) => Promise<ConversationDetail>;
+    /** A new conversation with an agent. */
+    start: (agentId: string) => Promise<Conversation>;
+    /** The files that arrived in a conversation: attached, sent through a form. */
+    files: (id: string) => Promise<ConversationFile[]>;
+    /**
+     * Stores a file in the conversation as the person picks it, to say it or send it through a
+     * form by its id: its bytes as they are, under its type and name.
+     */
+    upload: (id: string, file: File, options?: UploadOptions) => Promise<ConversationFile>;
+    /**
+     * Where a picture, a video or a sound of the conversation plays from in the page's own
+     * player: an address that needs no credential, for an hour, streamed as the player seeks.
+     */
+    play: (id: string, fileId: string) => Promise<string>;
+    /**
+     * A call with the agent from the browser, for whoever may talk to it (a person, as theirs):
+     * the call and its own conversation made now, where what is said lands, and where to join it
+     * (`VoiceCall`'s `connect`).
+     */
+    call: (agentId: string) => Promise<CallToken>;
+  };
+  /**
+   * The conversation's socket address, signed in: `ws:` beside `http:`, `wss:` beside `https:`,
+   * with the token (and the visitor) in its query, since a browser's socket takes no header.
+   * `fresh` asks the host's backend for a new token first (`getToken`), for a socket that could
+   * not open with the last one.
+   */
+  liveUrl: (conversationId: string, options?: { fresh?: boolean | undefined }) => Promise<string>;
+}
+
+const seg = encodeURIComponent;
+
+/** A file's path in a URL: each name of it encoded, the slashes between them kept. */
+const filePath = (path: string): string => path.split("/").map(seg).join("/");
+
+/** Where a file's preview is read: under its conversation, its agent or the organization. */
+const previewPath = (at: FileAt): string => {
+  if ("conversationId" in at) {
+    return `/conversations/${seg(at.conversationId)}/files/${seg(at.fileId)}/preview`;
+  }
+  const owner = "agentId" in at ? `/agents/${seg(at.agentId)}` : "";
+  return `${owner}/files/${filePath(at.path)}/preview`;
+};
+
+type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+/**
+ * The API under `baseUrl`: JSON in and out, an `ApiError` for anything but a success, signed in
+ * the one way `options` gives. A token asked of the host's backend (`getToken`) that the API
+ * refuses (401: it expired) is asked for once more, and the request sent again with it.
+ */
+export function createClient(options: ClientOptions): Client {
+  const { baseUrl, fetch: call = fetch } = options;
+  const signer = signerOf(options);
+
+  /** One request with the cookie or the credential's headers; a body goes as it is, typed. */
+  async function attempt(method: Method, path: string, body: Blob | undefined) {
+    const signed = await signer.sign();
+    const response = await call(`${baseUrl}${path}`, {
+      method,
+      credentials: signer.credentials,
+      headers:
+        body === undefined ? signed.headers : { ...signed.headers, "Content-Type": body.type },
+      ...(body === undefined ? {} : { body }),
+    });
+    return { response, signed };
+  }
+
+  async function send(method: Method, path: string, body?: Blob): Promise<Response> {
+    let { response, signed } = await attempt(method, path, body);
+    if (response.status === 401 && signed.renew !== null) {
+      signed.renew();
+      ({ response } = await attempt(method, path, body));
+    }
+    if (!response.ok) {
+      const answer: unknown = await response.json().catch(() => null);
+      throw parseError(response.status, answer);
+    }
+    return response;
+  }
+
+  async function json<T>(method: Method, path: string, body?: Blob): Promise<T> {
+    return (await (await send(method, path, body)).json()) as T;
+  }
+
+  /** A request whose answer has no body (204). */
+  async function run(method: Method, path: string): Promise<void> {
+    await send(method, path);
+  }
+
+  /** The four of `Files` under a prefix: `/files`, or `/agents/{id}/files`. */
+  const filesUnder = (prefix: string): Files => ({
+    list: () => json("GET", prefix),
+    put: (path, blob, searchable) =>
+      json("PUT", `${prefix}/${filePath(path)}?searchable=${searchable}`, blob),
+    delete: (path) => run("DELETE", `${prefix}/${filePath(path)}`),
+  });
+
+  const own = (id: string) => filesUnder(`/agents/${seg(id)}/files`);
+
+  /**
+   * A file sent by XMLHttpRequest, the one way a browser tells how much of a body has gone; the
+   * cookie goes as with `fetch` on the same origin, any other credential as its headers. Refused
+   * with a token asked of the host's backend, it is sent once more with a new one.
+   */
+  async function sendFile(
+    path: string,
+    file: File,
+    options: UploadOptions = {},
+  ): Promise<ConversationFile> {
+    const signed = await signer.sign();
+    try {
+      return await post(path, file, signed.headers, options);
+    } catch (error) {
+      const expired = error instanceof ApiError && error.status === 401;
+      if (!expired || signed.renew === null) throw error;
+      signed.renew();
+      return post(path, file, (await signer.sign()).headers, options);
+    }
+  }
+
+  function post(
+    path: string,
+    file: File,
+    headers: Readonly<Record<string, string>>,
+    { onProgress, signal }: UploadOptions,
+  ): Promise<ConversationFile> {
+    return new Promise((resolve, reject) => {
+      const aborted = () => new DOMException("The upload was aborted", "AbortError");
+      if (signal?.aborted) {
+        reject(aborted());
+        return;
+      }
+      const request = new XMLHttpRequest();
+      const abort = () => {
+        request.abort();
+      };
+      request.open("POST", `${baseUrl}${path}`);
+      for (const [name, value] of Object.entries(headers)) request.setRequestHeader(name, value);
+      request.setRequestHeader("Content-Type", file.type || "application/octet-stream");
+      request.setRequestHeader("X-File-Name", encodeURIComponent(file.name));
+      request.upload.addEventListener("progress", (event) => {
+        if (event.lengthComputable && event.total > 0) onProgress?.(event.loaded / event.total);
+      });
+      request.addEventListener("loadend", () => {
+        signal?.removeEventListener("abort", abort);
+      });
+      request.addEventListener("load", () => {
+        const body = readJson(request.responseText);
+        if (request.status >= 200 && request.status < 300) resolve(body as ConversationFile);
+        else reject(parseError(request.status, body));
+      });
+      request.addEventListener("error", () => {
+        reject(new ApiError(0, "The upload could not reach the server"));
+      });
+      request.addEventListener("abort", () => {
+        reject(aborted());
+      });
+      signal?.addEventListener("abort", abort, { once: true });
+      request.send(file);
+    });
+  }
+
+  return {
+    widget: () => json("GET", "/channels/web/widget"),
+    who: signer.who,
+    agents: {
+      face: (id) => json("GET", `/agents/${seg(id)}/face`),
+      about: (id) => json("GET", `/agents/${seg(id)}/about`),
+      describe: (id) => json("POST", `/agents/${seg(id)}/describe`),
+      files: (id) => own(id).list(),
+      putFile: (id, path, blob, searchable) => own(id).put(path, blob, searchable),
+      deleteFile: (id, path) => own(id).delete(path),
+      memories: (id) => json("GET", `/agents/${seg(id)}/memories`),
+      forget: (id, memoryId) => run("DELETE", `/agents/${seg(id)}/memories/${seg(memoryId)}`),
+      call: (id) => json("POST", `/agents/${seg(id)}/voice/token`),
+    },
+    files: { ...filesUnder("/files"), preview: (at) => json("GET", previewPath(at)) },
+    automations: {
+      list: (agentId) => json("GET", `/agents/${seg(agentId)}/automations`),
+      get: (agentId, name) => json("GET", `/agents/${seg(agentId)}/automations/${seg(name)}`),
+    },
+    runs: {
+      get: (id) => json("GET", `/runs/${seg(id)}`),
+    },
+    tasks: {
+      list: (agentId) => json("GET", `/agents/${seg(agentId)}/tasks`),
+      switch: (agentId, taskId, on) =>
+        json(
+          "PATCH",
+          `/agents/${seg(agentId)}/tasks/${seg(taskId)}`,
+          new Blob([JSON.stringify({ on })], { type: "application/json" }),
+        ),
+      remove: (agentId, taskId) => run("DELETE", `/agents/${seg(agentId)}/tasks/${seg(taskId)}`),
+    },
+    channels: {
+      list: (agentId) =>
+        json("GET", agentId === undefined ? "/channels" : `/channels?agent=${seg(agentId)}`),
+    },
+    conversations: {
+      get: (id) => json("GET", `/conversations/${seg(id)}`),
+      start: (agentId) => json("POST", `/agents/${seg(agentId)}/conversations`),
+      files: (id) => json("GET", `/conversations/${seg(id)}/files`),
+      upload: (id, file, options) => sendFile(`/conversations/${seg(id)}/files`, file, options),
+      play: async (id, fileId) => {
+        const link = await json<FileLink>(
+          "GET",
+          `/conversations/${seg(id)}/files/${seg(fileId)}/link`,
+        );
+        return new URL(`${baseUrl}${link.path}`, window.location.href).href;
+      },
+      call: (agentId) => json("POST", `/agents/${seg(agentId)}/calls`),
+    },
+    liveUrl: async (conversationId, { fresh = false } = {}) => {
+      const url = new URL(
+        `${baseUrl}/conversations/${seg(conversationId)}/live`,
+        window.location.href,
+      );
+      url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+      for (const [name, value] of Object.entries(await signer.query(fresh))) {
+        url.searchParams.set(name, value);
+      }
+      return url.href;
+    },
+  };
+}

package/src/conversationFiles.ts

@@ -0,0 +1,54 @@
+import { useMemo, useRef, useState } from "react";
+
+import type { Client } from "./client";
+import type { FileHost } from "./kit/uploads";
+import type { Attachment, Message } from "./types";
+
+/**
+ * A conversation's files, as its chat's pieces reach them: an upload to it (the composer's, a
+ * form's file field), every file known by id (said in its messages, uploaded here, or read back
+ * once when one is asked for that neither has), where one plays from, and the host's way to
+ * open one.
+ */
+export function useConversationFiles(
+  client: Client,
+  conversationId: string,
+  messages: readonly Message[],
+  open: ((file: Attachment) => void) | undefined,
+): FileHost {
+  const [kept, setKept] = useState<ReadonlyMap<string, Attachment>>(() => new Map());
+  const listed = useRef(false);
+
+  const known = useMemo(() => {
+    const all = new Map(kept);
+    for (const message of messages) for (const file of message.files ?? []) all.set(file.id, file);
+    return all;
+  }, [messages, kept]);
+
+  const keep = (files: readonly Attachment[]) => {
+    setKept((now) => {
+      const next = new Map(now);
+      for (const file of files) next.set(file.id, file);
+      return next;
+    });
+  };
+
+  return {
+    known,
+    open,
+    play: (file) => client.conversations.play(conversationId, file.id),
+    upload: async (file, progress, signal) => {
+      const stored = await client.conversations.upload(conversationId, file, {
+        onProgress: progress,
+        signal,
+      });
+      keep([stored]);
+      return stored;
+    },
+    find: (ids) => {
+      if (listed.current || ids.every((id) => known.has(id))) return;
+      listed.current = true;
+      client.conversations.files(conversationId).then(keep, () => undefined);
+    },
+  };
+}

package/src/credentials.ts

@@ -0,0 +1,158 @@
+/**
+ * Who a client calls as, one way at a time (v3/README.md, Credentials): the owner's session cookie
+ * in our own app; a person's token, given as it is or asked of the host's backend (and asked again
+ * once it expires); or an anonymous visitor of a site, by the site's publishable key and the id
+ * the page keeps for them.
+ */
+
+type Way = "credentials" | "token" | "getToken" | "publishableKey" | "visitorId";
+
+/** One way of signing in, with none of the others beside it. */
+type Alone<T> = T & { [K in Exclude<Way, keyof T>]?: never };
+
+export type Credentials =
+  /** Our app, on the API's own origin (`/api`): the session cookie the browser holds. */
+  | Alone<{ credentials: "cookie" }>
+  /** A person's token the host's backend minted (`POST /v1/tokens`), used as it is. */
+  | Alone<{ token: string }>
+  /**
+   * A person's token asked of the host's backend: when first needed, and once more each time the
+   * API refuses the one kept (it lasts an hour).
+   */
+  | Alone<{ getToken: () => Promise<string> }>
+  /**
+   * An anonymous visitor (the widget): the site's publishable key, and who they are, an id the
+   * page keeps; one is made and kept in `localStorage` when none is given.
+   */
+  | Alone<{ publishableKey: string; visitorId?: string | undefined }>;
+
+/** What one request carries to say who calls, and how to have it anew once it is refused. */
+export interface Signed {
+  headers: Readonly<Record<string, string>>;
+  /** Lets go of a token the API refused, for the next request to ask for another; null: none. */
+  renew: (() => void) | null;
+}
+
+/**
+ * Who a page speaks for: the business (the owner, in our own app) or a person it serves (a token's
+ * person, a publishable key's visitor). The API lets each answer different things: a yes the
+ * business decides is the business's alone.
+ */
+export type Speaker = "business" | "person";
+
+/** How every request and socket of a client says who calls. */
+export interface Signer {
+  who: Speaker;
+  /** What `fetch` sends of the browser's own: the cookie on the page's origin, or nothing. */
+  credentials: RequestCredentials;
+  sign: () => Promise<Signed>;
+  /**
+   * What a socket carries in its address instead (a browser's socket takes no header); `fresh`
+   * asks for a new token first, for a socket that could not open with the last one.
+   */
+  query: (fresh: boolean) => Promise<Readonly<Record<string, string>>>;
+}
+
+/** Where the page keeps its visitor's id, for every SignalCore widget on the site. */
+export const VISITOR_KEY = "signalcore.visitor";
+
+/** What the API takes as a visitor's id: 16 to 128 letters, digits, `_` and `-`. */
+const VISITOR = /^[A-Za-z0-9_-]{16,128}$/;
+
+/** A new visitor's id: 32 hex characters of the browser's own randomness (any page has it). */
+function newVisitor(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * The visitor this page speaks for: the one kept in `localStorage`, else a new one kept there for
+ * their next visit; where the page can't keep anything (a private window, storage blocked), a new
+ * one for this page alone.
+ */
+export function keptVisitor(): string {
+  try {
+    const kept = localStorage.getItem(VISITOR_KEY);
+    if (kept !== null && VISITOR.test(kept)) return kept;
+    const made = newVisitor();
+    localStorage.setItem(VISITOR_KEY, made);
+    return made;
+  } catch {
+    return newVisitor();
+  }
+}
+
+/** A credential that never changes: the same headers and the same query, nothing to renew. */
+const fixed = (
+  who: Speaker,
+  credentials: RequestCredentials,
+  headers: Record<string, string>,
+  query: Record<string, string>,
+): Signer => ({
+  who,
+  credentials,
+  sign: () => Promise.resolve({ headers, renew: null }),
+  query: () => Promise.resolve(query),
+});
+
+/**
+ * A token asked of the host's backend: when first needed, then kept. A refusal lets it go, once
+ * however many requests were refused with it, so the next request asks for another; one that
+ * could not be had is asked for again next time.
+ */
+function fetched(getToken: () => Promise<string>): Signer {
+  let current: Promise<string> | null = null;
+  const latest = (): Promise<string> => {
+    if (current !== null) return current;
+    const asked = Promise.resolve().then(getToken);
+    current = asked;
+    asked.catch(() => {
+      if (current === asked) current = null;
+    });
+    return asked;
+  };
+  return {
+    who: "person",
+    credentials: "omit",
+    sign: async () => {
+      const used = latest();
+      const token = await used;
+      return {
+        headers: { Authorization: `Bearer ${token}` },
+        renew: () => {
+          if (current === used) current = null;
+        },
+      };
+    },
+    query: async (fresh) => {
+      if (fresh) current = null;
+      return { token: await latest() };
+    },
+  };
+}
+
+/**
+ * How a client signs in with what it was given. The API's public prefix reads the header (the
+ * socket, its query) and never a cookie, so only our own app sends the browser's.
+ */
+export function signerOf(given: Credentials): Signer {
+  if (given.credentials === "cookie") return fixed("business", "same-origin", {}, {});
+  if (typeof given.token === "string") {
+    const { token } = given;
+    return fixed("person", "omit", { Authorization: `Bearer ${token}` }, { token });
+  }
+  if (typeof given.getToken === "function") return fetched(given.getToken);
+  if (typeof given.publishableKey === "string") {
+    const key = given.publishableKey;
+    const visitor = given.visitorId ?? keptVisitor();
+    return fixed(
+      "person",
+      "omit",
+      { Authorization: `Bearer ${key}`, "SignalCore-Visitor": visitor },
+      { token: key, visitor },
+    );
+  }
+  throw new TypeError(
+    'createClient takes one way to sign in: credentials: "cookie", token, getToken or publishableKey',
+  );
+}

package/src/dev.ts

@@ -0,0 +1,20 @@
+/**
+ * Whether the page runs a development build, as React tells it: a host's bundler writes in
+ * `process.env.NODE_ENV`; a page without one has no `process`, and counts as production.
+ */
+declare const process: { env: { NODE_ENV?: string } };
+
+function development(): boolean {
+  try {
+    return process.env.NODE_ENV !== "production";
+  } catch {
+    return false;
+  }
+}
+
+export const DEV = development();
+
+/** A note for the developer of the page, in development only: what the package let pass, and why. */
+export function note(...said: unknown[]): void {
+  if (DEV) console.debug("[signalcore]", ...said);
+}