wizards 0.4.1 → 0.4.2

package/modules/whatsapp/src/plugin.ts

@@ -1,374 +0,0 @@
-import { definePlugin, type PluginRequest } from "@engenty-wizards/plugin-sdk";
-import {
-  freshThreadState,
-  type Thread,
-  ThreadDoor,
-  type ThreadWizard,
-} from "@engenty-wizards/plugin-sdk/thread";
-import { z } from "zod";
-import { Graph, GraphError } from "./graph";
-import { type Inbound, parseWebhook, signatureOk } from "./inbound";
-import {
-  dropAccount,
-  getAccount,
-  keywordOf,
-  keywords,
-  loadThread,
-  putAccount,
-  saveThread,
-  setKeyword,
-  threadByRun,
-  waLink,
-} from "./store";
-import { ASKS, RUNNER, whatsappSurface } from "./surface";
-
-/**
- * WhatsApp as a door: the tenant connects its business number (Meta's Cloud API), the owner
- * switches the runner on per wizard and gets a keyword; a person writes the keyword to the
- * number and runs the wizard in the thread. The conversation itself is the SDK's thread door
- * (surface.ts says how it looks on WhatsApp); 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 });
-};
-
-const accountInput = z.object({
-  phoneNumberId: z.string().trim().min(1).max(40),
-  number: z.string().trim().min(5).max(20),
-  accessToken: z.string().trim().max(1000).optional(),
-  appSecret: z.string().trim().max(200).nullable().optional(),
-  template: z.string().trim().max(512).nullable().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;
-  }
-
-  // The runs the threads listen to, with what stops the listening.
-  const watching = new Map<string, () => void>();
-  const timers = new Map<string, ReturnType<typeof setTimeout>>();
-
-  /** The wizards switched on for WhatsApp, 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: whatsappSurface({ account: () => getAccount(db()), log }),
-    offered,
-    watch(thread) {
-      const runId = thread.runId;
-      if (!runId || watching.has(runId)) {
-        return;
-      }
-      const { id } = thread;
-      const stop = server.runs.subscribe(runId, (signal) => {
-        // Only a step that ended or a change of status moves the thread; a burst is one look.
-        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: Inbound): Promise<void> {
-    const thread: Thread = (await loadThread(db(), msg.from)) ?? {
-      id: msg.from,
-      name: msg.name,
-      runId: null,
-      state: freshThreadState(),
-      lastInboundAt: msg.at,
-      lastMessageId: null,
-    };
-    if (thread.lastMessageId === msg.id) {
-      // Meta posts a webhook again when the answer was slow: the message was dealt with.
-      return;
-    }
-    thread.lastMessageId = msg.id;
-    thread.lastInboundAt = Math.max(thread.lastInboundAt, msg.at);
-    if (msg.name) {
-      thread.name = msg.name;
-    }
-    // The two ticks turn blue while the answer is worked out.
-    void getAccount(db())
-      .then((account) => (account ? new Graph(account).markRead(msg.id) : undefined))
-      .catch(() => undefined);
-    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: "WhatsApp", en: "WhatsApp" },
-    kind: "channel",
-    capabilities: {
-      input: ASKS,
-      output: {
-        shows: ["text", "data", "image", "video", "voice", "document", "film"],
-        pictures: ["dashboard", "widget"],
-      },
-      asks: ["confirm"],
-      review: ["accept", "regenerate"],
-      waits: true,
-      handoff: ["thread"],
-    },
-    problem: async () =>
-      (await getAccount(db())) ? null : "Keine Nummer verbunden (Einstellungen → WhatsApp)",
-    // 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;
-    },
-  });
-
-  // Meta checks the address once, with the verify token the settings show.
-  server.registerPublicRoute({
-    method: "GET",
-    path: "/webhook",
-    handler: async ({ query }) => {
-      const account = await getAccount(db());
-      if (
-        account &&
-        query.get("hub.mode") === "subscribe" &&
-        query.get("hub.verify_token") === account.verifyToken
-      ) {
-        return new Response(query.get("hub.challenge") ?? "", {
-          status: 200,
-          headers: { "content-type": "text/plain" },
-        });
-      }
-      return fail(403, "forbidden", "The verify token does not match.");
-    },
-  });
-
-  // What people write: answered at once, dealt with in the thread's own turn.
-  server.registerPublicRoute({
-    method: "POST",
-    path: "/webhook",
-    handler: async ({ request }) => {
-      const account = await getAccount(db());
-      if (!account) {
-        return { ok: true };
-      }
-      const raw = await request.text();
-      if (
-        account.appSecret &&
-        !signatureOk(account.appSecret, raw, request.headers.get("x-hub-signature-256"))
-      ) {
-        return fail(403, "bad_signature", "The signature does not match.");
-      }
-      let body: unknown;
-      try {
-        body = JSON.parse(raw);
-      } catch {
-        return fail(400, "bad_body", "Not JSON.");
-      }
-      for (const msg of parseWebhook(body)) {
-        if (msg.phoneNumberId && msg.phoneNumberId !== account.phoneNumberId) {
-          continue;
-        }
-        void turn(msg.from, () => handle(msg));
-      }
-      return { ok: true };
-    },
-  });
-
-  // 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),
-      phoneNumberId: account?.phoneNumberId ?? "",
-      number: account?.number ?? "",
-      hasToken: Boolean(account?.accessToken),
-      hasSecret: Boolean(account?.appSecret),
-      template: account?.template ?? "",
-      verifyToken: account?.verifyToken ?? null,
-      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 word to a number of one's own: the token and the number id 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 = String(to ?? "").replace(/\D/g, "");
-      if (number.length < 5) {
-        return fail(400, "invalid", "A number with its country code.");
-      }
-      try {
-        const id = await new Graph(account).send(number, {
-          type: "text",
-          text: "✓ engenty wizards",
-        });
-        return { ok: true, id };
-      } catch (err) {
-        return fail(
-          502,
-          "provider",
-          err instanceof GraphError ? err.message : "The message was not sent.",
-        );
-      }
-    },
-  });
-
-  // The keyword a wizard answers to, and the link that writes 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 ? waLink(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/whatsapp/src/schema.ts

@@ -1,32 +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("whatsapp_account", {
-  id: integer("id").primaryKey(),
-  phoneNumberId: text("phone_number_id").notNull(),
-  /** Digits only: the number people write to, for `wa.me` links. */
-  number: text("number").notNull(),
-  accessToken: text("access_token").notNull(),
-  /** The Meta app's secret: with it, every webhook's signature is checked. */
-  appSecret: text("app_secret"),
-  verifyToken: text("verify_token").notNull(),
-  /** An approved utility template with one body parameter (the link), for a word after a day of silence. */
-  template: text("template"),
-  updatedAt: integer("updated_at", { mode: "timestamp_ms" }).notNull(),
-});
-
-export const binding = sqliteTable("whatsapp_binding", {
-  wizardId: text("wizard_id").primaryKey(),
-  keyword: text("keyword").notNull(),
-});
-
-export const thread = sqliteTable("whatsapp_thread", {
-  waId: text("wa_id").primaryKey(),
-  name: text("name"),
-  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/whatsapp/src/store.ts

@@ -1,156 +0,0 @@
-import { randomBytes } from "node:crypto";
-import type { PluginDb } from "@engenty-wizards/plugin-sdk";
-import type { Thread, ThreadState } from "@engenty-wizards/plugin-sdk/thread";
-import { eq } from "drizzle-orm";
-import type { Account } from "./graph";
-import { account, binding, thread } from "./schema";
-
-/** The plugin's rows: the number, 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
-    ? {
-        phoneNumberId: row.phoneNumberId,
-        number: row.number,
-        accessToken: row.accessToken,
-        appSecret: row.appSecret,
-        verifyToken: row.verifyToken,
-        template: row.template,
-      }
-    : null;
-}
-
-export interface AccountInput {
-  phoneNumberId: string;
-  number: string;
-  /** Left out: the token stays as it is. */
-  accessToken?: string;
-  appSecret?: string | null;
-  template?: string | null;
-}
-
-export async function putAccount(db: PluginDb, input: AccountInput): Promise<Account> {
-  const before = await getAccount(db);
-  const accessToken = input.accessToken || before?.accessToken;
-  if (!accessToken) {
-    throw Object.assign(new Error("An access token is needed."), { status: 400, code: "no_token" });
-  }
-  const next = {
-    phoneNumberId: input.phoneNumberId,
-    number: input.number.replace(/\D/g, ""),
-    accessToken,
-    appSecret:
-      input.appSecret === undefined ? (before?.appSecret ?? null) : input.appSecret || null,
-    verifyToken: before?.verifyToken ?? randomBytes(18).toString("base64url"),
-    template: input.template === undefined ? (before?.template ?? null) : input.template || null,
-    updatedAt: new Date(),
-  };
-  await db
-    .insert(account)
-    .values({ id: 1, ...next })
-    .onConflictDoUpdate({ target: account.id, set: next });
-  return { ...next };
-}
-
-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;
-}
-
-export const waLink = (number: string, keyword: string) =>
-  `https://wa.me/${number}?text=${encodeURIComponent(keyword)}`;
-
-// ── Threads ─────────────────────────────────────────────────────────────────
-
-function rowToThread(row: typeof thread.$inferSelect): Thread {
-  return {
-    id: row.waId,
-    name: row.name,
-    runId: row.runId,
-    state: JSON.parse(row.state) as ThreadState,
-    lastInboundAt: row.lastInboundAt.getTime(),
-    lastMessageId: row.lastMessageId,
-  };
-}
-
-export async function loadThread(db: PluginDb, waId: string): Promise<Thread | null> {
-  const [row] = await db.select().from(thread).where(eq(thread.waId, waId));
-  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 = {
-    name: t.name,
-    runId: t.runId,
-    state: JSON.stringify(t.state),
-    lastInboundAt: new Date(t.lastInboundAt),
-    lastMessageId: t.lastMessageId,
-    updatedAt: new Date(),
-  };
-  await db
-    .insert(thread)
-    .values({ waId: t.id, ...next })
-    .onConflictDoUpdate({ target: thread.waId, set: next });
-}

package/modules/whatsapp/src/surface.ts

@@ -1,127 +0,0 @@
-import type { Thread, ThreadPrompt, ThreadSurface } from "@engenty-wizards/plugin-sdk/thread";
-import { type Account, Graph, GraphError, LIMITS, type Outgoing, RE_ENGAGEMENT } from "./graph";
-
-/**
- * WhatsApp as a surface of the thread door: a question with up to three short options is
- * buttons, with up to ten a list, beyond that numbered lines; a place is the "send location"
- * button; files come through the Cloud API; after a day of silence only a template goes out.
- */
-
-export const RUNNER = "whatsapp";
-
-/** The field kinds the thread asks itself; any other on a page hands the page to the screen. */
-export const ASKS = [
-  "text",
-  "textarea",
-  "number",
-  "select",
-  "multiselect",
-  "date",
-  "email",
-  "url",
-  "toggle",
-  "image",
-  "file",
-  "location",
-  "audio",
-];
-
-const DAY = 24 * 3600_000;
-
-/** What the door says, as a message of the Cloud API. */
-export function toOutgoing(prompt: ThreadPrompt): Outgoing {
-  switch (prompt.kind) {
-    case "text":
-      return { type: "text", text: prompt.text };
-    case "choice": {
-      // Of a multiple choice the picked options are left out; their ids keep their numbers.
-      const options = prompt.options.filter((o) => !o.picked);
-      if (
-        options.length <= LIMITS.buttons &&
-        options.every((o) => o.title.length <= LIMITS.buttonTitle)
-      ) {
-        return {
-          type: "buttons",
-          text: prompt.text,
-          buttons: options.map((o) => ({ id: o.id, title: o.title })),
-        };
-      }
-      if (options.length <= LIMITS.rows) {
-        return {
-          type: "list",
-          text: prompt.text,
-          button: prompt.button,
-          rows: options.map((o) => ({ id: o.id, title: o.title })),
-        };
-      }
-      return {
-        type: "text",
-        text: `${prompt.text}\n\n${prompt.options.map((o, i) => `${i + 1}. ${o.title}`).join("\n")}`,
-      };
-    }
-    case "location":
-      return { type: "location_request", text: prompt.text };
-    case "link":
-      return { type: "link", text: prompt.text, url: prompt.url, label: prompt.label };
-    case "media":
-      switch (prompt.media) {
-        case "image":
-          return { type: "image", link: prompt.url, caption: prompt.caption };
-        case "document":
-          return {
-            type: "document",
-            link: prompt.url,
-            caption: prompt.caption,
-            filename: prompt.filename,
-          };
-        case "video":
-          return { type: "video", link: prompt.url, caption: prompt.caption };
-        case "audio":
-          return { type: "audio", link: prompt.url };
-      }
-  }
-}
-
-export function whatsappSurface(deps: {
-  account: () => Promise<Account | null>;
-  log: { warn(...args: unknown[]): void };
-}): ThreadSurface {
-  const graph = async () => {
-    const account = await deps.account();
-    if (!account) {
-      throw new Error("WhatsApp is not connected.");
-    }
-    return new Graph(account);
-  };
-  return {
-    runner: RUNNER,
-    asks: ASKS,
-    async send(thread: Thread, prompt: ThreadPrompt) {
-      try {
-        await (await graph()).send(thread.id, toOutgoing(prompt));
-      } catch (err) {
-        if (err instanceof GraphError && err.code === RE_ENGAGEMENT) {
-          deps.log.warn(`thread ${thread.id}: older than a day, the message was refused`);
-          return;
-        }
-        throw err;
-      }
-    },
-    media: async (ref) => (await graph()).media(ref.id),
-    // A free message only within a day of the person's last one.
-    mayDeliver: (thread) => Date.now() - thread.lastInboundAt < DAY,
-    async reach(thread, url) {
-      const account = await deps.account();
-      if (!account?.template) {
-        return false;
-      }
-      await new Graph(account).send(thread.id, {
-        type: "template",
-        name: account.template,
-        lang: thread.state.lang,
-        params: [url],
-      });
-      return true;
-    },
-  };
-}

package/modules/whatsapp/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "jsx": "react-jsx",
-    "lib": ["ES2023", "DOM", "DOM.Iterable"],
-    "types": ["node"],
-    "noEmit": true
-  },
-  "include": ["src", "ui"]
-}