@signalcore/ui 0.1.0 → 1.0.0-beta.0

package/src/automation/cron.ts

@@ -0,0 +1,196 @@
+/**
+ * A schedule's cron line, read into what it fires at: the moments of a day (a squad's day, an
+ * automation's next runs) and the sentence that says it (`whenOf`). Five fields (minute, hour,
+ * day of the month, month, day of the week) with `*`, lists, ranges, steps and English names, as
+ * the API's croniter reads them; anything past that is not read (null).
+ */
+
+export interface Cron {
+  minutes: ReadonlySet<number>;
+  hours: ReadonlySet<number>;
+  /** Day of the month, 1–31. */
+  days: ReadonlySet<number>;
+  /** 1–12. */
+  months: ReadonlySet<number>;
+  /** 0–6, Sunday 0. */
+  weekdays: ReadonlySet<number>;
+  /** Left open (`*`): cron's rule for days reads which of the two narrows them. */
+  anyDay: boolean;
+  anyWeekday: boolean;
+}
+
+interface Field {
+  min: number;
+  max: number;
+  names?: readonly string[];
+}
+
+const MONTH_NAMES = [
+  "jan",
+  "feb",
+  "mar",
+  "apr",
+  "may",
+  "jun",
+  "jul",
+  "aug",
+  "sep",
+  "oct",
+  "nov",
+  "dec",
+] as const;
+const WEEKDAY_NAMES = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"] as const;
+
+const FIELDS: readonly Field[] = [
+  { min: 0, max: 59 },
+  { min: 0, max: 23 },
+  { min: 1, max: 31 },
+  { min: 1, max: 12, names: MONTH_NAMES },
+  { min: 0, max: 7, names: WEEKDAY_NAMES },
+];
+
+/** One value of a field: a number in its bounds, or one of its names (`mon`, `jan`). */
+function valueOf(text: string, field: Field): number | null {
+  const named = field.names?.indexOf(text.toLowerCase()) ?? -1;
+  if (named >= 0) return named + field.min;
+  if (!/^\d+$/.test(text)) return null;
+  const value = Number(text);
+  return value >= field.min && value <= field.max ? value : null;
+}
+
+/** A field's values: `*`, `5`, `1-5`, `*` every 15, `8-18` every 2, `mon-fri`, and lists of them. */
+function parseField(text: string, field: Field): number[] | null {
+  const values = new Set<number>();
+  for (const part of text.split(",")) {
+    const [range = "", stepText] = part.split("/");
+    const step = stepText === undefined ? 1 : Number(stepText);
+    if (!Number.isInteger(step) || step < 1) return null;
+    let from: number | null;
+    let to: number | null;
+    if (range === "*") {
+      [from, to] = [field.min, field.max];
+    } else {
+      const [first = "", last] = range.split("-");
+      from = valueOf(first, field);
+      // "8/2" runs from 8 to the end of the field, as cron reads it.
+      to = last !== undefined ? valueOf(last, field) : stepText !== undefined ? field.max : from;
+    }
+    if (from === null || to === null || from > to) return null;
+    for (let value = from; value <= to; value += step) values.add(value);
+  }
+  return [...values];
+}
+
+/** A cron line of five fields, or null when it is anything else. */
+export function parseCron(line: string): Cron | null {
+  const texts = line.trim().split(/\s+/);
+  if (texts.length !== 5) return null;
+  const [minutes, hours, days, months, weekdays] = texts.map((text, at) => {
+    const field = FIELDS[at];
+    return field ? parseField(text, field) : null;
+  });
+  if (!minutes || !hours || !days || !months || !weekdays) return null;
+  return {
+    minutes: new Set(minutes),
+    hours: new Set(hours),
+    days: new Set(days),
+    months: new Set(months),
+    // 7 is Sunday too.
+    weekdays: new Set(weekdays.map((day) => day % 7)),
+    anyDay: texts[2]?.startsWith("*") ?? false,
+    anyWeekday: texts[4]?.startsWith("*") ?? false,
+  };
+}
+
+/** A moment as a zone's clock reads it. */
+export interface Wall {
+  minute: number;
+  hour: number;
+  day: number;
+  month: number;
+  weekday: number;
+}
+
+/**
+ * Whether the line fires at that minute. Days follow cron's rule: when both the day of the month
+ * and the day of the week are narrowed, either one is enough.
+ */
+export function fires(cron: Cron, at: Wall): boolean {
+  if (!cron.minutes.has(at.minute) || !cron.hours.has(at.hour) || !cron.months.has(at.month)) {
+    return false;
+  }
+  const day = cron.days.has(at.day);
+  const weekday = cron.weekdays.has(at.weekday);
+  if (cron.anyDay && cron.anyWeekday) return true;
+  if (cron.anyDay) return weekday;
+  if (cron.anyWeekday) return day;
+  return day || weekday;
+}
+
+const MINUTE = 60_000;
+/** How often the zone's offset is read again: a quarter of an hour meets every zone's changes. */
+const QUARTER = 15 * MINUTE;
+
+const clocks = new Map<string, Intl.DateTimeFormat>();
+
+/** The zone's clock, kept; an unknown zone reads as UTC, the API's default. */
+function clockOf(zone: string): Intl.DateTimeFormat {
+  let clock = clocks.get(zone);
+  if (!clock) {
+    const options: Intl.DateTimeFormatOptions = {
+      hourCycle: "h23",
+      year: "numeric",
+      month: "numeric",
+      day: "numeric",
+      hour: "numeric",
+      minute: "numeric",
+      second: "numeric",
+    };
+    try {
+      clock = new Intl.DateTimeFormat("en-US", { ...options, timeZone: zone });
+    } catch {
+      clock = new Intl.DateTimeFormat("en-US", { ...options, timeZone: "UTC" });
+    }
+    clocks.set(zone, clock);
+  }
+  return clock;
+}
+
+/** How far the zone's clock is ahead of UTC at a moment, in milliseconds. */
+export function offsetOf(zone: string, at: Date): number {
+  const parts = clockOf(zone).formatToParts(at);
+  const part = (type: Intl.DateTimeFormatPartTypes) =>
+    Number(parts.find((each) => each.type === type)?.value ?? 0);
+  const wall = Date.UTC(
+    part("year"),
+    part("month") - 1,
+    part("day"),
+    part("hour") % 24,
+    part("minute"),
+    part("second"),
+  );
+  return wall - Math.floor(at.getTime() / 1000) * 1000;
+}
+
+/** Every moment in [from, to) the line fires at, read on the clock of `zone`. */
+export function occurrences(cron: Cron, zone: string, from: Date, to: Date): Date[] {
+  const out: Date[] = [];
+  let quarter = Number.NaN;
+  let offset = 0;
+  for (let at = Math.ceil(from.getTime() / MINUTE) * MINUTE; at < to.getTime(); at += MINUTE) {
+    if (Math.floor(at / QUARTER) !== quarter) {
+      quarter = Math.floor(at / QUARTER);
+      offset = offsetOf(zone, new Date(at));
+    }
+    const wall = new Date(at + offset);
+    const fired = fires(cron, {
+      minute: wall.getUTCMinutes(),
+      hour: wall.getUTCHours(),
+      day: wall.getUTCDate(),
+      month: wall.getUTCMonth() + 1,
+      weekday: wall.getUTCDay(),
+    });
+    if (fired) out.push(new Date(at));
+  }
+  return out;
+}

package/src/automation/marks.tsx

@@ -0,0 +1,144 @@
+import {
+  BellIcon,
+  BrainIcon,
+  ChatCircleIcon,
+  ChatTextIcon,
+  ChatsCircleIcon,
+  ClockIcon,
+  FileTextIcon,
+  FlaskIcon,
+  GlobeIcon,
+  LightningIcon,
+  SparkleIcon,
+  TableIcon,
+  WebhooksLogoIcon,
+  type Icon,
+} from "@phosphor-icons/react";
+import type { ReactNode } from "react";
+
+import type { AppDirectory } from "../AgentAbout";
+import { Mark } from "../kit/Mark";
+import { sentOn } from "./record";
+import type { RunBy, RunStep, Trigger, Use } from "./types";
+
+/** Only an https logo is loaded: never a script, never a local file. */
+const https = (url: string | null): url is string => url !== null && /^https:\/\//i.test(url);
+
+/**
+ * An app's mark: the host's logo when it draws apps (`apps`), else the logo the API gives, else
+ * the app's initial; each bare, as `Mark` draws it.
+ */
+export function AppMark({
+  name,
+  icon,
+  size,
+  apps,
+}: {
+  name: string;
+  icon: string | null;
+  size: number;
+  apps: AppDirectory | undefined;
+}) {
+  if (apps !== undefined) return <>{apps.logo({ provider: "", name, icon, size })}</>;
+  if (https(icon)) return <Mark src={icon} size={size} />;
+  return (
+    <Mark size={size}>
+      <span>{name.trim().charAt(0).toUpperCase() || "?"}</span>
+    </Mark>
+  );
+}
+
+const KINDS: Readonly<Record<Exclude<Trigger["kind"], "event">, Icon>> = {
+  schedule: ClockIcon,
+  webhook: WebhooksLogoIcon,
+};
+
+/** What starts an automation, as a mark: a clock, a webhook, the app whose event it waits for. */
+export function TriggerMark({
+  trigger,
+  size,
+  apps,
+}: {
+  trigger: Trigger;
+  size: number;
+  apps: AppDirectory | undefined;
+}) {
+  if (trigger.kind !== "event") return <Mark icon={KINDS[trigger.kind]} size={size} />;
+  const name = trigger.app_title ?? trigger.app;
+  if (name === null) return <Mark icon={LightningIcon} size={size} />;
+  return <AppMark name={name} icon={trigger.icon} size={size} apps={apps} />;
+}
+
+/** What started a run: its time, a call, its app's event, a chat with the agent, a test. */
+const BY: Readonly<Record<Exclude<RunBy, "event">, Icon>> = {
+  schedule: ClockIcon,
+  webhook: WebhooksLogoIcon,
+  agent: ChatCircleIcon,
+  test: FlaskIcon,
+};
+
+export function ByMark({
+  by,
+  trigger,
+  size,
+  apps,
+}: {
+  by: RunBy;
+  /** The automation's, for an event's app; none, a plain mark. */
+  trigger: Trigger | null;
+  size: number;
+  apps: AppDirectory | undefined;
+}) {
+  if (by !== "event") return <Mark icon={BY[by]} size={size} />;
+  return trigger === null ? (
+    <Mark icon={LightningIcon} size={size} />
+  ) : (
+    <TriggerMark trigger={trigger} size={size} apps={apps} />
+  );
+}
+
+/**
+ * What a step uses, other than an app: the model, the agent, the inbox, a message on a channel, a
+ * table, the web.
+ */
+export const USES: Readonly<Record<Exclude<Use["kind"], "app">, Icon>> = {
+  ai: SparkleIcon,
+  agent: ChatsCircleIcon,
+  notify: BellIcon,
+  send: ChatTextIcon,
+  data: TableIcon,
+  http: GlobeIcon,
+};
+
+/** A call of a run's record, by what it reached; an app's tool by the app's mark. */
+const CALLS: Readonly<Record<string, Icon>> = {
+  ai: SparkleIcon,
+  notify: BellIcon,
+  send: ChatTextIcon,
+  "agent.start": ChatsCircleIcon,
+  "data.find": TableIcon,
+  "data.add": TableIcon,
+  "data.update": TableIcon,
+  http: GlobeIcon,
+  "files.search": FileTextIcon,
+  "files.read": FileTextIcon,
+  "files.write": FileTextIcon,
+  "files.list": FileTextIcon,
+  "memory.remember": BrainIcon,
+  "memory.recall": BrainIcon,
+};
+
+export function callMark(
+  step: RunStep,
+  app: { name: string; icon: string | null } | null,
+  apps: AppDirectory | undefined,
+  size: number,
+): ReactNode {
+  if (app !== null) return <AppMark name={app.name} icon={app.icon} size={size} apps={apps} />;
+  // A message sent on a channel: the channel's brand, when the host draws brands and it is known.
+  const channel = step.call === "send" ? sentOn(step) : null;
+  if (channel !== null && apps !== undefined) {
+    return apps.logo({ provider: channel, name: channel, size });
+  }
+  return <Mark icon={CALLS[step.call] ?? LightningIcon} size={size} />;
+}

package/src/automation/messages.ts

@@ -0,0 +1,231 @@
+import type { AutomationState, RunBy, RunStatus, Use } from "./types";
+
+/**
+ * A day as a person says it beside a time: today, yesterday, tomorrow, a weekday within the
+ * week (`name` as the locale names it, short or long), or a date further away.
+ */
+export type DayRef =
+  { kind: "today" | "yesterday" | "tomorrow" } | { kind: "weekday" | "date"; name: string };
+
+/** A tool's call by what it does, read from its name: what a run's record says it did. */
+export type Verb = "search" | "send" | "create" | "update" | "remove" | "use";
+
+/** What a run did, call by call, in words; `would` is a test's write, recorded and not done. */
+export interface CallMessages {
+  /** An app's tool, by what its name says it does, with the app's name. */
+  tool: (verb: Verb, app: string, would: boolean) => string;
+  /** One model call: it reads and writes for real in a test too. */
+  ai: string;
+  /** A line in the owner's inbox. */
+  notify: (would: boolean) => string;
+  /**
+   * A message to a contact on one of the agent's channels: the channel's kind when the record
+   * says it (`whatsapp`, `instagram`, `sms`), and who to (a number; "" for a contact by its id).
+   */
+  send: (channel: string | null, to: string, would: boolean) => string;
+  /** A conversation of the agent opened for what needs judgement or a person. */
+  start: (would: boolean) => string;
+  /** A table's rows looked up, added, changed, by the table's title. */
+  find: (table: string) => string;
+  add: (table: string, would: boolean) => string;
+  change: (table: string, would: boolean) => string;
+  /** A call to another system, by its host. */
+  http: (host: string, would: boolean) => string;
+  /** The organization's files searched. */
+  files: string;
+  /** One of its files read, kept, or its files listed, by the file's name. */
+  read: (file: string) => string;
+  wrote: (file: string, would: boolean) => string;
+  listed: string;
+  /** A line kept in, and one looked up from, what the agent learned. */
+  remember: (would: boolean) => string;
+  recall: string;
+}
+
+/** The words of an automation and its runs: the trigger in words, its state, its runs. */
+export interface AutomationMessages {
+  /** When it runs, from its cron line (`whenOf`): the days, then the times. */
+  daily: string;
+  /** Monday to Friday. */
+  weekdays: string;
+  /** Saturday and Sunday. */
+  weekends: string;
+  /** Some days of the week, by their names. */
+  weekly: (days: string[]) => string;
+  /** Some days of the month. */
+  monthly: (days: number[]) => string;
+  /** The times it runs at, after the days ("9:00", as the locale writes it). */
+  at: (times: string[]) => string;
+  /** Every few minutes or hours, all day or `between` two times. */
+  every: (count: number, unit: "minute" | "hour") => string;
+  between: (from: string, to: string) => string;
+  /** A frequency on some days only: "every 15 minutes" and "on weekdays". */
+  on: (often: string, days: string) => string;
+  /** A schedule the sentence can't say. */
+  custom: string;
+  /** What another kind of trigger waits for. */
+  webhook: string;
+  event: (app: string | null, event: string | null) => string;
+  /** When it runs next, after when it runs: the day, and the time when the line doesn't say it. */
+  next: (day: DayRef, time: string | null) => string;
+  /** How it stands, on its pill. */
+  states: Readonly<Record<AutomationState, string>>;
+  /** Its switch, for screen readers. */
+  switchLabel: string;
+  /** Over its steps, the table it moves, its runs. */
+  steps: string;
+  runs: string;
+  /** In the place of its runs, when there are none yet. */
+  noRuns: string;
+  /** What a step uses, other than an app (which goes by its name). */
+  uses: Readonly<Record<Exclude<Use["kind"], "app">, string>>;
+  /** The values of the table past the ones shown: "+3". */
+  more: (count: number) => string;
+  /** An automation the agent named that is not there (removed, renamed). */
+  gone: string;
+  /** When a run started, beside what started it. */
+  moment: (day: DayRef, time: string) => string;
+  /** What started a run; an event's by its app's name, when known. */
+  by: (by: RunBy, app: string | null) => string;
+  /** How a run stands. */
+  statuses: Readonly<Record<RunStatus, string>>;
+  /** A test's line: what the run returned, though it changed nothing. */
+  dry: (summary: string) => string;
+  /** How long a run took. */
+  took: (ms: number) => string;
+  /** Over the conversations a run opened, and each one's link. */
+  opened: string;
+  conversation: (index: number) => string;
+  /** The conversation the agent was asked in, for a run it started. */
+  askedIn: string;
+  /** A run that called nothing. */
+  noCalls: string;
+  /** Over the calls made outside any step. */
+  outside: string;
+  /** A call made several times in a row: "×12". */
+  times: (count: number) => string;
+  calls: CallMessages;
+}
+
+const plural = (count: number, one: string, many: string) =>
+  count === 1 ? one : `${count} ${many}`;
+
+/** English: what the package says until a host gives its own words. */
+export const AUTOMATION_MESSAGES: AutomationMessages = {
+  daily: "Every day",
+  weekdays: "Every weekday",
+  weekends: "Every weekend",
+  weekly: (days) =>
+    days.length === 1 ? `Every ${days[0] ?? ""}` : `On ${new Intl.ListFormat("en").format(days)}`,
+  monthly: (days) => `On day ${new Intl.ListFormat("en").format(days.map(String))} of every month`,
+  at: (times) => `at ${new Intl.ListFormat("en").format(times)}`,
+  every: (count, unit) => `Every ${plural(count, unit, `${unit}s`)}`,
+  between: (from, to) => `from ${from} to ${to}`,
+  on: (often, days) => `${often}, ${days.charAt(0).toLowerCase()}${days.slice(1)}`,
+  custom: "On a schedule of its own",
+  webhook: "When another system calls it",
+  event: (app, event) =>
+    event ? `When ${event} in ${app ?? "an app"}` : `On an event in ${app ?? "an app"}`,
+  next: (day, time) => {
+    const at = time === null ? "" : ` at ${time}`;
+    switch (day.kind) {
+      case "today":
+        return `next today${at}`;
+      case "tomorrow":
+        return `next tomorrow${at}`;
+      case "yesterday":
+        return `next${at}`;
+      default:
+        return `next on ${day.name}${at}`;
+    }
+  },
+  states: { active: "On", paused: "Paused", failing: "Last run failed" },
+  switchLabel: "On",
+  steps: "Steps",
+  runs: "Runs",
+  noRuns: "It hasn't run yet.",
+  uses: {
+    ai: "AI",
+    agent: "Agent",
+    notify: "Inbox",
+    send: "Message",
+    data: "Table",
+    http: "Web",
+  },
+  more: (count) => `+${count}`,
+  gone: "This automation is no longer there.",
+  moment: (day, time) => {
+    switch (day.kind) {
+      case "today":
+        return `Today ${time}`;
+      case "yesterday":
+        return `Yesterday ${time}`;
+      case "tomorrow":
+        return `Tomorrow ${time}`;
+      default:
+        return `${day.name} ${time}`;
+    }
+  },
+  by: (by, app) =>
+    ({
+      schedule: "scheduled",
+      webhook: "webhook",
+      event: app ? `${app} event` : "event",
+      agent: "you asked in the chat",
+      test: "test",
+    })[by],
+  statuses: {
+    running: "Running",
+    waiting: "Waiting",
+    done: "Done",
+    failed: "Failed",
+    skipped: "Skipped",
+  },
+  dry: (summary) => `Test: ${summary}`,
+  took: (ms) =>
+    ms < 60_000 ? `${Math.max(1, Math.round(ms / 1000))} s` : `${Math.round(ms / 60_000)} min`,
+  opened: "Conversations it opened",
+  conversation: (index) => `Conversation ${index}`,
+  askedIn: "The conversation you asked in",
+  noCalls: "It didn't call anything.",
+  outside: "Outside the steps",
+  times: (count) => `×${count}`,
+  calls: {
+    tool: (verb, app, would) => {
+      const done = {
+        search: `Searched ${app}`,
+        send: `Sent with ${app}`,
+        create: `Created in ${app}`,
+        update: `Changed in ${app}`,
+        remove: `Removed in ${app}`,
+        use: `Used ${app}`,
+      }[verb];
+      return would && verb !== "search"
+        ? `Would have ${done.charAt(0).toLowerCase()}${done.slice(1)}`
+        : done;
+    },
+    ai: "Used AI",
+    notify: (would) => (would ? "Would have told you in the inbox" : "Told you in the inbox"),
+    send: (channel, to, would) => {
+      const what =
+        { whatsapp: "a WhatsApp", sms: "an SMS", instagram: "an Instagram message" }[
+          channel ?? ""
+        ] ?? "a message";
+      const sent = `${what} to ${to || "a contact"}`;
+      return would ? `Would have sent ${sent}` : `Sent ${sent}`;
+    },
+    start: (would) => (would ? "Would have opened a conversation" : "Opened a conversation"),
+    find: (table) => `Looked up ${table}`,
+    add: (table, would) =>
+      would ? `Would have added a row to ${table}` : `Added a row to ${table}`,
+    change: (table, would) =>
+      would ? `Would have changed a row of ${table}` : `Changed a row of ${table}`,
+    http: (host, would) => (would ? `Would have called ${host}` : `Called ${host}`),
+    files: "Searched the files",
+    read: (file) => `Read ${file}`,
+    wrote: (file, would) => (would ? `Would have saved ${file}` : `Saved ${file}`),
+    listed: "Looked through its files",
+    remember: (would) => (would ? "Would have kept a memory" : "Kept a memory"),
+    recall: "Searched what it learned",
+  },
+};