wizards 0.4.0 → 0.4.2

package/modules/sms/src/plugin.ts

@@ -1,329 +0,0 @@
-import { definePlugin, type PluginRequest } from "@engenty-wizards/plugin-sdk";
-import {
-  freshThreadState,
-  type Thread,
-  ThreadDoor,
-  type ThreadInbound,
-  type ThreadWizard,
-} from "@engenty-wizards/plugin-sdk/thread";
-import { z } from "zod";
-import {
-  dropAccount,
-  getAccount,
-  keywordOf,
-  keywords,
-  loadThread,
-  putAccount,
-  saveThread,
-  setKeyword,
-  smsLink,
-  threadByRun,
-} from "./store";
-import { ASKS, RUNNER, smsSurface } from "./surface";
-import { e164, parseInbound, signatureOk, Twilio, TwilioError } from "./twilio";
-
-/**
- * SMS as a door: the tenant connects its Twilio account and number, the owner switches the
- * runner on per wizard and gets a keyword; a person texts the keyword to the number and runs
- * the wizard in texts. The conversation itself is the SDK's thread door (surface.ts says how
- * it reads as text); this file is the webhook, the rows and the studio's routes. The studio
- * half is ui/plugin.tsx.
- */
-
-const fail = (status: number, code: string, message: string): never => {
-  throw Object.assign(new Error(message), { status, code });
-};
-
-/** An empty TwiML answer: Twilio expects one, and sends nothing of its own. */
-const TWIML = new Response('<?xml version="1.0" encoding="UTF-8"?><Response></Response>', {
-  headers: { "content-type": "text/xml" },
-});
-
-const accountInput = z.object({
-  accountSid: z.string().trim().min(1).max(60),
-  number: z.string().trim().min(5).max(20),
-  authToken: z.string().trim().max(200).optional(),
-});
-
-export default definePlugin((wizards) => {
-  const { server, log } = wizards;
-  const db = () => server.getTenantDb();
-
-  server.registerMigrations("migrations");
-
-  // One turn per thread at a time: a webhook, a run's signal and a retry never interleave.
-  const turns = new Map<string, Promise<void>>();
-  function turn(key: string, work: () => Promise<void>): Promise<void> {
-    const next = (turns.get(key) ?? Promise.resolve())
-      .catch(() => undefined)
-      .then(work)
-      .catch((err) => log.error(`thread ${key}:`, err));
-    turns.set(key, next);
-    void next.finally(() => {
-      if (turns.get(key) === next) {
-        turns.delete(key);
-      }
-    });
-    return next;
-  }
-
-  const watching = new Map<string, () => void>();
-  const timers = new Map<string, ReturnType<typeof setTimeout>>();
-
-  /** The wizards switched on for SMS, each with its keyword. */
-  async function offered(): Promise<ThreadWizard[]> {
-    const on = await server.runs.wizards(RUNNER);
-    const words = await keywords(db());
-    return Promise.all(
-      on.map(async (w) => ({
-        ...w,
-        keyword: words.get(w.wizardId) ?? (await keywordOf(db(), w.wizardId, w.title)),
-      })),
-    );
-  }
-
-  const door = new ThreadDoor({
-    runs: server.runs,
-    surface: smsSurface({ account: () => getAccount(db()) }),
-    offered,
-    watch(thread) {
-      const runId = thread.runId;
-      if (!runId || watching.has(runId)) {
-        return;
-      }
-      const { id } = thread;
-      const stop = server.runs.subscribe(runId, (signal) => {
-        if (signal.event && signal.event.type !== "step_done" && signal.event.type !== "error") {
-          return;
-        }
-        clearTimeout(timers.get(runId));
-        timers.set(
-          runId,
-          setTimeout(() => {
-            timers.delete(runId);
-            void turn(id, () => resume(id));
-          }, 300),
-        );
-      });
-      watching.set(runId, stop);
-    },
-    unwatch(runId) {
-      watching.get(runId)?.();
-      watching.delete(runId);
-      clearTimeout(timers.get(runId));
-      timers.delete(runId);
-    },
-    log,
-  });
-  server.onUnload(() => {
-    for (const stop of watching.values()) {
-      stop();
-    }
-    watching.clear();
-    for (const timer of timers.values()) {
-      clearTimeout(timer);
-    }
-  });
-
-  async function handle(msg: ThreadInbound): Promise<void> {
-    const thread: Thread = (await loadThread(db(), msg.from)) ?? {
-      id: msg.from,
-      name: null,
-      runId: null,
-      state: freshThreadState(),
-      lastInboundAt: msg.at,
-      lastMessageId: null,
-    };
-    if (thread.lastMessageId === msg.id) {
-      // Twilio posts again when the answer was slow: the message was dealt with.
-      return;
-    }
-    thread.lastMessageId = msg.id;
-    thread.lastInboundAt = Math.max(thread.lastInboundAt, msg.at);
-    try {
-      await door.inbound(thread, msg);
-    } finally {
-      await saveThread(db(), thread);
-    }
-  }
-
-  async function resume(id: string): Promise<void> {
-    const thread = await loadThread(db(), id);
-    if (!thread) {
-      return;
-    }
-    try {
-      await door.resume(thread);
-    } finally {
-      await saveThread(db(), thread);
-    }
-  }
-
-  // ── The door ───────────────────────────────────────────────────────────────
-
-  server.registerRunner({
-    id: RUNNER,
-    label: { de: "SMS", en: "SMS" },
-    kind: "channel",
-    capabilities: {
-      input: ASKS,
-      output: { shows: ["text", "data"], pictures: [] },
-      asks: ["confirm"],
-      review: ["accept", "regenerate"],
-      waits: true,
-      handoff: ["sms"],
-    },
-    problem: async () =>
-      (await getAccount(db())) ? null : "Keine Nummer verbunden (Einstellungen → SMS)",
-    // The share dialog's row: the number, the keyword and the link that writes it.
-    address: async (wizard) => {
-      const b = await bindingView(wizard.id);
-      return b.number ? { number: b.number, keyword: b.keyword, link: b.link } : null;
-    },
-  });
-
-  // What people text: Twilio posts a form; answered with empty TwiML, dealt with in the thread's turn.
-  server.registerPublicRoute({
-    method: "POST",
-    path: "/webhook",
-    handler: async ({ request }) => {
-      const account = await getAccount(db());
-      if (!account) {
-        return TWIML.clone();
-      }
-      const form = new URLSearchParams(await request.text());
-      const urls = [await server.publicUrl("/webhook"), request.url];
-      if (!signatureOk(account.authToken, urls, form, request.headers.get("x-twilio-signature"))) {
-        return fail(403, "bad_signature", "The signature does not match.");
-      }
-      const msg = parseInbound(form);
-      if (msg) {
-        void turn(msg.from, () => handle(msg));
-      }
-      return TWIML.clone();
-    },
-  });
-
-  // A run that ended while nobody listened (the runtime was restarted): told on its own.
-  for (const event of ["run.done", "run.failed"] as const) {
-    server.on(event, async ({ run }) => {
-      if (run.mode !== "live") {
-        return;
-      }
-      const thread = await threadByRun(db(), run.id);
-      if (thread && !thread.state.delivered) {
-        await turn(thread.id, () => resume(thread.id));
-      }
-    });
-  }
-
-  // ── The studio's side ──────────────────────────────────────────────────────
-
-  const admin = (request: PluginRequest) => {
-    if (request.user.role === "member") {
-      fail(403, "forbidden", "Owners and admins only.");
-    }
-  };
-
-  async function accountView() {
-    const account = await getAccount(db());
-    return {
-      connected: Boolean(account),
-      accountSid: account?.accountSid ?? "",
-      number: account?.number ?? "",
-      hasToken: Boolean(account?.authToken),
-      webhook: await server.publicUrl("/webhook"),
-    };
-  }
-
-  server.registerHttpRoute({
-    method: "GET",
-    path: "/account",
-    role: "admin",
-    handler: accountView,
-  });
-
-  server.registerHttpRoute({
-    method: "PUT",
-    path: "/account",
-    role: "admin",
-    handler: async (request) => {
-      admin(request);
-      const parsed = accountInput.safeParse(await request.json());
-      if (!parsed.success) {
-        return fail(400, "invalid", parsed.error.issues[0]?.message ?? "invalid");
-      }
-      await putAccount(db(), parsed.data);
-      return accountView();
-    },
-  });
-
-  server.registerHttpRoute({
-    method: "DELETE",
-    path: "/account",
-    role: "admin",
-    handler: async (request) => {
-      admin(request);
-      await dropAccount(db());
-      return accountView();
-    },
-  });
-
-  // A text to a number of one's own: the account and the number are right when it arrives.
-  server.registerHttpRoute({
-    method: "POST",
-    path: "/account/test",
-    role: "admin",
-    handler: async (request) => {
-      admin(request);
-      const account = await getAccount(db());
-      if (!account) {
-        return fail(409, "not_connected", "No number is connected.");
-      }
-      const { to } = (await request.json()) as { to?: string };
-      const number = e164(String(to ?? ""));
-      if (number.length < 6) {
-        return fail(400, "invalid", "A number with its country code.");
-      }
-      try {
-        const id = await new Twilio(account).send(number, "✓ engenty wizards");
-        return { ok: true, id };
-      } catch (err) {
-        return fail(
-          502,
-          "provider",
-          err instanceof TwilioError ? err.message : "The text was not sent.",
-        );
-      }
-    },
-  });
-
-  // The keyword a wizard answers to, and the link that types it.
-  async function bindingView(wizardId: string) {
-    const account = await getAccount(db());
-    const on = await server.runs.wizards(RUNNER);
-    const title = on.find((w) => w.wizardId === wizardId)?.title ?? "wizard";
-    const keyword = await keywordOf(db(), wizardId, title);
-    return {
-      keyword,
-      link: account ? smsLink(account.number, keyword) : null,
-      number: account?.number ?? null,
-    };
-  }
-
-  server.registerHttpRoute({
-    method: "GET",
-    path: "/binding/:wizardId",
-    handler: ({ params }) => bindingView(params.wizardId),
-  });
-
-  server.registerHttpRoute({
-    method: "PUT",
-    path: "/binding/:wizardId",
-    handler: async (request) => {
-      const { keyword } = (await request.json()) as { keyword?: string };
-      await setKeyword(db(), request.params.wizardId, String(keyword ?? ""));
-      return bindingView(request.params.wizardId);
-    },
-  });
-});

package/modules/sms/src/schema.ts

@@ -1,26 +0,0 @@
-import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
-
-/** The tables of migrations/, for Drizzle. Kept in step with the SQL by hand. */
-
-export const account = sqliteTable("sms_account", {
-  id: integer("id").primaryKey(),
-  accountSid: text("account_sid").notNull(),
-  authToken: text("auth_token").notNull(),
-  /** The number people text, as E.164: +43660… */
-  number: text("number").notNull(),
-  updatedAt: integer("updated_at", { mode: "timestamp_ms" }).notNull(),
-});
-
-export const binding = sqliteTable("sms_binding", {
-  wizardId: text("wizard_id").primaryKey(),
-  keyword: text("keyword").notNull(),
-});
-
-export const thread = sqliteTable("sms_thread", {
-  number: text("number").primaryKey(),
-  runId: text("run_id"),
-  state: text("state").notNull(),
-  lastInboundAt: integer("last_inbound_at", { mode: "timestamp_ms" }).notNull(),
-  lastMessageId: text("last_message_id"),
-  updatedAt: integer("updated_at", { mode: "timestamp_ms" }).notNull(),
-});

package/modules/sms/src/store.ts

@@ -1,140 +0,0 @@
-import type { PluginDb } from "@engenty-wizards/plugin-sdk";
-import type { Thread, ThreadState } from "@engenty-wizards/plugin-sdk/thread";
-import { eq } from "drizzle-orm";
-import { account, binding, thread } from "./schema";
-import { type Account, e164 } from "./twilio";
-
-/** The plugin's rows: the account, the keywords, the threads. */
-
-export async function getAccount(db: PluginDb): Promise<Account | null> {
-  const [row] = await db.select().from(account).where(eq(account.id, 1));
-  return row ? { accountSid: row.accountSid, authToken: row.authToken, number: row.number } : null;
-}
-
-export interface AccountInput {
-  accountSid: string;
-  number: string;
-  /** Left out: the token stays as it is. */
-  authToken?: string;
-}
-
-export async function putAccount(db: PluginDb, input: AccountInput): Promise<Account> {
-  const before = await getAccount(db);
-  const authToken = input.authToken || before?.authToken;
-  if (!authToken) {
-    throw Object.assign(new Error("An auth token is needed."), { status: 400, code: "no_token" });
-  }
-  const next = {
-    accountSid: input.accountSid,
-    authToken,
-    number: e164(input.number),
-    updatedAt: new Date(),
-  };
-  await db
-    .insert(account)
-    .values({ id: 1, ...next })
-    .onConflictDoUpdate({ target: account.id, set: next });
-  return { accountSid: next.accountSid, authToken, number: next.number };
-}
-
-export async function dropAccount(db: PluginDb): Promise<void> {
-  await db.delete(account).where(eq(account.id, 1));
-}
-
-// ── Keywords ────────────────────────────────────────────────────────────────
-
-export const KEYWORD = /^[\p{L}\p{N}][\p{L}\p{N} _-]{0,38}$/u;
-
-/** The keyword of every bound wizard, by wizard id. */
-export async function keywords(db: PluginDb): Promise<Map<string, string>> {
-  const rows = await db.select().from(binding);
-  return new Map(rows.map((r) => [r.wizardId, r.keyword]));
-}
-
-/** The wizard's keyword, made from its title the first time it is asked for. */
-export async function keywordOf(db: PluginDb, wizardId: string, title: string): Promise<string> {
-  const all = await keywords(db);
-  const own = all.get(wizardId);
-  if (own) {
-    return own;
-  }
-  const taken = new Set([...all.values()].map((k) => k.toLowerCase()));
-  const base =
-    title
-      .toLowerCase()
-      .replace(/[^\p{L}\p{N}]+/gu, " ")
-      .trim()
-      .split(" ")[0]
-      ?.slice(0, 30) || "wizard";
-  let keyword = base;
-  for (let n = 2; taken.has(keyword); n++) {
-    keyword = `${base}${n}`;
-  }
-  await db.insert(binding).values({ wizardId, keyword }).onConflictDoNothing();
-  return (await keywords(db)).get(wizardId) ?? keyword;
-}
-
-export async function setKeyword(db: PluginDb, wizardId: string, keyword: string): Promise<string> {
-  const clean = keyword.trim().replace(/\s+/g, " ");
-  if (!KEYWORD.test(clean)) {
-    throw Object.assign(new Error("A keyword is letters, digits, spaces and dashes, up to 40."), {
-      status: 400,
-      code: "bad_keyword",
-    });
-  }
-  const other = [...(await keywords(db))].find(
-    ([id, k]) => id !== wizardId && k.toLowerCase() === clean.toLowerCase(),
-  );
-  if (other) {
-    throw Object.assign(new Error("Another wizard has this keyword."), {
-      status: 409,
-      code: "keyword_taken",
-    });
-  }
-  await db
-    .insert(binding)
-    .values({ wizardId, keyword: clean })
-    .onConflictDoUpdate({ target: binding.wizardId, set: { keyword: clean } });
-  return clean;
-}
-
-/** The link that opens the phone's messages with the keyword typed (RFC 5724). */
-export const smsLink = (number: string, keyword: string) =>
-  `sms:${number}?body=${encodeURIComponent(keyword)}`;
-
-// ── Threads ─────────────────────────────────────────────────────────────────
-
-function rowToThread(row: typeof thread.$inferSelect): Thread {
-  return {
-    id: row.number,
-    name: null,
-    runId: row.runId,
-    state: JSON.parse(row.state) as ThreadState,
-    lastInboundAt: row.lastInboundAt.getTime(),
-    lastMessageId: row.lastMessageId,
-  };
-}
-
-export async function loadThread(db: PluginDb, number: string): Promise<Thread | null> {
-  const [row] = await db.select().from(thread).where(eq(thread.number, number));
-  return row ? rowToThread(row) : null;
-}
-
-export async function threadByRun(db: PluginDb, runId: string): Promise<Thread | null> {
-  const [row] = await db.select().from(thread).where(eq(thread.runId, runId));
-  return row ? rowToThread(row) : null;
-}
-
-export async function saveThread(db: PluginDb, t: Thread): Promise<void> {
-  const next = {
-    runId: t.runId,
-    state: JSON.stringify(t.state),
-    lastInboundAt: new Date(t.lastInboundAt),
-    lastMessageId: t.lastMessageId,
-    updatedAt: new Date(),
-  };
-  await db
-    .insert(thread)
-    .values({ number: t.id, ...next })
-    .onConflictDoUpdate({ target: thread.number, set: next });
-}

package/modules/sms/src/surface.ts

@@ -1,70 +0,0 @@
-import {
-  clipText,
-  type Thread,
-  type ThreadLang,
-  type ThreadPrompt,
-  type ThreadSurface,
-} from "@engenty-wizards/plugin-sdk/thread";
-import { type Account, Twilio } from "./twilio";
-
-/**
- * SMS as a surface of the thread door: text only. A question with options is numbered lines
- * and the person answers with the number; a place is an address typed; every picture and
- * file is a link; a long text is its gist, the link at the end has the rest.
- */
-
-export const RUNNER = "sms";
-
-/** The field kinds a text can answer; a photo, a file or a signature hands the page to the screen. */
-export const ASKS = [
-  "text",
-  "textarea",
-  "number",
-  "select",
-  "multiselect",
-  "date",
-  "email",
-  "url",
-  "toggle",
-  "location",
-];
-
-/** How long a text may be before its gist goes out instead: a few segments. */
-const GIST = 600;
-
-const hints = {
-  de: { one: "Antwort: die Nummer", many: "Antwort: die Nummern, mit Komma getrennt" },
-  en: { one: "Reply with the number", many: "Reply with the numbers, separated by commas" },
-};
-
-/** What the door says, as one text. */
-export function toText(prompt: ThreadPrompt, lang: ThreadLang): string {
-  switch (prompt.kind) {
-    case "text":
-      return clipText(prompt.text, GIST);
-    case "choice": {
-      const lines = prompt.options.map((o, i) => `${i + 1}. ${o.picked ? "✓ " : ""}${o.title}`);
-      return `${clipText(prompt.text, GIST)}\n\n${lines.join("\n")}\n\n${hints[lang][prompt.multiple ? "many" : "one"]}`;
-    }
-    case "location":
-      return clipText(prompt.text, GIST);
-    case "link":
-      return `${clipText(prompt.text, GIST)}\n${prompt.url}`;
-    case "media":
-      return `${prompt.caption ?? prompt.filename ?? prompt.media}: ${prompt.url}`;
-  }
-}
-
-export function smsSurface(deps: { account: () => Promise<Account | null> }): ThreadSurface {
-  return {
-    runner: RUNNER,
-    asks: ASKS,
-    async send(thread: Thread, prompt: ThreadPrompt) {
-      const account = await deps.account();
-      if (!account) {
-        throw new Error("SMS is not connected.");
-      }
-      await new Twilio(account).send(thread.id, toText(prompt, thread.state.lang));
-    },
-  };
-}

package/modules/sms/src/twilio.ts

@@ -1,130 +0,0 @@
-import { createHmac, timingSafeEqual } from "node:crypto";
-import type { ThreadInbound } from "@engenty-wizards/plugin-sdk/thread";
-
-/**
- * Twilio's messaging API, the part this plugin uses: sending a text to a number, reading
- * what Twilio posts when one arrives, and checking that it was Twilio who posted it.
- */
-
-export const API = "https://api.twilio.com/2010-04-01";
-
-export interface Account {
-  accountSid: string;
-  authToken: string;
-  /** E.164: +43660… */
-  number: string;
-}
-
-/** A text may hold up to 1600 characters over several segments; longer is cut. */
-export const TEXT_LIMIT = 1500;
-
-export class TwilioError extends Error {
-  constructor(
-    message: string,
-    readonly status: number,
-    readonly code: number | null,
-  ) {
-    super(message);
-    this.name = "TwilioError";
-  }
-}
-
-/** A number as Twilio and the person's phone write it: +, then digits. */
-export function e164(raw: string): string {
-  const digits = raw.replace(/[^\d+]/g, "");
-  return digits.startsWith("+") ? `+${digits.slice(1).replace(/\+/g, "")}` : `+${digits}`;
-}
-
-export class Twilio {
-  constructor(
-    private readonly account: Account,
-    private readonly fetchImpl: typeof fetch = (...args) => globalThis.fetch(...args),
-  ) {}
-
-  /** Sends one text; gives the message's sid. */
-  async send(to: string, body: string): Promise<string | null> {
-    const form = new URLSearchParams({
-      To: to,
-      From: this.account.number,
-      Body: body.length > TEXT_LIMIT ? `${body.slice(0, TEXT_LIMIT - 1)}…` : body,
-    });
-    const res = await this.fetchImpl(
-      `${API}/Accounts/${encodeURIComponent(this.account.accountSid)}/Messages.json`,
-      {
-        method: "POST",
-        headers: {
-          authorization: `Basic ${Buffer.from(`${this.account.accountSid}:${this.account.authToken}`).toString("base64")}`,
-          "content-type": "application/x-www-form-urlencoded",
-        },
-        body: form.toString(),
-        signal: AbortSignal.timeout(20_000),
-      },
-    );
-    const text = await res.text();
-    let parsed: Record<string, unknown> = {};
-    try {
-      parsed = text ? (JSON.parse(text) as Record<string, unknown>) : {};
-    } catch {
-      parsed = {};
-    }
-    if (!res.ok) {
-      throw new TwilioError(
-        typeof parsed.message === "string" ? parsed.message : `Twilio answered ${res.status}.`,
-        res.status,
-        typeof parsed.code === "number" ? parsed.code : null,
-      );
-    }
-    return typeof parsed.sid === "string" ? parsed.sid : null;
-  }
-}
-
-/**
- * `X-Twilio-Signature` is the HMAC-SHA1, base64, of the address Twilio posted to with every
- * form field appended, sorted by name, each as name then value.
- */
-export function signatureOf(authToken: string, url: string, form: URLSearchParams): string {
-  const names = [...new Set(form.keys())].sort();
-  const data = names.reduce((acc, name) => acc + name + form.getAll(name).join(""), url);
-  return createHmac("sha1", authToken).update(data, "utf8").digest("base64");
-}
-
-export function signatureOk(
-  authToken: string,
-  urls: string[],
-  form: URLSearchParams,
-  header: string | null,
-): boolean {
-  if (!header) {
-    return false;
-  }
-  const given = Buffer.from(header);
-  return urls.some((url) => {
-    const expected = Buffer.from(signatureOf(authToken, url, form));
-    return expected.length === given.length && timingSafeEqual(expected, given);
-  });
-}
-
-/** What Twilio posted, as the thread door reads a message. Null for a status callback. */
-export function parseInbound(form: URLSearchParams): ThreadInbound | null {
-  const id = form.get("MessageSid") || form.get("SmsSid");
-  const from = form.get("From");
-  if (!id || !from || form.get("MessageStatus")) {
-    return null;
-  }
-  const body = (form.get("Body") ?? "").trim();
-  const count = Number(form.get("NumMedia") ?? 0) || 0;
-  const first = count ? form.get("MediaUrl0") : null;
-  const mime = count ? (form.get("MediaContentType0") ?? "application/octet-stream") : "";
-  const base = { id, from, name: form.get("ProfileName") || null, at: Date.now() };
-  if (first) {
-    const kind = mime.startsWith("image/")
-      ? "image"
-      : mime.startsWith("video/")
-        ? "video"
-        : mime.startsWith("audio/")
-          ? "audio"
-          : "document";
-    return { ...base, kind, media: { id: first, mime, caption: body || undefined }, text: body };
-  }
-  return { ...base, kind: "text", text: body };
-}