@sentroy-co/client-sdk 2.13.9 → 2.14.0

package/src/cli/format.ts

@@ -0,0 +1,147 @@
+/**
+ * Output formatters — table (human-friendly) + json (script/automation).
+ *
+ * CLI commands accept `--output=json|table` (default: table) and call
+ * `printRows(rows, columns, flags)`.
+ */
+
+import { c } from "./args"
+
+export interface Column<T> {
+  /** Header text shown in table mode (uppercase recommended). */
+  header: string
+  /** Value extractor; should return a primitive that .toString()'s cleanly. */
+  get: (row: T) => string | number | null | undefined
+  /** Max display width — longer values get truncated with `…`. Default 40. */
+  maxWidth?: number
+  /** Right-align numeric columns. Default false. */
+  alignRight?: boolean
+}
+
+/**
+ * Print rows as a formatted table (or JSON if --output=json).
+ *
+ * Table mode uses 2-space gap between columns, dim header line, no
+ * vertical separators (keeps copy-paste clean). Empty cells render as
+ * `c.dim("—")`.
+ */
+export function printRows<T>(
+  rows: T[],
+  columns: Column<T>[],
+  flags: Record<string, string | boolean>,
+): void {
+  const output =
+    typeof flags.output === "string" ? flags.output.toLowerCase() : "table"
+  if (output === "json") {
+    // For JSON we dump the raw row objects, not the column projection —
+    // scripts may want fields beyond what we show in the table.
+    process.stdout.write(JSON.stringify(rows, null, 2) + "\n")
+    return
+  }
+  if (rows.length === 0) {
+    process.stdout.write(c.dim("(no results)") + "\n")
+    return
+  }
+  // Compute string cells + widths
+  const cells: string[][] = rows.map((row) =>
+    columns.map((col) => {
+      const v = col.get(row)
+      if (v === null || v === undefined || v === "") return ""
+      const s = String(v)
+      const max = col.maxWidth ?? 40
+      if (s.length > max) return s.slice(0, max - 1) + "…"
+      return s
+    }),
+  )
+  const widths = columns.map((col, i) => {
+    const headerWidth = col.header.length
+    const rowMax = cells.reduce((m, r) => Math.max(m, (r[i] ?? "").length), 0)
+    return Math.max(headerWidth, rowMax)
+  })
+
+  // Header
+  const headerLine = columns
+    .map((col, i) => padCell(col.header, widths[i]!, col.alignRight ?? false))
+    .join("  ")
+  process.stdout.write(c.dim(headerLine) + "\n")
+
+  // Underline
+  const underline = widths.map((w) => "─".repeat(w)).join("  ")
+  process.stdout.write(c.dim(underline) + "\n")
+
+  // Rows
+  for (const cellRow of cells) {
+    const line = columns
+      .map((col, i) => {
+        const v = cellRow[i] ?? ""
+        const padded = padCell(v || c.dim("—"), widths[i]!, col.alignRight ?? false)
+        return padded
+      })
+      .join("  ")
+    process.stdout.write(line + "\n")
+  }
+  process.stdout.write("\n" + c.dim(`${rows.length} row${rows.length === 1 ? "" : "s"}`) + "\n")
+}
+
+function padCell(text: string, width: number, alignRight: boolean): string {
+  // ANSI escape sequences mess up String.prototype.padEnd length math;
+  // strip color codes for width calculation only.
+  const visible = text.replace(/\x1b\[[0-9;]*m/g, "")
+  const pad = " ".repeat(Math.max(0, width - visible.length))
+  return alignRight ? pad + text : text + pad
+}
+
+/**
+ * Print a single object as a key/value detail panel.
+ * Used by `<group> <resource> get <id>` commands.
+ */
+export function printDetail<T extends Record<string, unknown>>(
+  obj: T,
+  flags: Record<string, string | boolean>,
+): void {
+  const output =
+    typeof flags.output === "string" ? flags.output.toLowerCase() : "table"
+  if (output === "json") {
+    process.stdout.write(JSON.stringify(obj, null, 2) + "\n")
+    return
+  }
+  const keys = Object.keys(obj)
+  if (keys.length === 0) {
+    process.stdout.write(c.dim("(empty)") + "\n")
+    return
+  }
+  const longest = keys.reduce((m, k) => Math.max(m, k.length), 0)
+  for (const k of keys) {
+    const v = obj[k]
+    const valStr =
+      v === null || v === undefined
+        ? c.dim("—")
+        : typeof v === "object"
+          ? JSON.stringify(v)
+          : String(v)
+    process.stdout.write(`${c.dim(k.padEnd(longest))}  ${valStr}\n`)
+  }
+  process.stdout.write("\n")
+}
+
+/**
+ * Localized string helper — Sentroy mail/templates fields can be either a
+ * plain string or `Record<locale, string>` (e.g. `{tr, en}`). For table
+ * display, pick "en" fallback "tr" fallback first available, otherwise
+ * the raw string.
+ */
+export function loc(value: unknown, preferred = "en"): string {
+  if (value === null || value === undefined) return ""
+  if (typeof value === "string") return value
+  if (typeof value === "object") {
+    const obj = value as Record<string, unknown>
+    const direct = obj[preferred]
+    if (typeof direct === "string") return direct
+    const tr = obj.tr
+    if (typeof tr === "string") return tr
+    for (const k of Object.keys(obj)) {
+      if (typeof obj[k] === "string") return obj[k] as string
+    }
+  }
+  return ""
+}

package/src/cli/index.ts

@@ -1,11 +1,20 @@
 /**
  * `sentroy` — CLI entry point.
  *
- * Subcommand router with no third-party deps. Today only `env` exists;
- * future subcommands (`mail`, `media`, etc.) hook in here.
+ * Subcommand router with no third-party deps. Groups:
+ *   - env       Vault sync (push/pull/list/diff) — vault-scoped token
+ *   - mail      Mail resource queries (templates/domains/mailboxes/...)
+ *   - storage   Storage resource queries (buckets/media/usage)
+ *   - ai        AI Skill install (Claude/Cursor/Windsurf/AGENTS.md)
+ *
+ * Shared helpers live in `./args` (parseFlags, resolveSharedOpts, apiFetch,
+ * c, fail, info, ok, warn) and `./format` (printRows, printDetail, loc).
  */
 
 import { cmdPush, cmdPull, cmdList, cmdDiff } from "./env"
+import { MAIL_HANDLERS } from "./mail"
+import { STORAGE_HANDLERS } from "./storage"
+import { AI_HANDLERS } from "./ai"
 
 const VERSION = "__VERSION__" // replaced at runtime via package.json read
 
@@ -33,9 +42,41 @@ const ENV_SUBCOMMANDS: Record<string, SubCommand> = {
   },
 }
 
+// MAIL/STORAGE/AI subcommands use sub-sub-command pattern:
+//   `sentroy mail templates list` → MAIL_HANDLERS["templates.list"]
+//   `sentroy mail logs get <id>`  → MAIL_HANDLERS["logs.get"]
+//
+// Router joins argv[1] + argv[2] with "." for resource+verb lookup.
+// `sentroy mail analytics` has no verb → MAIL_HANDLERS["analytics"].
+// `sentroy ai install` has no resource → AI_HANDLERS["install"].
+
+/**
+ * Maps `mail templates list` → `templatesList`, `storage buckets get` →
+ * `bucketsGet`. If verb missing, tries plain resource key (e.g. `analytics`
+ * or `usage`). Returns the handler fn + how many argv tokens it consumed
+ * past the group (2 = resource+verb, 1 = resource only) so caller can
+ * slice the rest as args.
+ */
+function resolveHandler(
+  handlers: Record<string, (args: string[]) => Promise<void> | void>,
+  resource: string,
+  verb: string | undefined,
+): { fn: (args: string[]) => Promise<void> | void; consumed: number } | null {
+  // Flag tokens are NOT verbs (e.g. `mail analytics --days=7`).
+  const verbToken = verb && !verb.startsWith("--") ? verb : undefined
+  if (verbToken) {
+    const camel =
+      resource + verbToken.charAt(0).toUpperCase() + verbToken.slice(1)
+    const h = handlers[camel]
+    if (h) return { fn: h, consumed: 3 }
+  }
+  const direct = handlers[resource]
+  if (direct) return { fn: direct, consumed: 2 }
+  return null
+}
+
 function readPackageVersion(): string {
   if (VERSION !== "__VERSION__") return VERSION
-  // Walk up from this file: dist/cli/index.js → dist/cli → dist → package.
   try {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     const { version } = require("../../package.json") as { version: string }
@@ -50,31 +91,53 @@ function showHelp(): void {
   process.stdout.write(
     `\nsentroy ${v} — Sentroy CLI\n\n` +
       `USAGE\n` +
-      `  sentroy <command> [args] [flags]\n\n` +
-      `COMMANDS\n` +
-      `  env push  [<file>]     ${ENV_SUBCOMMANDS.push.description}\n` +
-      `  env pull  [<file>]     ${ENV_SUBCOMMANDS.pull.description}\n` +
-      `  env list               ${ENV_SUBCOMMANDS.list.description}\n` +
-      `  env diff  [<file>]     ${ENV_SUBCOMMANDS.diff.description}\n\n` +
+      `  sentroy <group> <subcommand> [args] [flags]\n\n` +
+      `ENV (vault sync — requires SENTROY_ENV_API_KEY)\n` +
+      `  sentroy env push  [<file>]              ${ENV_SUBCOMMANDS.push!.description}\n` +
+      `  sentroy env pull  [<file>]              ${ENV_SUBCOMMANDS.pull!.description}\n` +
+      `  sentroy env list                        ${ENV_SUBCOMMANDS.list!.description}\n` +
+      `  sentroy env diff  [<file>]              ${ENV_SUBCOMMANDS.diff!.description}\n\n` +
+      `MAIL (requires SENTROY_API_KEY + SENTROY_COMPANY_SLUG)\n` +
+      `  sentroy mail templates list             List email templates\n` +
+      `  sentroy mail templates get <id>         Template detail\n` +
+      `  sentroy mail domains list               List sending domains\n` +
+      `  sentroy mail mailboxes list             List inbox mailboxes\n` +
+      `  sentroy mail inbox list                 Recent inbox messages (--mailbox, --folder, --unread, --q, --page, --limit)\n` +
+      `  sentroy mail suppressions list          Bounce/complaint suppressions (--domain, --reason)\n` +
+      `  sentroy mail logs list                  Delivery logs (--status, --domain, --from, --to)\n` +
+      `  sentroy mail logs get <id>              Log detail (event timeline)\n` +
+      `  sentroy mail webhooks list              Webhook endpoints (--domain)\n` +
+      `  sentroy mail analytics                  Aggregate stats (--days=7|30|90, --domain)\n\n` +
+      `STORAGE (requires SENTROY_API_KEY + SENTROY_COMPANY_SLUG)\n` +
+      `  sentroy storage buckets list            List storage buckets\n` +
+      `  sentroy storage buckets get <slug>      Bucket detail\n` +
+      `  sentroy storage media list <bucketSlug> List media in bucket (--type, --folder, --q, --sort, --dir, --limit, --skip)\n` +
+      `  sentroy storage media get <bucketSlug> <mediaId>  Media detail\n` +
+      `  sentroy storage usage                   Quota + per-bucket breakdown\n` +
+      `  sentroy storage quota                   Lightweight quota only\n\n` +
+      `AI SKILL (install the Sentroy AI agent skill into your project)\n` +
+      `  sentroy ai install                      Autodetect tools (Claude, Cursor, Windsurf) + AGENTS.md\n` +
+      `  sentroy ai install --claude             Install only into .claude/skills/sentroy/\n` +
+      `  sentroy ai install --cursor             Install only into .cursor/rules/sentroy.mdc\n` +
+      `  sentroy ai install --windsurf           Merge into .windsurfrules\n` +
+      `  sentroy ai install --agents             Merge into AGENTS.md at cwd\n` +
+      `  sentroy ai install --all                Install into every supported target\n` +
+      `  sentroy ai install --upgrade            Re-install latest, replacing existing sentinel block\n` +
+      `  sentroy ai install --check              Dry-run, show what would change\n\n` +
       `GLOBAL FLAGS\n` +
-      `  --token=stk_env_...    Vault token (default: $SENTROY_ENV_API_KEY)\n` +
-      `  --url=https://...      Sentroy core URL (default: $SENTROY_ENV_API_URL or https://sentroy.com)\n\n` +
-      `ENV PUSH FLAGS\n` +
-      `  --delete-missing       Remove vault keys not present in the local file (full sync)\n` +
-      `  --dry-run              Print the diff but do not write\n` +
-      `  --yes                  Skip the delete-confirmation prompt (CI-friendly)\n\n` +
-      `ENV PULL FLAGS\n` +
-      `  --force                Overwrite the file if it already exists\n\n` +
-      `ENV LIST FLAGS\n` +
-      `  --values               Include values (default: keys only)\n` +
-      `  --public-only          Only variables marked public\n\n` +
+      `  --token=stk_...                         Override $SENTROY_API_KEY (env vault uses $SENTROY_ENV_API_KEY)\n` +
+      `  --url=https://...                       Override base URL (default https://sentroy.com)\n` +
+      `  --company-slug=<slug>                   Override $SENTROY_COMPANY_SLUG (required for mail/storage)\n` +
+      `  --output=json|table                     Output format (default table)\n\n` +
       `EXAMPLES\n` +
       `  sentroy env push .env.production --delete-missing\n` +
-      `  sentroy env pull .env --force\n` +
-      `  sentroy env diff .env.production --delete-missing\n` +
-      `  sentroy env list --values --public-only\n\n` +
-      `Token scope (project + environment) is implicit — generate one in the\n` +
-      `Sentroy vault dashboard.\n\n`,
+      `  sentroy mail templates list --output=json | jq '.[].name'\n` +
+      `  sentroy mail logs list --status=bounced --days=7\n` +
+      `  sentroy storage buckets list\n` +
+      `  sentroy ai install\n\n` +
+      `DOCS\n` +
+      `  https://docs.sentroy.com/cli            Full CLI reference\n` +
+      `  https://docs.sentroy.com/ai-skills      AI Skill install guide\n\n`,
   )
 }
 
@@ -95,6 +158,7 @@ async function main(): Promise<void> {
   }
 
   const cmd = argv[0]
+
   if (cmd === "env") {
     const sub = argv[1]
     const handler = sub ? ENV_SUBCOMMANDS[sub] : undefined
@@ -109,6 +173,64 @@ async function main(): Promise<void> {
     return
   }
 
+  if (cmd === "mail") {
+    // `mail <resource> [verb] [args]` → handler key = resource + Capitalize(verb).
+    // Exception: `mail analytics` has no verb → handler key = "analytics".
+    const resource = argv[1]
+    const verb = argv[2]
+    if (!resource) {
+      process.stderr.write(
+        `usage: sentroy mail <resource> [verb] [args]\nresources: templates, domains, mailboxes, inbox, suppressions, logs, webhooks, analytics\n`,
+      )
+      process.exit(1)
+    }
+    const handler = resolveHandler(MAIL_HANDLERS, resource, verb)
+    if (!handler) {
+      process.stderr.write(
+        `unknown mail command: \`sentroy mail ${resource}${verb ? " " + verb : ""}\`\n` +
+          `available: ${Object.keys(MAIL_HANDLERS).join(", ")}\n`,
+      )
+      process.exit(1)
+    }
+    await handler.fn(argv.slice(handler.consumed))
+    return
+  }
+
+  if (cmd === "storage") {
+    const resource = argv[1]
+    const verb = argv[2]
+    if (!resource) {
+      process.stderr.write(
+        `usage: sentroy storage <resource> [verb] [args]\nresources: buckets, media, usage, quota\n`,
+      )
+      process.exit(1)
+    }
+    const handler = resolveHandler(STORAGE_HANDLERS, resource, verb)
+    if (!handler) {
+      process.stderr.write(
+        `unknown storage command: \`sentroy storage ${resource}${verb ? " " + verb : ""}\`\n` +
+          `available: ${Object.keys(STORAGE_HANDLERS).join(", ")}\n`,
+      )
+      process.exit(1)
+    }
+    await handler.fn(argv.slice(handler.consumed))
+    return
+  }
+
+  if (cmd === "ai") {
+    const sub = argv[1]
+    const handler = sub ? AI_HANDLERS[sub as keyof typeof AI_HANDLERS] : undefined
+    if (!handler) {
+      process.stderr.write(
+        `unknown ai subcommand: ${sub ?? "<missing>"}\n` +
+          `available: ${Object.keys(AI_HANDLERS).join(", ")}\n`,
+      )
+      process.exit(1)
+    }
+    await handler(argv.slice(2))
+    return
+  }
+
   process.stderr.write(
     `unknown command: ${cmd}\nrun \`sentroy --help\` for usage.\n`,
   )