@letterapp/cli 0.2.0 → 0.3.0

package/dist/index.js

@@ -60,6 +60,30 @@ function prompt(question) {
     });
   });
 }
+function emit(data) {
+  if (jsonMode) {
+    printJson(data);
+    return;
+  }
+  if (data && typeof data === "object" && Array.isArray(data.data)) {
+    const env = data;
+    if (env.data.length === 0) {
+      console.log(chalk.dim("(none)"));
+    } else {
+      for (const row of env.data) {
+        const id = String(row.id ?? row.slug ?? row.external_id ?? "");
+        const label = row.name ?? row.email ?? row.domain ?? row.subject ?? "";
+        console.log(`${chalk.bold(id)}${label ? "  " + label : ""}`);
+      }
+    }
+    if (env.next_cursor) {
+      console.log(chalk.dim(`
+\u203A more: --cursor ${env.next_cursor}`));
+    }
+    return;
+  }
+  printJson(data);
+}
 var c = chalk;
 
 // src/config.ts
@@ -87,6 +111,15 @@ function getConfigPath() {
 function resetConfig() {
   config.clear();
 }
+async function resolveProjectSlug(flag) {
+  if (flag) return flag;
+  if (process.env.LETTER_PROJECT) return process.env.LETTER_PROJECT;
+  const cred = await readCredential();
+  if (cred?.project?.slug) return cred.project.slug;
+  throw new Error(
+    "No project. Pass --project <slug>, set LETTER_PROJECT, or run `letter login`."
+  );
+}
 function credentialsPath() {
   return path.join(homedir(), ".letter", "credentials.json");
 }
@@ -181,6 +214,78 @@ var LetterClient = class {
   }
 };
 var client = new LetterClient();
+var ManagementClient = class {
+  maxRetries = 3;
+  async resolveAuth() {
+    const cred = await readCredential();
+    const token = process.env.LETTER_PAT || cred?.pat || "";
+    if (!token) {
+      throw new Error(
+        "Not connected for management. Run `letter login` (or set LETTER_PAT) first."
+      );
+    }
+    const base = getBaseUrl(process.env.LETTER_PAT ? void 0 : cred?.baseUrl);
+    return { base, token };
+  }
+  async request(method, path3, init = {}, attempt = 1) {
+    const { base, token } = await this.resolveAuth();
+    let url = `${base}${path3}`;
+    if (init.query) {
+      const qs = new URLSearchParams();
+      for (const [k, v] of Object.entries(init.query)) {
+        if (v !== void 0 && v !== "") qs.set(k, String(v));
+      }
+      const s = qs.toString();
+      if (s) url += `?${s}`;
+    }
+    const headers = {
+      authorization: `Bearer ${token}`,
+      accept: "application/json",
+      "user-agent": USER_AGENT
+    };
+    let body;
+    if (init.form) {
+      body = init.form;
+    } else if (init.body !== void 0) {
+      headers["content-type"] = "application/json";
+      body = JSON.stringify(init.body);
+    }
+    const res = await fetch(url, { method, headers, body });
+    if (res.status === 429 && attempt <= this.maxRetries) {
+      const retryAfter = Number(res.headers.get("retry-after") || 2);
+      await new Promise((r) => setTimeout(r, retryAfter * 1e3 * attempt));
+      return this.request(method, path3, init, attempt + 1);
+    }
+    const text = await res.text();
+    const data = text ? JSON.parse(text) : {};
+    if (!res.ok) {
+      const msg = data?.error?.message || `HTTP ${res.status}`;
+      const err = new Error(msg);
+      err.status = res.status;
+      throw err;
+    }
+    return { status: res.status, data };
+  }
+  get(path3, query) {
+    return this.request("GET", path3, { query });
+  }
+  post(path3, body) {
+    return this.request("POST", path3, { body });
+  }
+  postForm(path3, form) {
+    return this.request("POST", path3, { form });
+  }
+  patch(path3, body) {
+    return this.request("PATCH", path3, { body });
+  }
+  put(path3, body) {
+    return this.request("PUT", path3, { body });
+  }
+  delete(path3) {
+    return this.request("DELETE", path3);
+  }
+};
+var mgmt = new ManagementClient();
 
 // src/browser.ts
 import { spawn } from "child_process";
@@ -249,7 +354,7 @@ function escapeRegExp(s) {
 
 // src/pm.ts
 import { spawn as spawn2 } from "child_process";
-import { readFile as readFile3 } from "fs/promises";
+import { readFile as readFile3, readdir } from "fs/promises";
 async function detectPackageManager(cwd) {
   if (await fileExists(cwd, "pnpm-lock.yaml")) return "pnpm";
   if (await fileExists(cwd, "yarn.lock")) return "yarn";
@@ -277,6 +382,121 @@ async function detectFramework(cwd) {
     return null;
   }
 }
+async function detectStack(cwd) {
+  if (await fileExists(cwd, "package.json")) {
+    return { runtime: "node", framework: await detectFramework(cwd) };
+  }
+  if (await fileExists(cwd, "pyproject.toml") || await fileExists(cwd, "requirements.txt") || await fileExists(cwd, "Pipfile") || await fileExists(cwd, "setup.py")) {
+    return { runtime: "python", framework: await detectPythonFramework(cwd) };
+  }
+  if (await fileExists(cwd, "Gemfile") || await hasGemspec(cwd)) {
+    return { runtime: "ruby", framework: await detectRubyFramework(cwd) };
+  }
+  if (await fileExists(cwd, "go.mod")) return { runtime: "go", framework: null };
+  if (await fileExists(cwd, "composer.json")) {
+    return { runtime: "php", framework: await detectPhpFramework(cwd) };
+  }
+  return { runtime: "other", framework: null };
+}
+function stackLabel(stack) {
+  if (stack.framework) return stack.framework;
+  switch (stack.runtime) {
+    case "node":
+      return "a Node.js project";
+    case "python":
+      return "a Python project";
+    case "ruby":
+      return "a Ruby project";
+    case "go":
+      return "a Go project";
+    case "php":
+      return "a PHP project";
+    default:
+      return "your project";
+  }
+}
+function languageName(stack) {
+  switch (stack.runtime) {
+    case "node":
+      return "TypeScript";
+    case "python":
+      return "Python";
+    case "ruby":
+      return "Ruby";
+    case "go":
+      return "Go";
+    case "php":
+      return "PHP";
+    default:
+      return "your language";
+  }
+}
+async function readIf(cwd, name) {
+  try {
+    return await readFile3(`${cwd}/${name}`, "utf8");
+  } catch {
+    return "";
+  }
+}
+async function hasGemspec(cwd) {
+  try {
+    return (await readdir(cwd)).some((f) => f.endsWith(".gemspec"));
+  } catch {
+    return false;
+  }
+}
+async function detectPythonFramework(cwd) {
+  const txt = (await readIf(cwd, "requirements.txt") + await readIf(cwd, "pyproject.toml") + await readIf(cwd, "Pipfile")).toLowerCase();
+  if (txt.includes("django")) return "Django";
+  if (txt.includes("fastapi")) return "FastAPI";
+  if (txt.includes("flask")) return "Flask";
+  return null;
+}
+async function detectRubyFramework(cwd) {
+  const txt = (await readIf(cwd, "Gemfile")).toLowerCase();
+  if (txt.includes("rails")) return "Rails";
+  if (txt.includes("sinatra")) return "Sinatra";
+  return null;
+}
+async function detectPhpFramework(cwd) {
+  const txt = (await readIf(cwd, "composer.json")).toLowerCase();
+  if (txt.includes("laravel")) return "Laravel";
+  if (txt.includes("symfony")) return "Symfony";
+  return null;
+}
+var SDK_PYPI = "letterapp";
+var SDK_GEM = "letterapp";
+function sdkInstall(cmd, args) {
+  return { cmd, args, display: `${cmd} ${args.join(" ")}` };
+}
+async function pythonSdkInstall(cwd) {
+  if (await fileExists(cwd, "uv.lock")) return sdkInstall("uv", ["add", SDK_PYPI]);
+  const pyproject = (await readIf(cwd, "pyproject.toml")).toLowerCase();
+  if (await fileExists(cwd, "poetry.lock") || pyproject.includes("[tool.poetry]")) {
+    return sdkInstall("poetry", ["add", SDK_PYPI]);
+  }
+  if (await fileExists(cwd, "Pipfile")) {
+    return sdkInstall("pipenv", ["install", SDK_PYPI]);
+  }
+  return sdkInstall("pip", ["install", SDK_PYPI]);
+}
+async function rubySdkInstall(cwd) {
+  if (await fileExists(cwd, "Gemfile")) {
+    return sdkInstall("bundle", ["add", SDK_GEM]);
+  }
+  return sdkInstall("gem", ["install", SDK_GEM]);
+}
+function runSdkInstall(install, cwd) {
+  return new Promise((resolve) => {
+    const child = spawn2(install.cmd, install.args, {
+      cwd,
+      stdio: "inherit",
+      shell: process.platform === "win32"
+    });
+    child.on("error", () => resolve(1));
+    child.on("close", (code) => resolve(code ?? 1));
+  });
+}
 function installCommand(pm, pkg) {
   switch (pm) {
     case "pnpm":
@@ -304,8 +524,10 @@ function runInstall(pm, pkg, cwd) {
 
 // src/commands/login.ts
 var SDK_PACKAGE = "@letterapp/node";
-var ENV_FILE = ".env.local";
 var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function envFileFor(stack) {
+  return stack.runtime === "node" ? ".env.local" : ".env";
+}
 function registerLoginCommand(program2) {
   program2.command("login", { isDefault: true }).alias("init").description("Connect this project to Letter (interactive device login)").option("--no-open", "Don't open the browser; print the URL to open manually").option("-y, --yes", "Non-interactive: don't wait for Enter (agents/CI)").option("--no-install", "Skip installing the SDK").option("--base-url <url>", "Target a self-hosted or local Letter instance").option(
     "--api-key <key>",
@@ -321,9 +543,10 @@ async function runLogin(opts) {
   const interactive = process.stdin.isTTY && !opts.yes;
   banner();
   if (opts.apiKey) {
+    const envFile = envFileFor(await detectStack(cwd));
     const entries = { LETTER_API_KEY: opts.apiKey };
     if (base !== DEFAULT_BASE_URL) entries.LETTER_BASE_URL = base;
-    const file = await upsertEnv(cwd, ENV_FILE, entries);
+    const file = await upsertEnv(cwd, envFile, entries);
     printSuccess(`Saved LETTER_API_KEY to ${rel(cwd, file)} (--api-key).`);
     printWarning("--api-key is for CI. For interactive setup, run `letter login`.");
     return 0;
@@ -371,51 +594,242 @@ async function runLogin(opts) {
       printError(new Error("This login expired. Run the command again to retry."));
       return 1;
     }
-    return finish(res.api_key, res.base_url, res.project, cwd, opts.install);
+    return finish(res, cwd, opts.install);
   }
   printError(new Error("Timed out waiting for approval. Run the command again."));
   return 1;
 }
-async function finish(apiKey, baseUrl, project, cwd, doInstall) {
+async function finish(approved, cwd, doInstall) {
+  const { api_key: apiKey, pat, base_url: baseUrl, project, workspace } = approved;
   log();
   printSuccess(`Approved for project ${c.bold(project.name)}.`);
+  const stack = await detectStack(cwd);
+  const isNode = stack.runtime === "node";
+  const envFile = envFileFor(stack);
   const entries = { LETTER_API_KEY: apiKey };
   if (baseUrl && baseUrl !== DEFAULT_BASE_URL) entries.LETTER_BASE_URL = baseUrl;
-  const envFile = await upsertEnv(cwd, ENV_FILE, entries);
-  printSuccess(`Saved LETTER_API_KEY to ${rel(cwd, envFile)}.`);
+  const written = await upsertEnv(cwd, envFile, entries);
+  printSuccess(`Saved LETTER_API_KEY to ${rel(cwd, written)}.`);
   try {
     const credFile = await saveCredential({
       apiKey,
+      pat,
       baseUrl: baseUrl || DEFAULT_BASE_URL,
       project,
+      workspace,
       savedAt: (/* @__PURE__ */ new Date()).toISOString()
     });
-    printSuccess(`Stored credentials in ${tildify(credFile)} for tooling (MCP).`);
+    printSuccess(`Stored credentials in ${tildify(credFile)} for tooling (MCP + CLI).`);
   } catch {
     printWarning("Could not write ~/.letter/credentials.json (continuing).");
   }
-  const pm = await detectPackageManager(cwd);
-  if (doInstall) {
-    printInfo(`Installing ${SDK_PACKAGE} with ${pm}\u2026`);
-    const code = await runInstall(pm, SDK_PACKAGE, cwd);
-    if (code === 0) printSuccess(`Installed ${SDK_PACKAGE}.`);
-    else printWarning(`Install failed. Run: ${installCommand(pm, SDK_PACKAGE)}`);
+  if (isNode) {
+    const pm = await detectPackageManager(cwd);
+    if (doInstall) {
+      printInfo(`Installing ${SDK_PACKAGE} with ${pm}\u2026`);
+      const code = await runInstall(pm, SDK_PACKAGE, cwd);
+      if (code === 0) printSuccess(`Installed ${SDK_PACKAGE}.`);
+      else printWarning(`Install failed. Run: ${installCommand(pm, SDK_PACKAGE)}`);
+    } else {
+      printInfo(`Skipped install. Run: ${installCommand(pm, SDK_PACKAGE)}`);
+    }
+    printNodeInstructions(stack.framework, envFile);
+  } else if (stack.runtime === "python" || stack.runtime === "ruby") {
+    const install = stack.runtime === "python" ? await pythonSdkInstall(cwd) : await rubySdkInstall(cwd);
+    await installSdk(install, doInstall);
+    if (stack.runtime === "python") {
+      printPythonInstructions(stack.framework, envFile);
+    } else {
+      printRubyInstructions(stack.framework, envFile);
+    }
   } else {
-    printInfo(`Skipped install. Run: ${installCommand(pm, SDK_PACKAGE)}`);
+    printInfo(
+      `Detected ${stackLabel(stack)}. No ${languageName(stack)} SDK yet, so use the HTTP API - no package installed.`
+    );
+    printHttpInstructions(stack, envFile, baseUrl || DEFAULT_BASE_URL);
   }
-  printNextSteps(await detectFramework(cwd));
   return 0;
 }
-function printNextSteps(framework) {
+async function installSdk(install, doInstall) {
+  if (doInstall) {
+    printInfo(`Installing letterapp (${install.display})\u2026`);
+    const code = await runSdkInstall(install, process.cwd());
+    if (code === 0) printSuccess("Installed letterapp.");
+    else printWarning(`Install failed. Run: ${install.display}`);
+  } else {
+    printInfo(`Skipped install. Run: ${install.display}`);
+  }
+}
+function printNodeInstructions(framework, envFile) {
+  log();
+  log(c.bold("Next: hand these steps to your coding agent"));
+  log(
+    c.dim(
+      framework ? `Detected ${framework}. The SDK is installed and LETTER_API_KEY is in ${envFile}.` : `The SDK is installed and LETTER_API_KEY is in ${envFile}.`
+    )
+  );
+  log();
+  log(
+    c.bold("  1. ") + `Create a server-side client (e.g. ${c.cyan("lib/letter.ts")}):`
+  );
+  log(c.dim('       import { Letter } from "@letterapp/node";'));
+  log(c.dim("       export const letter = new Letter({"));
+  log(c.dim("         apiKey: process.env.LETTER_API_KEY!,"));
+  log(
+    c.dim(
+      "         ...(process.env.LETTER_BASE_URL ? { baseUrl: process.env.LETTER_BASE_URL } : {}),"
+    )
+  );
+  log(c.dim("       });"));
+  log();
+  log(
+    c.bold("  2. ") + `Call ${c.cyan("identify()")} where users sign up or log in:`
+  );
+  log(
+    c.dim(
+      "       await letter.identify({ userId: user.id, email: user.email });"
+    )
+  );
+  log();
+  log(
+    c.bold("  3. ") + `Call ${c.cyan("track()")} on your 2-3 most important actions:`
+  );
+  log(
+    c.dim('       await letter.track({ userId: user.id, event: "Signed Up" });')
+  );
+  log();
+  log(
+    c.dim(
+      "  In serverless handlers or scripts, await letter.flush() before returning."
+    )
+  );
+  log();
+  log(c.dim("Verify it landed: ") + c.bold("letter status"));
+  log(
+    c.dim(
+      `Your API key is in ${envFile} - keep it out of source control, and don't echo its value.`
+    )
+  );
+  log();
+}
+function printPythonInstructions(framework, envFile) {
+  log();
+  log(c.bold("Next: hand these steps to your coding agent"));
+  log(
+    c.dim(
+      framework ? `Detected ${framework}. The SDK is installed and LETTER_API_KEY is in ${envFile}.` : `The SDK is installed and LETTER_API_KEY is in ${envFile}.`
+    )
+  );
+  log();
+  log(
+    c.bold("  1. ") + `Create a shared client (e.g. ${c.cyan("letter.py")}):`
+  );
+  log(c.dim("       import os"));
+  log(c.dim("       from letterapp import Letter"));
+  log(c.dim('       letter = Letter(api_key=os.environ["LETTER_API_KEY"])'));
+  log(c.dim('       # Self-hosted/local: pass base_url=os.environ["LETTER_BASE_URL"].'));
+  log();
+  log(
+    c.bold("  2. ") + `Call ${c.cyan("identify()")} where users sign up or log in:`
+  );
+  log(c.dim("       letter.identify(user_id=user.id, email=user.email)"));
+  log();
+  log(
+    c.bold("  3. ") + `Call ${c.cyan("track()")} on your 2-3 most important actions:`
+  );
+  log(c.dim('       letter.track(user_id=user.id, event="Signed Up")'));
+  log();
+  log(
+    c.dim(
+      "  In serverless handlers or scripts, call letter.flush() (or letter.close()) before returning."
+    )
+  );
+  log();
+  log(c.dim("Verify it landed: ") + c.bold("letter status"));
+  log(
+    c.dim(
+      `Your API key is in ${envFile} - keep it out of source control, and don't echo its value.`
+    )
+  );
+  log();
+}
+function printRubyInstructions(framework, envFile) {
+  log();
+  log(c.bold("Next: hand these steps to your coding agent"));
+  log(
+    c.dim(
+      framework ? `Detected ${framework}. The SDK is installed and LETTER_API_KEY is in ${envFile}.` : `The SDK is installed and LETTER_API_KEY is in ${envFile}.`
+    )
+  );
+  log();
+  log(
+    c.bold("  1. ") + `Create a shared client (in Rails, ${c.cyan("config/initializers/letter.rb")}):`
+  );
+  log(c.dim('       require "letterapp"'));
+  log(c.dim('       LETTER = Letterapp::Client.new(api_key: ENV["LETTER_API_KEY"])'));
+  log(c.dim('       # Self-hosted/local: pass base_url: ENV["LETTER_BASE_URL"].'));
+  log();
+  log(
+    c.bold("  2. ") + `Call ${c.cyan("identify")} where users sign up or log in:`
+  );
+  log(c.dim("       LETTER.identify(user_id: user.id, email: user.email)"));
   log();
-  log(c.bold("Next steps"));
-  if (framework) log(c.dim(`Detected ${framework}.`));
-  log(`  1. Create a server-side client that reads ${c.cyan("process.env.LETTER_API_KEY")}.`);
-  log(`  2. Call ${c.cyan("letter.identify(...)")} where users sign up or log in.`);
-  log(`  3. Call ${c.cyan("letter.track(...)")} on 2-3 key actions.`);
+  log(
+    c.bold("  3. ") + `Call ${c.cyan("track")} on your 2-3 most important actions:`
+  );
+  log(c.dim('       LETTER.track(user_id: user.id, event: "Signed Up")'));
   log();
-  log(c.dim("Check it landed: ") + c.bold("letter status"));
-  log(c.dim("Your API key is in .env.local - keep it out of source control."));
+  log(
+    c.dim(
+      "  In serverless handlers or scripts, call LETTER.flush before returning."
+    )
+  );
+  log();
+  log(c.dim("Verify it landed: ") + c.bold("letter status"));
+  log(
+    c.dim(
+      `Your API key is in ${envFile} - keep it out of source control, and don't echo its value.`
+    )
+  );
+  log();
+}
+function printHttpInstructions(stack, envFile, base) {
+  log();
+  log(c.bold("Next: hand these steps to your coding agent"));
+  log(
+    c.dim(
+      `Detected ${stackLabel(stack)}. There's no ${languageName(stack)} SDK yet, so call Letter's HTTP API directly in ${languageName(stack)} with your usual HTTP client.`
+    )
+  );
+  log();
+  log(
+    c.dim(
+      `LETTER_API_KEY is in ${envFile}. Read it from the environment; never inline it.`
+    )
+  );
+  log();
+  log(c.bold("  1. ") + "identify users where they sign up or log in:");
+  log(c.dim(`       POST ${base}/v1/identify`));
+  log(c.dim("       Authorization: Bearer $LETTER_API_KEY"));
+  log(c.dim('       { "userId": "<your user id>", "email": "<email>" }'));
+  log();
+  log(c.bold("  2. ") + "track your 2-3 most important actions:");
+  log(c.dim(`       POST ${base}/v1/track`));
+  log(c.dim("       Authorization: Bearer $LETTER_API_KEY"));
+  log(c.dim('       { "userId": "<your user id>", "event": "Signed Up" }'));
+  log();
+  log(
+    c.dim(
+      "  Send Content-Type: application/json. The same auth/shape covers group and batch."
+    )
+  );
+  log();
+  log(c.dim("Verify it landed: ") + c.bold("letter status"));
+  log(
+    c.dim(
+      `Your API key is in ${envFile} - keep it out of source control, and don't echo its value.`
+    )
+  );
   log();
 }
 function rel(cwd, file) {
@@ -527,14 +941,595 @@ function registerConfigCommands(program2) {
   });
 }
 
+// src/commands/resources.ts
+import { readFile as readFile4 } from "fs/promises";
+async function readValue(raw) {
+  if (raw.startsWith("@")) return (await readFile4(raw.slice(1), "utf8")).trim();
+  return raw;
+}
+async function buildBody(fields, opts) {
+  const body = {};
+  for (const f of fields) {
+    const v = opts[camel(f.key)];
+    if (v === void 0) continue;
+    if (f.json) {
+      body[f.key] = JSON.parse(await readValue(String(v)));
+    } else if (f.number) {
+      body[f.key] = Number(v);
+    } else if (f.boolean) {
+      body[f.key] = v === true || v === "true";
+    } else {
+      body[f.key] = await readValue(String(v));
+    }
+  }
+  return body;
+}
+async function buildForm(fields, opts) {
+  const form = new FormData();
+  for (const f of fields) {
+    const v = opts[camel(f.key)];
+    if (v === void 0) continue;
+    if (f.file) {
+      const path3 = String(v);
+      const bytes = await readFile4(path3);
+      const name = path3.split("/").pop() || f.key;
+      form.append(f.key, new Blob([new Uint8Array(bytes)]), name);
+    } else if (f.json) {
+      form.append(f.key, await readValue(String(v)));
+    } else {
+      form.append(f.key, String(v));
+    }
+  }
+  return form;
+}
+function buildQuery(fields, opts) {
+  const q = {};
+  for (const f of fields) {
+    const v = opts[camel(f.key)];
+    if (v === void 0) continue;
+    q[f.key] = f.number ? Number(v) : String(v);
+  }
+  return q;
+}
+function camel(key) {
+  return key.replace(/[-_]([a-z])/g, (_, ch) => ch.toUpperCase());
+}
+function applyFields(cmd, fields) {
+  for (const f of fields) {
+    cmd.option(f.flag, f.description ?? f.key);
+  }
+}
+async function basePath(spec, project) {
+  const seg = spec.segment ?? spec.name;
+  if (!spec.scoped) return `/v1/${seg}`;
+  const slug = await resolveProjectSlug(project);
+  return `/v1/projects/${slug}/${seg}`;
+}
+function withProject(cmd, scoped) {
+  if (scoped) {
+    cmd.option("-p, --project <slug>", "Project slug (default: connected project)");
+  }
+  return cmd;
+}
+function fail(err) {
+  printError(err);
+  process.exitCode = 1;
+}
+function register(program2, spec) {
+  const group = program2.command(spec.name).description(spec.describe);
+  if (spec.alias) group.alias(spec.alias);
+  const idName = spec.idName ?? "id";
+  if (spec.list) {
+    const cmd = withProject(
+      group.command("list").description(`List ${spec.name}`),
+      spec.scoped
+    );
+    if (spec.list.paginated) {
+      cmd.option("--limit <n>", "Max items (1-100)");
+      cmd.option("--cursor <cursor>", "Pagination cursor");
+    }
+    if (spec.list.query) applyFields(cmd, spec.list.query);
+    cmd.action(async (opts) => {
+      try {
+        const query = {};
+        if (spec.list?.paginated) {
+          if (opts.limit) query.limit = Number(opts.limit);
+          if (opts.cursor) query.cursor = opts.cursor;
+        }
+        if (spec.list?.query) Object.assign(query, buildQuery(spec.list.query, opts));
+        const { data } = await mgmt.get(await basePath(spec, opts.project), query);
+        emit(data);
+      } catch (err) {
+        fail(err);
+      }
+    });
+  }
+  if (spec.get) {
+    const cmd = withProject(
+      group.command("get").description(`Get a ${spec.name} by ${idName}`).argument(`<${idName}>`, idName),
+      spec.scoped
+    );
+    cmd.action(async (idValue, opts) => {
+      try {
+        const path3 = `${await basePath(spec, opts.project)}/${encodeURIComponent(idValue)}`;
+        const { data } = await mgmt.get(path3);
+        emit(data);
+      } catch (err) {
+        fail(err);
+      }
+    });
+  }
+  if (spec.create) {
+    const cmd = withProject(
+      group.command("create").description(`Create a ${spec.name}`),
+      spec.scoped
+    );
+    applyFields(cmd, spec.create);
+    cmd.action(async (opts) => {
+      try {
+        const body = await buildBody(spec.create, opts);
+        const { data } = await mgmt.post(await basePath(spec, opts.project), body);
+        emit(data);
+      } catch (err) {
+        fail(err);
+      }
+    });
+  }
+  if (spec.update) {
+    const cmd = withProject(
+      group.command("update").description(`Update a ${spec.name}`).argument(`<${idName}>`, idName),
+      spec.scoped
+    );
+    applyFields(cmd, spec.update);
+    cmd.action(async (idValue, opts) => {
+      try {
+        const body = await buildBody(spec.update, opts);
+        const path3 = `${await basePath(spec, opts.project)}/${encodeURIComponent(idValue)}`;
+        const { data } = await mgmt.patch(path3, body);
+        emit(data);
+      } catch (err) {
+        fail(err);
+      }
+    });
+  }
+  if (spec.remove) {
+    const cmd = withProject(
+      group.command("delete").description(`Delete a ${spec.name}`).argument(`<${idName}>`, idName),
+      spec.scoped
+    );
+    cmd.action(async (idValue, opts) => {
+      try {
+        const path3 = `${await basePath(spec, opts.project)}/${encodeURIComponent(idValue)}`;
+        await mgmt.delete(path3);
+        printSuccess(`Deleted ${spec.name.replace(/s$/, "")} ${idValue}.`);
+      } catch (err) {
+        fail(err);
+      }
+    });
+  }
+  for (const action of spec.actions ?? []) {
+    const needsId = action.needsId ?? true;
+    const cmd = withProject(
+      needsId ? group.command(action.name).description(action.describe).argument(`<${idName}>`, idName) : group.command(action.name).description(action.describe),
+      spec.scoped
+    );
+    if (action.fields) applyFields(cmd, action.fields);
+    if (action.query) applyFields(cmd, action.query);
+    const handler = async (...args) => {
+      const opts = args[args.length - 2];
+      const idValue = needsId ? args[0] : void 0;
+      try {
+        let path3 = await basePath(spec, opts.project);
+        if (needsId) path3 += `/${encodeURIComponent(idValue)}`;
+        path3 += action.suffix;
+        if (action.method === "get") {
+          const query = action.query ? buildQuery(action.query, opts) : void 0;
+          const { data: data2 } = await mgmt.get(path3, query);
+          emit(data2);
+          return;
+        }
+        if (action.multipart && action.fields) {
+          const form = await buildForm(action.fields, opts);
+          const { data: data2, status: status2 } = await mgmt.request(
+            action.method.toUpperCase(),
+            path3,
+            { form }
+          );
+          if (status2 === 204) printSuccess(`${action.name} ok.`);
+          else emit(data2);
+          return;
+        }
+        const body = action.fields ? await buildBody(action.fields, opts) : void 0;
+        const { data, status } = await mgmt.request(
+          action.method.toUpperCase(),
+          path3,
+          { body }
+        );
+        if (status === 204) printSuccess(`${action.name} ok.`);
+        else emit(data);
+      } catch (err) {
+        fail(err);
+      }
+    };
+    cmd.action(handler);
+  }
+}
+var cursor = { paginated: true };
+var SPECS = [
+  // -- Workspace ------------------------------------------------------------
+  {
+    name: "projects",
+    describe: "Manage projects",
+    scoped: false,
+    idName: "slug",
+    list: {},
+    get: true,
+    create: [
+      { flag: "--name <name>", key: "name" },
+      { flag: "--timezone <tz>", key: "timezone" }
+    ],
+    update: [
+      { flag: "--name <name>", key: "name" },
+      { flag: "--timezone <tz>", key: "timezone" }
+    ],
+    remove: true
+  },
+  {
+    name: "members",
+    describe: "Manage workspace members",
+    scoped: false,
+    idName: "userId",
+    list: {},
+    create: [
+      { flag: "--email <email>", key: "email" },
+      { flag: "--role <role>", key: "role", description: "member | admin" }
+    ],
+    remove: true
+  },
+  {
+    name: "invitations",
+    describe: "Manage workspace invitations",
+    scoped: false,
+    list: {},
+    create: [
+      { flag: "--email <email>", key: "email" },
+      { flag: "--role <role>", key: "role", description: "member | admin" }
+    ],
+    remove: true
+  },
+  {
+    // Personal access tokens (lt_pat_*) authenticate the CLI / Management API.
+    // The dashboard calls these "API keys"; `tokens` stays as a hidden alias.
+    name: "api-keys",
+    alias: "tokens",
+    segment: "tokens",
+    describe: "Manage your personal access tokens (lt_pat_*, the CLI/API credential)",
+    scoped: false,
+    list: {},
+    create: [
+      { flag: "--name <name>", key: "name" },
+      {
+        flag: "--expires-at <iso>",
+        key: "expires_at",
+        description: "Expiry as an ISO 8601 datetime (default: never)"
+      }
+    ],
+    remove: true
+  },
+  // -- Contacts & data ------------------------------------------------------
+  {
+    name: "contacts",
+    describe: "Manage contacts",
+    scoped: true,
+    idName: "externalId",
+    list: { ...cursor },
+    get: true,
+    actions: [
+      {
+        name: "suppress",
+        describe: "Suppress a contact",
+        method: "post",
+        suffix: "/suppress"
+      },
+      {
+        name: "resubscribe",
+        describe: "Resubscribe a contact",
+        method: "post",
+        suffix: "/resubscribe"
+      },
+      {
+        name: "import",
+        describe: "Upload a CSV import (--file <path> --mapping <json|@file>)",
+        method: "post",
+        needsId: false,
+        suffix: "/imports",
+        multipart: true,
+        fields: [
+          { flag: "--file <path>", key: "file", file: true },
+          { flag: "--mapping <json>", key: "mapping", json: true },
+          { flag: "--dedupe <strategy>", key: "dedupe", description: "update | skip" },
+          { flag: "--row-count <n>", key: "rowCount" }
+        ]
+      }
+    ]
+  },
+  {
+    name: "accounts",
+    describe: "Inspect accounts",
+    scoped: true,
+    idName: "externalId",
+    list: { ...cursor },
+    get: true
+  },
+  {
+    name: "events",
+    describe: "List events",
+    scoped: true,
+    list: { ...cursor, query: [{ flag: "--name <name>", key: "name" }] }
+  },
+  {
+    name: "suppressions",
+    describe: "Manage the suppression list",
+    scoped: true,
+    idName: "email",
+    list: { ...cursor },
+    create: [{ flag: "--email <email>", key: "email" }],
+    remove: true
+  },
+  {
+    name: "segments",
+    describe: "Manage segments",
+    scoped: true,
+    list: {},
+    get: true,
+    create: [
+      { flag: "--name <name>", key: "name" },
+      { flag: "--filter <json>", key: "filter", json: true }
+    ],
+    update: [
+      { flag: "--name <name>", key: "name" },
+      { flag: "--filter <json>", key: "filter", json: true }
+    ],
+    remove: true,
+    actions: [
+      {
+        name: "preview",
+        describe: "Count contacts matching a filter (--filter <json|@file>)",
+        method: "post",
+        needsId: false,
+        suffix: "/preview",
+        fields: [{ flag: "--filter <json>", key: "filter", json: true }]
+      }
+    ]
+  },
+  // -- Sequences ------------------------------------------------------------
+  {
+    name: "sequences",
+    describe: "Manage drip sequences",
+    scoped: true,
+    list: {},
+    get: true,
+    create: [{ flag: "--name <name>", key: "name" }],
+    update: [
+      { flag: "--name <name>", key: "name" },
+      { flag: "--status <status>", key: "status", description: "active | archived" }
+    ],
+    remove: true,
+    actions: [
+      {
+        name: "draft",
+        describe: "Save the draft graph + trigger",
+        method: "put",
+        suffix: "/draft",
+        fields: [
+          { flag: "--graph <json>", key: "graph", json: true },
+          { flag: "--trigger <json>", key: "trigger", json: true },
+          { flag: "--expected-revision <n>", key: "expected_revision", number: true }
+        ]
+      },
+      {
+        name: "publish",
+        describe: "Publish the current draft",
+        method: "post",
+        suffix: "/publish"
+      },
+      {
+        name: "preview",
+        describe: "Render an email node (--node-id <id>)",
+        method: "post",
+        suffix: "/preview",
+        fields: [{ flag: "--node-id <id>", key: "nodeId" }]
+      },
+      {
+        name: "test-email",
+        describe: "Send a test email (--node-id <id> --to <email>)",
+        method: "post",
+        suffix: "/test-email",
+        fields: [
+          { flag: "--node-id <id>", key: "nodeId" },
+          { flag: "--to <email>", key: "to" }
+        ]
+      },
+      {
+        name: "activity",
+        describe: "Show enrollment activity",
+        method: "get",
+        suffix: "/activity"
+      },
+      {
+        name: "versions",
+        describe: "List published versions",
+        method: "get",
+        suffix: "/versions"
+      }
+    ]
+  },
+  // -- Broadcasts -----------------------------------------------------------
+  {
+    name: "broadcasts",
+    describe: "Manage broadcasts",
+    scoped: true,
+    list: {},
+    get: true,
+    create: [{ flag: "--name <name>", key: "name" }],
+    update: [
+      { flag: "--name <name>", key: "name" },
+      { flag: "--subject <subject>", key: "subject" },
+      { flag: "--preview <preview>", key: "preview" },
+      { flag: "--audience <json>", key: "audience", json: true },
+      { flag: "--template-id <id>", key: "template_id" },
+      { flag: "--body-doc <json>", key: "body_doc", json: true }
+    ],
+    remove: true,
+    actions: [
+      {
+        name: "preflight",
+        describe: "Validate before sending",
+        method: "post",
+        suffix: "/preflight"
+      },
+      {
+        name: "schedule",
+        describe: "Schedule (--scheduled-at <iso>) or send now (omit)",
+        method: "post",
+        suffix: "/schedule",
+        fields: [{ flag: "--scheduled-at <iso>", key: "scheduled_at" }]
+      },
+      {
+        name: "cancel",
+        describe: "Cancel a scheduled or sending broadcast",
+        method: "post",
+        suffix: "/cancel"
+      },
+      {
+        name: "live",
+        describe: "Live status, stats, and recent activity",
+        method: "get",
+        suffix: "/live"
+      }
+    ]
+  },
+  // -- Templates ------------------------------------------------------------
+  {
+    name: "templates",
+    describe: "Manage email templates",
+    scoped: true,
+    list: {},
+    get: true,
+    create: [
+      { flag: "--name <name>", key: "name" },
+      { flag: "--design <json>", key: "design", json: true }
+    ],
+    update: [
+      { flag: "--name <name>", key: "name" },
+      { flag: "--design <json>", key: "design", json: true }
+    ],
+    remove: true,
+    actions: [
+      {
+        name: "default",
+        describe: "Set as the project default",
+        method: "post",
+        suffix: "/default"
+      },
+      {
+        name: "reset",
+        describe: "Reset design to a preset (--preset plain|branded)",
+        method: "post",
+        suffix: "/reset",
+        fields: [{ flag: "--preset <preset>", key: "preset" }]
+      },
+      {
+        name: "logo",
+        describe: "Upload a logo (--file <path>)",
+        method: "post",
+        suffix: "/logo",
+        multipart: true,
+        fields: [{ flag: "--file <path>", key: "file", file: true }]
+      },
+      {
+        name: "remove-logo",
+        describe: "Remove the template logo",
+        method: "delete",
+        suffix: "/logo"
+      }
+    ]
+  },
+  // -- Settings -------------------------------------------------------------
+  {
+    name: "domains",
+    describe: "Manage sending domains",
+    scoped: true,
+    list: {},
+    create: [{ flag: "--domain <domain>", key: "domain" }],
+    remove: true,
+    actions: [
+      {
+        name: "verify",
+        describe: "Re-check DKIM verification",
+        method: "post",
+        suffix: "/verify"
+      }
+    ]
+  },
+  {
+    // Project ingestion keys (lt_live_*) authenticate the SDKs / ingestion API.
+    // The dashboard calls these "Project tokens"; `keys` stays as a hidden alias.
+    name: "project-tokens",
+    alias: "keys",
+    segment: "keys",
+    describe: "Manage project ingestion keys (lt_live_*, the SDK/ingestion credential)",
+    scoped: true,
+    list: {},
+    create: [{ flag: "--name <name>", key: "name" }],
+    remove: true
+  }
+];
+function registerResourceCommands(program2) {
+  for (const spec of SPECS) register(program2, spec);
+  program2.command("me").description("Show the token's user, workspace, and role").action(async () => {
+    try {
+      const { data } = await mgmt.get("/v1/me");
+      emit(data);
+    } catch (err) {
+      fail(err);
+    }
+  });
+  program2.command("sender-identity").description("Set From / From-name / Reply-To (--from-email, --from-name, --reply-to-email)").option("-p, --project <slug>", "Project slug (default: connected project)").option("--from-email <email>", "From address").option("--from-name <name>", "From display name").option("--reply-to-email <email>", "Reply-To address").action(async (opts) => {
+    try {
+      const slug = await resolveProjectSlug(opts.project);
+      const body = {};
+      if (opts.fromEmail !== void 0) body.from_email = opts.fromEmail;
+      if (opts.fromName !== void 0) body.from_name = opts.fromName;
+      if (opts.replyToEmail !== void 0) body.reply_to_email = opts.replyToEmail;
+      const { data } = await mgmt.put(`/v1/projects/${slug}/sender-identity`, body);
+      emit(data);
+    } catch (err) {
+      fail(err);
+    }
+  });
+  program2.command("sending-mode").description("Set the sending mode (letter_subdomain | byo_domain)").argument("<mode>", "letter_subdomain | byo_domain").option("-p, --project <slug>", "Project slug (default: connected project)").action(async (mode, opts) => {
+    try {
+      const slug = await resolveProjectSlug(opts.project);
+      const { data } = await mgmt.put(`/v1/projects/${slug}/sending-mode`, {
+        sending_mode: mode
+      });
+      emit(data);
+    } catch (err) {
+      fail(err);
+    }
+  });
+}
+
 // src/index.ts
 var program = new Command();
-program.name("letter").description("Connect your app to Letter, then manage it from the command line").version("0.2.0").option("--json", "Output raw JSON (for scripting / agents)").hook("preAction", (thisCommand) => {
+program.name("letter").description("Connect your app to Letter, then manage it from the command line").version("0.3.0").option("--json", "Output raw JSON (for scripting / agents)").hook("preAction", (thisCommand) => {
   if (thisCommand.opts().json) setJsonMode(true);
 });
 registerLoginCommand(program);
 registerAuthCommands(program);
 registerStatusCommand(program);
 registerConfigCommands(program);
+registerResourceCommands(program);
 program.parseAsync();
 //# sourceMappingURL=index.js.map