causly-server 0.0.0-stage → 1.5.0

package/tools/slackOps.js

@@ -0,0 +1,151 @@
+const SLACK_API = "https://slack.com/api";
+
+function getToken() {
+  const token = process.env.SLACK_BOT_TOKEN;
+  if (!token) {
+    throw new Error(
+      "SLACK_BOT_TOKEN not set. Run `npm run setup` to configure it, or add it manually to your .env file: SLACK_BOT_TOKEN=xoxb-..."
+    );
+  }
+  return token;
+}
+
+async function slackFetch(method, body = {}, useGet = false) {
+  const token = getToken();
+
+  let res;
+  if (useGet) {
+    const query = new URLSearchParams(
+      Object.entries(body).reduce((acc, [k, v]) => {
+        if (v !== undefined && v !== null) acc[k] = String(v);
+        return acc;
+      }, {})
+    ).toString();
+    res = await fetch(`${SLACK_API}/${method}${query ? `?${query}` : ""}`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+  } else {
+    res = await fetch(`${SLACK_API}/${method}`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json; charset=utf-8",
+      },
+      body: JSON.stringify(body),
+    });
+  }
+
+  const data = await res.json();
+  if (!data.ok) {
+    throw new Error(`Slack API error (${method}): ${data.error || "unknown_error"}`);
+  }
+  return data;
+}
+
+/** Look up a Slack user's info by user ID. */
+export async function slackGetUser({ user_id }) {
+  const data = await slackFetch("users.info", { user: user_id }, true);
+  const u = data.user;
+  return {
+    id: u.id,
+    name: u.name,
+    real_name: u.real_name,
+    display_name: u.profile?.display_name || null,
+    email: u.profile?.email || null,
+    is_bot: u.is_bot,
+    is_admin: u.is_admin || false,
+  };
+}
+
+/** List channels in the workspace. Paginates automatically up to `limit` total channels. */
+export async function slackListChannels({ limit = 100, types = "public_channel,private_channel" }) {
+  const channels = [];
+  let cursor;
+  do {
+    const data = await slackFetch(
+      "conversations.list",
+      { limit: Math.min(200, limit - channels.length), types, cursor },
+      true
+    );
+    channels.push(...data.channels);
+    cursor = data.response_metadata?.next_cursor || undefined;
+  } while (cursor && channels.length < limit);
+
+  return {
+    channels: channels.slice(0, limit).map((c) => ({
+      id: c.id,
+      name: c.name,
+      is_private: c.is_private,
+      is_archived: c.is_archived,
+      num_members: c.num_members,
+    })),
+  };
+}
+
+/** Get details of a single channel. */
+export async function slackGetChannel({ channel_id }) {
+  const data = await slackFetch("conversations.info", { channel: channel_id }, true);
+  const c = data.channel;
+  return {
+    id: c.id,
+    name: c.name,
+    is_private: c.is_private,
+    is_archived: c.is_archived,
+    topic: c.topic?.value || null,
+    purpose: c.purpose?.value || null,
+    num_members: c.num_members,
+  };
+}
+
+/** Read recent message history from a channel. */
+export async function slackReadMessages({ channel_id, limit = 20 }) {
+  const data = await slackFetch("conversations.history", { channel: channel_id, limit }, true);
+  return {
+    channel_id,
+    messages: data.messages.map((m) => ({
+      user: m.user || m.bot_id || "unknown",
+      text: m.text,
+      ts: m.ts,
+      thread_ts: m.thread_ts || null,
+      reply_count: m.reply_count || 0,
+    })),
+  };
+}
+
+/** Search messages across the workspace. Requires a user token with search:read scope; bot tokens generally can't search — this will surface a clear error if unsupported. */
+export async function slackSearchMessages({ query, count = 20 }) {
+  const data = await slackFetch("search.messages", { query, count }, true);
+  return {
+    query,
+    total: data.messages?.total || 0,
+    matches: (data.messages?.matches || []).map((m) => ({
+      channel: m.channel?.name || m.channel?.id,
+      user: m.username || m.user,
+      text: m.text,
+      ts: m.ts,
+      permalink: m.permalink,
+    })),
+  };
+}
+
+/** Post a message to a channel. HIGH risk — requires confirm: true. */
+export async function slackSendMessage({ channel_id, text, confirm }) {
+  const data = await slackFetch("chat.postMessage", { channel: channel_id, text });
+  return { channel: data.channel, ts: data.ts, sent: true };
+}
+
+/** Reply in a thread. HIGH risk — requires confirm: true. */
+export async function slackReplyThread({ channel_id, thread_ts, text, confirm }) {
+  const data = await slackFetch("chat.postMessage", {
+    channel: channel_id,
+    thread_ts,
+    text,
+  });
+  return { channel: data.channel, ts: data.ts, thread_ts, sent: true };
+}
+
+/** Create a new channel. HIGH risk — requires confirm: true. */
+export async function slackCreateChannel({ name, is_private = false, confirm }) {
+  const data = await slackFetch("conversations.create", { name, is_private });
+  return { id: data.channel.id, name: data.channel.name, is_private: data.channel.is_private, created: true };
+}

package/tools/statusOps.js

@@ -0,0 +1,104 @@
+// `causly-server status`: one screen with what is set up and what is waiting.
+import fs from "fs";
+import { SERVICES, serviceState } from "./services.js";
+import { CLIENTS, SERVER_NAME, clientConfigPath, readJson } from "./cliOps.js";
+import { dbPath } from "./store.js";
+import { latestBackup } from "./backupOps.js";
+import { checkForUpdate, updateMessage } from "./updateCheck.js";
+import { PACKS } from "../packs/registry.js";
+
+const CLIENT_LABEL = { claude: "Claude Desktop", cursor: "Cursor", windsurf: "Windsurf" };
+
+async function readData(dbFile, now) {
+  if (!fs.existsSync(dbFile)) return null;
+  let sqlite;
+  try {
+    sqlite = await import("node:sqlite");
+  } catch {
+    return { unavailable: true };
+  }
+  let db;
+  try {
+    db = new sqlite.DatabaseSync(dbFile, { readOnly: true });
+  } catch {
+    return { unavailable: true };
+  }
+  const one = (sql, ...args) => {
+    try {
+      return db.prepare(sql).get(...args);
+    } catch {
+      return null; // that pack has never been used, so its table does not exist yet
+    }
+  };
+  try {
+    const today = now.toISOString().slice(0, 10);
+    return {
+      companies: one("SELECT COUNT(*) AS n FROM companies")?.n ?? 0,
+      open_deals: one("SELECT COUNT(*) AS n FROM deals WHERE closed_at IS NULL")?.n ?? 0,
+      meetings: one("SELECT COUNT(*) AS n FROM meetings")?.n ?? 0,
+      open_actions: one("SELECT COUNT(*) AS n FROM action_items WHERE status = 'open'")?.n ?? 0,
+      overdue_actions: one("SELECT COUNT(*) AS n FROM action_items WHERE status = 'open' AND due_date IS NOT NULL AND due_date < ?", today)?.n ?? 0,
+      pending_reminders: one("SELECT COUNT(*) AS n FROM reminders WHERE status = 'pending'")?.n ?? 0,
+      overdue_reminders: one("SELECT COUNT(*) AS n FROM reminders WHERE status = 'pending' AND due_at <= ?", now.toISOString())?.n ?? 0,
+      next_reminder: one("SELECT title, due_at FROM reminders WHERE status = 'pending' ORDER BY due_at LIMIT 1") ?? null,
+    };
+  } finally {
+    db.close();
+  }
+}
+
+const ago = (ms, now) => {
+  const days = Math.floor((now - ms) / 86_400_000);
+  return days <= 0 ? "today" : days === 1 ? "yesterday" : `${days} days ago`;
+};
+
+export async function runStatus({ env = process.env, version, platform, home, dbFile = dbPath(), now = new Date(), fetch: fetchFn, checkUpdate = true } = {}) {
+  const where = { platform, home, env };
+  const lines = [`causly-server ${version}`, ""];
+
+  // editors
+  const editors = CLIENTS.map((c) => {
+    const { config } = readJson(clientConfigPath(c, where));
+    const entry = config.mcpServers?.[SERVER_NAME];
+    return entry ? { client: c, entry } : null;
+  }).filter(Boolean);
+  if (!editors.length) lines.push('Editors:   none yet. Run "causly-server init".');
+  for (const { client, entry } of editors) {
+    const requested = String(entry.env?.CAUSLY_TOOLSETS || "").split(",").map((s) => s.trim()).filter(Boolean);
+    const core = Object.keys(PACKS).filter((n) => PACKS[n].core);
+    const packs = requested.includes("all") ? Object.keys(PACKS).length : new Set([...core, ...requested.filter((n) => PACKS[n])]).size;
+    const workspace = entry.env?.CAUSLY_WORKSPACE ? `files limited to ${entry.env.CAUSLY_WORKSPACE}` : "file access not limited to a folder";
+    lines.push(`Editors:   ${CLIENT_LABEL[client]} (${packs} tool packs at startup; ${workspace})`);
+  }
+
+  // keys
+  const ready = SERVICES.filter((s) => serviceState(s, env).configured).map((s) => s.name);
+  const partial = SERVICES.filter((s) => serviceState(s, env).incomplete).map((s) => s.name);
+  lines.push(`Keys:      ${ready.length ? `${ready.length} ready (${ready.join(", ")})` : "none yet"}`);
+  if (partial.length) lines.push(`           incomplete: ${partial.join(", ")}`);
+  lines.push('           add or fix with "causly-server setup", test with "causly-server doctor --test"');
+
+  // data
+  const data = await readData(dbFile, now);
+  lines.push("");
+  if (!data) lines.push("Data:      nothing saved yet (pipeline, meetings and reminders appear here once used)");
+  else if (data.unavailable) lines.push("Data:      cannot be read here (needs Node 22.13 or newer)");
+  else {
+    lines.push(`Pipeline:  ${data.open_deals} open deal(s), ${data.companies} companies`);
+    lines.push(`Meetings:  ${data.meetings} saved; ${data.open_actions} open action item(s)${data.overdue_actions ? `, ${data.overdue_actions} overdue` : ""}`);
+    const next = data.next_reminder ? `; next: "${data.next_reminder.title}" at ${new Date(data.next_reminder.due_at).toLocaleString()}` : "";
+    lines.push(`Reminders: ${data.pending_reminders} pending${data.overdue_reminders ? ` (${data.overdue_reminders} due now)` : ""}${next}`);
+  }
+
+  const backup = data && !data.unavailable ? latestBackup() : null;
+  if (data && !data.unavailable) {
+    lines.push(backup ? `Backup:    last one ${ago(backup.mtime, now.getTime())}` : 'Backup:    none yet. Make one with "causly-server backup"');
+  }
+
+  // update
+  if (checkUpdate) {
+    const msg = updateMessage(await checkForUpdate({ current: version, fetch: fetchFn, env }));
+    if (msg) lines.push("", msg);
+  }
+  return { lines, editors: editors.map((e) => e.client), ready, partial, data, backup };
+}

package/tools/store.js

@@ -0,0 +1,111 @@
+// Local SQLite store shared by packs that need to remember things between
+// sessions (reminders, pipeline, follow-ups, ...).
+//
+// - Uses Node's built-in `node:sqlite` (no native dependency). Needs Node 22.13+;
+//   the rest of the server keeps working on older Node, only store-backed
+//   tools report a clear error.
+// - Opened lazily on first use, so users who never touch these tools never get a file.
+// - Location: ~/.causly/causly.db, or CAUSLY_DB_PATH.
+// - Each pack owns its tables through registerMigrations(namespace, [sql, ...]).
+//   Migrations are append-only: never edit a shipped statement, add a new one.
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { causlyHome } from "./paths.js";
+
+const migrations = new Map(); // namespace -> SQL statements, in order
+const applied = new Map(); // namespace -> highest applied version, for the open db
+let db = null;
+let openPath = null;
+let opening = null; // { file, promise }
+
+export function registerMigrations(namespace, statements) {
+  migrations.set(namespace, statements);
+}
+
+export function dbPath() {
+  return process.env.CAUSLY_DB_PATH || path.join(causlyHome(), "causly.db");
+}
+
+async function openDatabase(file) {
+  let sqlite;
+  try {
+    sqlite = await import("node:sqlite");
+  } catch {
+    throw new Error(`The local store needs Node 22.13 or newer (this is ${process.version}).`);
+  }
+  if (file !== ":memory:") fs.mkdirSync(path.dirname(file), { recursive: true });
+  const handle = new sqlite.DatabaseSync(file);
+  handle.exec("PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;"); // wait for another process's write instead of failing
+  handle.exec(
+    "CREATE TABLE IF NOT EXISTS schema_migrations (" +
+      "namespace TEXT NOT NULL, version INTEGER NOT NULL, applied_at TEXT NOT NULL, " +
+      "PRIMARY KEY (namespace, version))"
+  );
+  return handle;
+}
+
+function migrate(handle) {
+  for (const [namespace, statements] of migrations) {
+    let current = applied.get(namespace);
+    if (current === undefined) {
+      current = handle
+        .prepare("SELECT COALESCE(MAX(version), 0) AS v FROM schema_migrations WHERE namespace = ?")
+        .get(namespace).v;
+    }
+    for (let v = current; v < statements.length; v++) {
+      handle.exec("BEGIN");
+      try {
+        handle.exec(statements[v]);
+        handle
+          .prepare("INSERT INTO schema_migrations (namespace, version, applied_at) VALUES (?, ?, ?)")
+          .run(namespace, v + 1, new Date().toISOString());
+        handle.exec("COMMIT");
+      } catch (err) {
+        handle.exec("ROLLBACK");
+        throw err;
+      }
+      current = v + 1;
+    }
+    applied.set(namespace, current);
+  }
+}
+
+/** The open database, with every registered migration applied. */
+export async function getDb() {
+  const file = dbPath();
+  if (!db || openPath !== file) {
+    if (!opening || opening.file !== file) {
+      closeDb();
+      const promise = openDatabase(file).then(
+        (handle) => {
+          db = handle;
+          openPath = file;
+          applied.clear();
+          opening = null;
+        },
+        (err) => {
+          opening = null;
+          throw err;
+        }
+      );
+      opening = { file, promise };
+    }
+    await opening.promise;
+  }
+  migrate(db);
+  return db;
+}
+
+export function closeDb() {
+  if (db) {
+    try {
+      db.close();
+    } catch {
+      // already closed
+    }
+  }
+  db = null;
+  openPath = null;
+  applied.clear();
+}

package/tools/stripeOps.js

@@ -0,0 +1,299 @@
+// Stripe tools over the REST API. No new dependencies.
+//
+//   stripe_get_account         balance, and whether the key is test or live
+//   stripe_list_customers      find customers by email or name
+//   stripe_create_customer     add a customer
+//   stripe_list_invoices       invoices, filter by customer and status
+//   stripe_create_invoice      DRAFT invoice with line items (nothing is sent or charged)
+//   stripe_send_invoice        finalize a draft and email it to the customer (HIGH, confirm)
+//   stripe_create_payment_link shareable checkout link for a fixed amount (HIGH, confirm)
+//   stripe_list_payments       recent payments
+//   stripe_refund              refund a payment, whole or partial (HIGH, confirm)
+//
+// Credentials: STRIPE_API_KEY. Use a TEST key (sk_test_... or a restricted rk_test_...) first.
+// A live key is refused unless STRIPE_ALLOW_LIVE=true, so a live key pasted by mistake does nothing.
+// Amounts in and out are in normal units: 500 means $500.00 (JPY: 500 means 500 yen).
+import crypto from "crypto";
+import { UNTRUSTED_NOTICE } from "./webOps.js";
+
+const API = "https://api.stripe.com/v1";
+const clamp = (n, lo, hi) => Math.min(Math.max(n, lo), hi);
+const EMAIL = /^[^\s@,;<>]+@[^\s@,;<>]+\.[^\s@,;<>]+$/;
+const MAX_MINOR = 99_999_999; // Stripe's limit: 8 digits in the smallest unit
+
+// ---------------------------------------------------------------- money
+
+const ZERO_DECIMAL = new Set(["bif", "clp", "djf", "gnf", "jpy", "kmf", "krw", "mga", "pyg", "rwf", "ugx", "vnd", "vuv", "xaf", "xof", "xpf"]);
+const THREE_DECIMAL = new Set(["bhd", "iqd", "jod", "kwd", "lyd", "omr", "tnd"]);
+const decimals = (cur) => (ZERO_DECIMAL.has(cur) ? 0 : THREE_DECIMAL.has(cur) ? 3 : 2);
+
+export function checkCurrency(value, env = process.env) {
+  const c = String(value ?? env.STRIPE_DEFAULT_CURRENCY ?? "usd").trim().toLowerCase();
+  if (!/^[a-z]{3}$/.test(c)) throw new Error("currency must be a 3-letter code like usd, eur or inr.");
+  return c;
+}
+
+/** 500 usd -> 50000. Rejects zero, negatives and more decimals than the currency has. */
+export function toMinor(amount, currency, label = "amount") {
+  const n = Number(amount);
+  if (!Number.isFinite(n) || n <= 0) throw new Error(`${label} must be a positive number in normal units (500 means 500.00).`);
+  const d = decimals(currency);
+  const minor = Math.round(n * 10 ** d);
+  if (Math.abs(minor / 10 ** d - n) > 1e-9) throw new Error(`${label} ${n} has too many decimals for ${currency.toUpperCase()} (${d} allowed).`);
+  if (minor > MAX_MINOR) throw new Error(`${label} is above Stripe's maximum for ${currency.toUpperCase()}.`);
+  return minor;
+}
+
+export const toMajor = (minor, currency) => (minor == null ? null : Math.round(minor) / 10 ** decimals(currency));
+
+// ---------------------------------------------------------------- client
+
+/** Nested objects and arrays use Stripe's bracket form: line_items[0][price]=... */
+export function encode(obj) {
+  const out = [];
+  const walk = (value, key) => {
+    if (value === undefined || value === null) return;
+    if (Array.isArray(value)) value.forEach((v, i) => walk(v, `${key}[${i}]`));
+    else if (typeof value === "object") for (const [k, v] of Object.entries(value)) walk(v, key ? `${key}[${k}]` : k);
+    else out.push([key, String(value)]);
+  };
+  walk(obj, "");
+  return new URLSearchParams(out);
+}
+
+function client(deps = {}, env = process.env) {
+  const fetchFn = deps.fetch ?? globalThis.fetch;
+  const key = env.STRIPE_API_KEY;
+  if (!key) throw new Error("Stripe is not set up. Missing: STRIPE_API_KEY (use a test key, sk_test_..., from the Stripe dashboard).");
+  const live = /^(sk|rk)_live_/.test(key);
+  if (live && env.STRIPE_ALLOW_LIVE !== "true") {
+    throw new Error("STRIPE_API_KEY is a LIVE key, which is blocked on purpose. Use a test key (sk_test_...). To really work with live money, set STRIPE_ALLOW_LIVE=true.");
+  }
+  const scrub = (text) => String(text).split(key).join("[REDACTED]");
+  const mode = live ? "live" : "test";
+
+  const call = async (method, path, params) => {
+    const form = params ? encode(params) : undefined;
+    const url = `${API}${path}${method === "GET" && form && [...form].length ? `?${form}` : ""}`;
+    let res;
+    try {
+      res = await fetchFn(url, {
+        method,
+        headers: {
+          authorization: `Bearer ${key}`,
+          ...(method === "POST" ? { "content-type": "application/x-www-form-urlencoded", "idempotency-key": crypto.randomUUID() } : {}),
+        },
+        body: method === "POST" ? (form ?? new URLSearchParams()).toString() : undefined,
+        signal: AbortSignal.timeout(25_000),
+      });
+    } catch (err) {
+      throw new Error(`Could not reach Stripe: ${scrub(err.message)}`);
+    }
+    const data = await res.json().catch(() => ({}));
+    if (res.ok) return data;
+    const e = data.error ?? {};
+    if (res.status === 401) throw new Error("Stripe rejected the API key. Check STRIPE_API_KEY.");
+    if (res.status === 403) throw new Error(`Stripe refused: ${scrub(e.message || "permission denied")}. A restricted key may be missing a permission for this action.`);
+    if (res.status === 429) throw new Error("Stripe rate limit hit. Wait a moment and try again.");
+    throw new Error(`Stripe error: ${scrub(e.message || `HTTP ${res.status}`)}`);
+  };
+  call.mode = mode;
+  return call;
+}
+
+const iso = (sec) => (sec ? new Date(sec * 1000).toISOString() : null);
+const cleanId = (id, prefix, label) => {
+  const s = String(id ?? "").trim();
+  if (!new RegExp(`^${prefix}_[A-Za-z0-9]+$`).test(s)) throw new Error(`${label} must be a Stripe id starting with ${prefix}_.`);
+  return s;
+};
+
+function invoiceView(i) {
+  const cur = i.currency;
+  return {
+    id: i.id,
+    number: i.number ?? null,
+    status: i.status,
+    customer: i.customer_email || i.customer_name || i.customer,
+    customer_id: typeof i.customer === "string" ? i.customer : i.customer?.id,
+    total: toMajor(i.total, cur),
+    amount_due: toMajor(i.amount_due, cur),
+    amount_paid: toMajor(i.amount_paid, cur),
+    currency: cur?.toUpperCase(),
+    due_date: iso(i.due_date)?.slice(0, 10) ?? null,
+    created: iso(i.created),
+    hosted_invoice_url: i.hosted_invoice_url ?? null,
+  };
+}
+
+// ---------------------------------------------------------------- tools
+
+export async function getAccount(_input = {}, deps = {}) {
+  const call = client(deps);
+  const b = await call("GET", "/balance");
+  const side = (list) => (list || []).map((x) => ({ currency: x.currency.toUpperCase(), amount: toMajor(x.amount, x.currency) }));
+  return { mode: call.mode, available: side(b.available), pending: side(b.pending) };
+}
+
+export async function listCustomers({ email, query, limit = 10 } = {}, deps = {}) {
+  const call = client(deps);
+  const max = clamp(Math.trunc(Number(limit)) || 10, 1, 100);
+  let data;
+  if (query && String(query).trim()) {
+    const q = String(query).trim().replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    data = await call("GET", "/customers/search", { query: `name~"${q}"`, limit: max });
+  } else {
+    if (email && !EMAIL.test(String(email).trim())) throw new Error("email is not a valid email address.");
+    data = await call("GET", "/customers", { ...(email ? { email: String(email).trim().toLowerCase() } : {}), limit: max });
+  }
+  const customers = (data.data || []).map((c) => ({ id: c.id, name: c.name ?? null, email: c.email ?? null, created: iso(c.created), ...(c.description ? { description: String(c.description).slice(0, 200) } : {}) }));
+  return { mode: call.mode, count: customers.length, customers, notice: UNTRUSTED_NOTICE };
+}
+
+export async function createCustomer({ email, name, description } = {}, deps = {}) {
+  if (!email && !name) throw new Error("Give at least an email or a name.");
+  if (email && !EMAIL.test(String(email).trim())) throw new Error("email is not a valid email address.");
+  const call = client(deps);
+  const c = await call("POST", "/customers", {
+    ...(email ? { email: String(email).trim().toLowerCase() } : {}),
+    ...(name ? { name: String(name).trim() } : {}),
+    ...(description ? { description: String(description) } : {}),
+  });
+  return { created: true, mode: call.mode, customer: { id: c.id, name: c.name ?? null, email: c.email ?? null } };
+}
+
+export async function listInvoices({ customer, status, limit = 10 } = {}, deps = {}) {
+  const call = client(deps);
+  if (status && !["draft", "open", "paid", "uncollectible", "void"].includes(status)) throw new Error("status must be draft, open, paid, uncollectible or void.");
+  const data = await call("GET", "/invoices", {
+    ...(customer ? { customer: cleanId(customer, "cus", "customer") } : {}),
+    ...(status ? { status } : {}),
+    limit: clamp(Math.trunc(Number(limit)) || 10, 1, 100),
+  });
+  const invoices = (data.data || []).map(invoiceView);
+  return { mode: call.mode, count: invoices.length, invoices, notice: UNTRUSTED_NOTICE };
+}
+
+async function resolveCustomer(call, customer, name) {
+  const s = String(customer ?? "").trim();
+  if (/^cus_[A-Za-z0-9]+$/.test(s)) return { id: s, created: false };
+  if (!EMAIL.test(s)) throw new Error("customer must be a Stripe customer id (cus_...) or an email address.");
+  const found = await call("GET", "/customers", { email: s.toLowerCase(), limit: 1 });
+  if (found.data?.length) return { id: found.data[0].id, created: false };
+  const made = await call("POST", "/customers", { email: s.toLowerCase(), ...(name ? { name: String(name).trim() } : {}) });
+  return { id: made.id, created: true };
+}
+
+export async function createInvoice({ customer, customer_name, items, currency, days_until_due = 14, memo } = {}, deps = {}) {
+  if (!Array.isArray(items) || !items.length) throw new Error("items is required: a list like [{ description, amount, quantity }].");
+  if (items.length > 20) throw new Error("20 line items at most.");
+  const cur = checkCurrency(currency);
+  const lines = items.map((it, n) => {
+    const description = String(it?.description ?? "").trim();
+    if (!description) throw new Error(`Item ${n + 1} needs a description.`);
+    if (description.length > 250) throw new Error(`Item ${n + 1}: description is over 250 characters.`);
+    const qty = it.quantity === undefined ? 1 : Number(it.quantity);
+    if (!Number.isInteger(qty) || qty < 1 || qty > 10_000) throw new Error(`Item ${n + 1}: quantity must be a whole number from 1 to 10000.`);
+    return { description, quantity: qty, unit_amount: toMinor(it.amount, cur, `Item ${n + 1} amount`) };
+  });
+  const days = clamp(Math.trunc(Number(days_until_due)) || 14, 1, 90);
+
+  const call = client(deps);
+  const cust = await resolveCustomer(call, customer, customer_name);
+  const inv = await call("POST", "/invoices", {
+    customer: cust.id,
+    currency: cur,
+    collection_method: "send_invoice",
+    days_until_due: days,
+    auto_advance: false,
+    pending_invoice_items_behavior: "exclude",
+    ...(memo ? { description: String(memo).slice(0, 1000) } : {}),
+  });
+  try {
+    for (const line of lines) {
+      await call("POST", "/invoiceitems", { customer: cust.id, invoice: inv.id, currency: cur, ...line });
+    }
+  } catch (err) {
+    await call("DELETE", `/invoices/${inv.id}`).catch(() => {}); // do not leave a half-built draft behind
+    throw err;
+  }
+  const full = await call("GET", `/invoices/${inv.id}`);
+  return {
+    created: true,
+    mode: call.mode,
+    customer_created: cust.created,
+    invoice: invoiceView(full),
+    next: "This is a draft: nothing was sent or charged. Use stripe_send_invoice (needs confirm: true) to email it to the customer.",
+  };
+}
+
+export async function sendInvoice({ invoice, confirm } = {}, deps = {}) {
+  const id = cleanId(invoice, "in", "invoice");
+  const call = client(deps);
+  const current = await call("GET", `/invoices/${id}`);
+  if (current.status === "paid" || current.status === "void" || current.status === "uncollectible") {
+    throw new Error(`Invoice ${id} is ${current.status}; it cannot be sent.`);
+  }
+  if (!current.total) throw new Error(`Invoice ${id} has no amount; add line items first.`);
+  let working = current;
+  if (current.status === "draft") working = await call("POST", `/invoices/${id}/finalize`, { auto_advance: false });
+  const sent = await call("POST", `/invoices/${id}/send`);
+  return { sent: true, mode: call.mode, invoice: invoiceView({ ...working, ...sent }) };
+}
+
+export async function createPaymentLink({ name, amount, currency, confirm } = {}, deps = {}) {
+  const title = String(name ?? "").trim();
+  if (!title) throw new Error("name is required (what the customer is paying for).");
+  if (title.length > 250) throw new Error("name is over 250 characters.");
+  const cur = checkCurrency(currency);
+  const minor = toMinor(amount, cur);
+  const call = client(deps);
+  const price = await call("POST", "/prices", { currency: cur, unit_amount: minor, product_data: { name: title } });
+  const link = await call("POST", "/payment_links", { line_items: [{ price: price.id, quantity: 1 }] });
+  return { created: true, mode: call.mode, url: link.url, id: link.id, name: title, amount: toMajor(minor, cur), currency: cur.toUpperCase() };
+}
+
+export async function listPayments({ customer, limit = 10 } = {}, deps = {}) {
+  const call = client(deps);
+  const data = await call("GET", "/payment_intents", {
+    ...(customer ? { customer: cleanId(customer, "cus", "customer") } : {}),
+    limit: clamp(Math.trunc(Number(limit)) || 10, 1, 100),
+  });
+  const payments = (data.data || []).map((p) => ({
+    id: p.id,
+    status: p.status,
+    amount: toMajor(p.amount, p.currency),
+    received: toMajor(p.amount_received, p.currency),
+    currency: p.currency?.toUpperCase(),
+    customer: typeof p.customer === "string" ? p.customer : p.customer?.id ?? null,
+    ...(p.description ? { description: String(p.description).slice(0, 200) } : {}),
+    created: iso(p.created),
+  }));
+  return { mode: call.mode, count: payments.length, payments, notice: UNTRUSTED_NOTICE };
+}
+
+export async function refund({ payment, amount, reason, confirm } = {}, deps = {}) {
+  const id = cleanId(payment, "pi", "payment");
+  if (reason !== undefined && !["duplicate", "fraudulent", "requested_by_customer"].includes(reason)) {
+    throw new Error("reason must be duplicate, fraudulent or requested_by_customer.");
+  }
+  const call = client(deps);
+  const pi = await call("GET", `/payment_intents/${id}`);
+  const received = pi.amount_received ?? 0;
+  if (!received) throw new Error(`Payment ${id} has nothing to refund (status ${pi.status}).`);
+  let minor;
+  if (amount !== undefined && amount !== null && amount !== "") {
+    minor = toMinor(amount, pi.currency, "amount");
+    if (minor > received) throw new Error(`amount ${toMajor(minor, pi.currency)} is more than the ${toMajor(received, pi.currency)} ${pi.currency.toUpperCase()} received.`);
+  }
+  const r = await call("POST", "/refunds", { payment_intent: id, ...(minor ? { amount: minor } : {}), ...(reason ? { reason } : {}) });
+  return {
+    refunded: true,
+    mode: call.mode,
+    refund_id: r.id,
+    status: r.status,
+    amount: toMajor(r.amount, r.currency),
+    currency: r.currency?.toUpperCase(),
+    full_refund: !minor || minor === received,
+  };
+}