@sentroy-co/client-sdk 2.13.9 → 2.15.0

package/src/cli/mail.ts

@@ -0,0 +1,363 @@
+/**
+ * `sentroy mail …` — read-only subcommands for the mail product.
+ *
+ * Every handler resolves shared opts (token + base URL + company slug),
+ * builds an optional query string from CLI flags, calls the platform
+ * REST API under `/api/companies/<slug>/…`, then prints the result via
+ * the shared table/json formatter (`printRows` for lists, `printDetail`
+ * for single-resource gets).
+ *
+ * Auth: Bearer `stk_…` access token (resolved by `resolveSharedOpts`).
+ * Output: table by default, `--output=json` for scripting.
+ *
+ * The handler map is exported as `MAIL_HANDLERS` so `cli/index.ts` can
+ * dispatch `sentroy mail <group> <action>` without each handler having
+ * to know about the router.
+ */
+import { apiFetch, parseFlags, resolveSharedOpts, type SharedOpts } from "./args"
+import { loc, printDetail, printRows, type Column } from "./format"
+
+// ── Types (loose — matches platform JSON shape, not Mongoose models) ────
+
+type LocalizedString = string | Record<string, string>
+
+interface TemplateRow {
+  id: string
+  name: LocalizedString
+  subject: LocalizedString
+  domainId: string
+  thumbnailUrl?: string
+  category?: string
+  createdAt: string
+}
+
+interface DomainRow {
+  id: string
+  domain: string
+  status: string
+  isAssigned: boolean
+  catchAll?: boolean
+  createdAt: string
+}
+
+interface MailboxRow {
+  id: string
+  email: string
+  domainId: string
+  isCatchAll: boolean
+  createdAt: string
+}
+
+interface InboxRow {
+  id: string
+  mailbox: string
+  folder: string
+  subject: string
+  from: string
+  to: string | string[]
+  snippet?: string
+  unread: boolean
+  receivedAt: string
+}
+
+interface SuppressionRow {
+  id: string
+  email: string
+  reason: string
+  domainId?: string
+  createdAt: string
+}
+
+interface LogRow {
+  id: string
+  messageId: string
+  to: string | string[]
+  from: string
+  subject: string
+  status: string
+  domainId?: string
+  createdAt: string
+}
+
+interface WebhookRow {
+  id: string
+  url: string
+  events: string[]
+  domainId?: string
+  active: boolean
+}
+
+// ── Query string builder ────────────────────────────────────────────────
+
+/**
+ * Build a query string from a flag map, copying only the keys listed in
+ * `keys`. Skips booleans (those are switches, not values) and undefined.
+ * Returns "" if nothing to encode — caller can append safely.
+ */
+function buildQuery(
+  flags: Record<string, string | boolean>,
+  keys: readonly { flag: string; param?: string }[],
+): string {
+  const params = new URLSearchParams()
+  for (const { flag, param } of keys) {
+    const v = flags[flag]
+    if (v === undefined) continue
+    if (typeof v === "boolean") {
+      if (v) params.set(param ?? flag, "true")
+      continue
+    }
+    params.set(param ?? flag, v)
+  }
+  const s = params.toString()
+  return s ? `?${s}` : ""
+}
+
+/** Slice ISO timestamps to "YYYY-MM-DD" or "YYYY-MM-DD HH:mm". */
+function sliceDate(value: string | undefined | null, len: 10 | 16): string {
+  if (!value) return ""
+  const s = String(value)
+  if (len === 16) return s.slice(0, 10) + " " + s.slice(11, 16)
+  return s.slice(0, 10)
+}
+
+function yesNo(value: unknown): string {
+  if (value === true) return "yes"
+  if (value === false) return "no"
+  return ""
+}
+
+function ctx(args: string[]): { positional: string[]; flags: Record<string, string | boolean>; shared: SharedOpts } {
+  const { positional, flags } = parseFlags(args)
+  const shared = resolveSharedOpts(flags, { requireCompanySlug: true })
+  return { positional, flags, shared }
+}
+
+function companyPath(shared: SharedOpts, suffix: string): string {
+  return `/api/companies/${encodeURIComponent(shared.companySlug as string)}${suffix}`
+}
+
+// ── Templates ───────────────────────────────────────────────────────────
+
+async function templatesList(args: string[]): Promise<void> {
+  const { flags, shared } = ctx(args)
+  const qs = buildQuery(flags, [
+    { flag: "page" },
+    { flag: "limit" },
+  ])
+  const data = await apiFetch<TemplateRow[]>(shared, companyPath(shared, `/templates${qs}`))
+  const cols: Column<TemplateRow>[] = [
+    { header: "ID", get: (r) => r.id, maxWidth: 24 },
+    { header: "NAME", get: (r) => loc(r.name) },
+    { header: "SUBJECT", get: (r) => loc(r.subject), maxWidth: 50 },
+    { header: "DOMAIN", get: (r) => r.domainId, maxWidth: 24 },
+    { header: "CATEGORY", get: (r) => r.category ?? "" },
+    { header: "CREATED", get: (r) => sliceDate(r.createdAt, 10) },
+  ]
+  printRows(data ?? [], cols, flags)
+}
+
+async function templatesGet(args: string[]): Promise<void> {
+  const { positional, flags, shared } = ctx(args)
+  const id = positional[0]
+  if (!id) {
+    process.stderr.write("usage: sentroy mail templates get <id>\n")
+    process.exit(1)
+  }
+  const data = await apiFetch<Record<string, unknown>>(
+    shared,
+    companyPath(shared, `/templates/${encodeURIComponent(id)}`),
+  )
+  printDetail(data ?? {}, flags)
+}
+
+// ── Domains ─────────────────────────────────────────────────────────────
+
+async function domainsList(args: string[]): Promise<void> {
+  const { flags, shared } = ctx(args)
+  const qs = buildQuery(flags, [
+    { flag: "page" },
+    { flag: "limit" },
+  ])
+  const data = await apiFetch<DomainRow[]>(shared, companyPath(shared, `/domains${qs}`))
+  const cols: Column<DomainRow>[] = [
+    { header: "ID", get: (r) => r.id, maxWidth: 24 },
+    { header: "DOMAIN", get: (r) => r.domain },
+    { header: "STATUS", get: (r) => r.status },
+    { header: "ASSIGNED", get: (r) => yesNo(r.isAssigned) },
+    { header: "CREATED", get: (r) => sliceDate(r.createdAt, 10) },
+  ]
+  printRows(data ?? [], cols, flags)
+}
+
+// ── Mailboxes ───────────────────────────────────────────────────────────
+
+async function mailboxesList(args: string[]): Promise<void> {
+  const { flags, shared } = ctx(args)
+  const qs = buildQuery(flags, [
+    { flag: "page" },
+    { flag: "limit" },
+    { flag: "domain", param: "domainId" },
+  ])
+  const data = await apiFetch<MailboxRow[]>(shared, companyPath(shared, `/mailboxes${qs}`))
+  const cols: Column<MailboxRow>[] = [
+    { header: "ID", get: (r) => r.id, maxWidth: 24 },
+    { header: "EMAIL", get: (r) => r.email },
+    { header: "DOMAIN", get: (r) => r.domainId, maxWidth: 24 },
+    { header: "CATCHALL", get: (r) => yesNo(r.isCatchAll) },
+    { header: "CREATED", get: (r) => sliceDate(r.createdAt, 10) },
+  ]
+  printRows(data ?? [], cols, flags)
+}
+
+// ── Inbox ───────────────────────────────────────────────────────────────
+
+async function inboxList(args: string[]): Promise<void> {
+  const { flags, shared } = ctx(args)
+  const qs = buildQuery(flags, [
+    { flag: "mailbox" },
+    { flag: "folder" },
+    { flag: "unread" },
+    { flag: "page" },
+    { flag: "limit" },
+    { flag: "q" },
+  ])
+  const data = await apiFetch<InboxRow[]>(shared, companyPath(shared, `/inbox${qs}`))
+  const cols: Column<InboxRow>[] = [
+    { header: "ID", get: (r) => r.id, maxWidth: 24 },
+    { header: "MAILBOX", get: (r) => r.mailbox },
+    { header: "FOLDER", get: (r) => r.folder },
+    { header: "FROM", get: (r) => r.from, maxWidth: 40 },
+    { header: "SUBJECT", get: (r) => r.subject, maxWidth: 40 },
+    { header: "UNREAD", get: (r) => yesNo(r.unread) },
+    { header: "RECEIVED", get: (r) => sliceDate(r.receivedAt, 16) },
+  ]
+  printRows(data ?? [], cols, flags)
+}
+
+// ── Suppressions ────────────────────────────────────────────────────────
+
+async function suppressionsList(args: string[]): Promise<void> {
+  const { flags, shared } = ctx(args)
+  const qs = buildQuery(flags, [
+    { flag: "page" },
+    { flag: "limit" },
+    { flag: "domain", param: "domainId" },
+    { flag: "reason" },
+  ])
+  const data = await apiFetch<SuppressionRow[]>(shared, companyPath(shared, `/suppressions${qs}`))
+  const cols: Column<SuppressionRow>[] = [
+    { header: "ID", get: (r) => r.id, maxWidth: 24 },
+    { header: "EMAIL", get: (r) => r.email },
+    { header: "REASON", get: (r) => r.reason, maxWidth: 20 },
+    { header: "DOMAIN", get: (r) => r.domainId ?? "", maxWidth: 24 },
+    { header: "CREATED", get: (r) => sliceDate(r.createdAt, 10) },
+  ]
+  printRows(data ?? [], cols, flags)
+}
+
+// ── Logs ────────────────────────────────────────────────────────────────
+
+async function logsList(args: string[]): Promise<void> {
+  const { flags, shared } = ctx(args)
+  const qs = buildQuery(flags, [
+    { flag: "page" },
+    { flag: "limit" },
+    { flag: "status" },
+    { flag: "domain", param: "domainId" },
+    { flag: "from" },
+    { flag: "to" },
+  ])
+  const data = await apiFetch<LogRow[]>(shared, companyPath(shared, `/logs${qs}`))
+  const cols: Column<LogRow>[] = [
+    { header: "ID", get: (r) => r.id, maxWidth: 24 },
+    { header: "MESSAGE", get: (r) => r.messageId, maxWidth: 24 },
+    { header: "TO", get: (r) => Array.isArray(r.to) ? r.to.join(",") : r.to },
+    { header: "STATUS", get: (r) => r.status },
+    { header: "DOMAIN", get: (r) => r.domainId ?? "", maxWidth: 24 },
+    { header: "CREATED", get: (r) => sliceDate(r.createdAt, 16) },
+  ]
+  printRows(data ?? [], cols, flags)
+}
+
+async function logsGet(args: string[]): Promise<void> {
+  const { positional, flags, shared } = ctx(args)
+  const id = positional[0]
+  if (!id) {
+    process.stderr.write("usage: sentroy mail logs get <id>\n")
+    process.exit(1)
+  }
+  const data = await apiFetch<Record<string, unknown>>(
+    shared,
+    companyPath(shared, `/logs/${encodeURIComponent(id)}`),
+  )
+  printDetail(data ?? {}, flags)
+}
+
+// ── Webhooks ────────────────────────────────────────────────────────────
+
+async function webhooksList(args: string[]): Promise<void> {
+  const { flags, shared } = ctx(args)
+  const qs = buildQuery(flags, [
+    { flag: "domain", param: "domainId" },
+  ])
+  const data = await apiFetch<WebhookRow[]>(shared, companyPath(shared, `/webhooks${qs}`))
+  const cols: Column<WebhookRow>[] = [
+    { header: "ID", get: (r) => r.id, maxWidth: 24 },
+    { header: "URL", get: (r) => r.url, maxWidth: 50 },
+    { header: "DOMAIN", get: (r) => r.domainId ?? "", maxWidth: 24 },
+    { header: "ACTIVE", get: (r) => yesNo(r.active) },
+  ]
+  printRows(data ?? [], cols, flags)
+}
+
+// ── Analytics ───────────────────────────────────────────────────────────
+
+interface AnalyticsResponse {
+  windowDays?: number
+  overview?: Record<string, unknown>
+  prevOverview?: Record<string, unknown>
+  daily?: unknown[]
+  domains?: unknown[]
+  recentLogs?: unknown[]
+}
+
+async function analytics(args: string[]): Promise<void> {
+  const { flags, shared } = ctx(args)
+  const qs = buildQuery(flags, [
+    { flag: "days" },
+    { flag: "domain", param: "domainId" },
+  ])
+  const data = await apiFetch<AnalyticsResponse>(shared, companyPath(shared, `/analytics${qs}`))
+  const output =
+    typeof flags.output === "string" ? flags.output.toLowerCase() : "table"
+  if (output === "json") {
+    process.stdout.write(JSON.stringify(data ?? {}, null, 2) + "\n")
+    return
+  }
+  const overview = (data?.overview ?? {}) as Record<string, unknown>
+  const summary: Record<string, unknown> = {
+    windowDays: data?.windowDays ?? "",
+    ...overview,
+  }
+  printDetail(summary, flags)
+  process.stdout.write(
+    "\x1b[2m(overview shown — pass --output=json for full daily/domain/recentLogs breakdown)\x1b[0m\n",
+  )
+}
+
+// ── Router export ───────────────────────────────────────────────────────
+
+export const MAIL_HANDLERS = {
+  templatesList,
+  templatesGet,
+  domainsList,
+  mailboxesList,
+  inboxList,
+  suppressionsList,
+  logsList,
+  logsGet,
+  webhooksList,
+  analytics,
+} as const
+
+export type MailHandlerName = keyof typeof MAIL_HANDLERS

package/src/cli/storage.ts

@@ -0,0 +1,307 @@
+/**
+ * `sentroy storage <subcommand>` — bucket + media browsing for the
+ * Sentroy storage product.
+ *
+ * Mirrors the dashboard at https://storage.sentroy.com but stays
+ * read-only: list/get buckets and media, surface usage + quota. Mutating
+ * ops (upload/delete) are intentionally not in this CLI — use the SDK or
+ * dashboard, which give you progress + crop UX.
+ *
+ * Auth: Bearer stk_… via `resolveSharedOpts({requireCompanySlug: true})`.
+ * Every path is prefixed `/api/companies/<slug>`.
+ */
+
+import {
+  parseFlags,
+  resolveSharedOpts,
+  apiFetch,
+  fail,
+  info,
+  c,
+  type SharedOpts,
+} from "./args"
+import { printRows, printDetail, type Column } from "./format"
+
+// ── Types (loose — match server response shape) ─────────────────────────
+
+interface Bucket {
+  id: string
+  name: string
+  slug: string
+  description?: string | null
+  isPublic: boolean
+  storageUsed: number
+  fileCount: number
+  createdAt: string
+  updatedAt?: string
+  [k: string]: unknown
+}
+
+interface Media {
+  id: string
+  bucketId?: string
+  originalName: string
+  fileName?: string
+  type: string
+  mimeType: string
+  size: number
+  folder?: string | null
+  isPublic: boolean
+  url?: string
+  imageMeta?: Record<string, unknown> | null
+  audioMeta?: Record<string, unknown> | null
+  videoMeta?: Record<string, unknown> | null
+  tags?: string[]
+  createdAt?: string
+  [k: string]: unknown
+}
+
+interface MediaListResponse {
+  items: Media[]
+  total: number
+  limit: number
+  skip: number
+  sort?: string
+  dir?: string
+}
+
+interface QuotaResponse {
+  used: number
+  limit: number
+  remaining: number
+}
+
+interface UsageResponse {
+  quota: QuotaResponse
+  buckets: Array<{
+    id: string
+    name: string
+    slug: string
+    storageUsed: number
+    fileCount: number
+  }>
+  byType: Record<string, { count: number; size: number }>
+  timeSeries: Array<{ date: string; size: number; count: number }>
+  recent: Media[]
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────
+
+function humanBytes(n: number | null | undefined): string {
+  if (n === null || n === undefined || !Number.isFinite(n)) return "—"
+  if (n < 1024) return `${n} B`
+  const units = ["KB", "MB", "GB", "TB"]
+  let v = n / 1024
+  let i = 0
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024
+    i++
+  }
+  return `${v.toFixed(1)} ${units[i]}`
+}
+
+function yesNo(v: unknown): string {
+  return v ? "yes" : "no"
+}
+
+function shortDate(v: unknown): string {
+  if (typeof v !== "string" || v.length < 10) return ""
+  return v.slice(0, 10)
+}
+
+function companyPrefix(shared: SharedOpts): string {
+  if (!shared.companySlug) {
+    fail("internal: company slug missing after resolveSharedOpts guard")
+  }
+  return `/api/companies/${encodeURIComponent(shared.companySlug)}`
+}
+
+/** Append flag-derived query params; only emits keys whose flag is set. */
+function buildQuery(
+  flags: Record<string, string | boolean>,
+  keys: string[],
+): string {
+  const params: string[] = []
+  for (const k of keys) {
+    const raw = flags[k]
+    if (raw === undefined || raw === false) continue
+    const value = raw === true ? "" : String(raw)
+    if (!value) continue
+    params.push(`${encodeURIComponent(k)}=${encodeURIComponent(value)}`)
+  }
+  return params.length ? `?${params.join("&")}` : ""
+}
+
+// ── Column specs ────────────────────────────────────────────────────────
+
+const BUCKET_COLUMNS: Column<Bucket>[] = [
+  { header: "ID", get: (b) => b.id, maxWidth: 24 },
+  { header: "NAME", get: (b) => b.name, maxWidth: 32 },
+  { header: "SLUG", get: (b) => b.slug, maxWidth: 32 },
+  { header: "PUBLIC", get: (b) => yesNo(b.isPublic), maxWidth: 6 },
+  { header: "USED", get: (b) => humanBytes(b.storageUsed), alignRight: true },
+  { header: "FILES", get: (b) => b.fileCount, alignRight: true },
+  { header: "CREATED", get: (b) => shortDate(b.createdAt), maxWidth: 10 },
+]
+
+const MEDIA_COLUMNS: Column<Media>[] = [
+  { header: "ID", get: (m) => m.id, maxWidth: 24 },
+  { header: "NAME", get: (m) => m.originalName, maxWidth: 40 },
+  { header: "TYPE", get: (m) => m.type, maxWidth: 12 },
+  { header: "MIME", get: (m) => m.mimeType, maxWidth: 24 },
+  { header: "SIZE", get: (m) => humanBytes(m.size), alignRight: true },
+  { header: "FOLDER", get: (m) => m.folder ?? "", maxWidth: 24 },
+  { header: "PUBLIC", get: (m) => yesNo(m.isPublic), maxWidth: 6 },
+]
+
+// ── Subcommand handlers ─────────────────────────────────────────────────
+
+async function bucketsList(argv: string[]): Promise<void> {
+  const { flags } = parseFlags(argv)
+  const shared = resolveSharedOpts(flags, { requireCompanySlug: true })
+  const data = await apiFetch<Bucket[] | { items: Bucket[] }>(
+    shared,
+    `${companyPrefix(shared)}/buckets`,
+  )
+  const rows = Array.isArray(data) ? data : (data?.items ?? [])
+  printRows(rows, BUCKET_COLUMNS, flags)
+}
+
+async function bucketsGet(argv: string[]): Promise<void> {
+  const { positional, flags } = parseFlags(argv)
+  const bucketSlug = positional[0]
+  if (!bucketSlug) {
+    fail("usage: sentroy storage buckets get <bucketSlug>")
+  }
+  const shared = resolveSharedOpts(flags, { requireCompanySlug: true })
+  const data = await apiFetch<Bucket>(
+    shared,
+    `${companyPrefix(shared)}/buckets/${encodeURIComponent(bucketSlug)}`,
+  )
+  printDetail(data as unknown as Record<string, unknown>, flags)
+}
+
+async function mediaList(argv: string[]): Promise<void> {
+  const { positional, flags } = parseFlags(argv)
+  const bucketSlug = positional[0]
+  if (!bucketSlug) {
+    fail(
+      "usage: sentroy storage media list <bucketSlug> [--type= --folder= --q= --sort= --dir= --limit= --skip=]",
+    )
+  }
+  const shared = resolveSharedOpts(flags, { requireCompanySlug: true })
+  const query = buildQuery(flags, [
+    "type",
+    "folder",
+    "q",
+    "sort",
+    "dir",
+    "limit",
+    "skip",
+  ])
+  const data = await apiFetch<MediaListResponse>(
+    shared,
+    `${companyPrefix(shared)}/buckets/${encodeURIComponent(bucketSlug)}/media${query}`,
+  )
+  const items = data?.items ?? []
+  printRows(items, MEDIA_COLUMNS, flags)
+
+  // Footer only in table mode — JSON consumers get total/limit/skip in payload.
+  const output =
+    typeof flags.output === "string" ? flags.output.toLowerCase() : "table"
+  if (output !== "json") {
+    const total = data?.total ?? items.length
+    const limit = data?.limit ?? items.length
+    const skip = data?.skip ?? 0
+    const page = limit > 0 ? Math.floor(skip / limit) + 1 : 1
+    const pages = limit > 0 ? Math.max(1, Math.ceil(total / limit)) : 1
+    info(`Total: ${total} item${total === 1 ? "" : "s"}, page ${page}/${pages}`)
+  }
+}
+
+async function mediaGet(argv: string[]): Promise<void> {
+  const { positional, flags } = parseFlags(argv)
+  const bucketSlug = positional[0]
+  const mediaId = positional[1]
+  if (!bucketSlug || !mediaId) {
+    fail("usage: sentroy storage media get <bucketSlug> <mediaId>")
+  }
+  const shared = resolveSharedOpts(flags, { requireCompanySlug: true })
+  const data = await apiFetch<Media>(
+    shared,
+    `${companyPrefix(shared)}/buckets/${encodeURIComponent(bucketSlug)}/media/${encodeURIComponent(mediaId)}`,
+  )
+  printDetail(data as unknown as Record<string, unknown>, flags)
+}
+
+async function usage(argv: string[]): Promise<void> {
+  const { flags } = parseFlags(argv)
+  const shared = resolveSharedOpts(flags, { requireCompanySlug: true })
+  const data = await apiFetch<UsageResponse>(
+    shared,
+    `${companyPrefix(shared)}/usage`,
+  )
+
+  const output =
+    typeof flags.output === "string" ? flags.output.toLowerCase() : "table"
+  if (output === "json") {
+    process.stdout.write(JSON.stringify(data, null, 2) + "\n")
+    return
+  }
+
+  // Table mode renders quota summary only — the nested arrays
+  // (buckets, byType, timeSeries, recent) bloat the terminal; nudge to
+  // --output=json for the full picture.
+  const quota = data?.quota ?? { used: 0, limit: 0, remaining: 0 }
+  const pct =
+    quota.limit > 0 ? ((quota.used / quota.limit) * 100).toFixed(1) + "%" : "—"
+  printDetail(
+    {
+      used: humanBytes(quota.used),
+      limit: humanBytes(quota.limit),
+      remaining: humanBytes(quota.remaining),
+      utilization: pct,
+      buckets: data?.buckets?.length ?? 0,
+      recentItems: data?.recent?.length ?? 0,
+    },
+    flags,
+  )
+  info(`Pass ${c.cyan("--output=json")} for the full byType / timeSeries / recent payload.`)
+}
+
+async function quota(argv: string[]): Promise<void> {
+  const { flags } = parseFlags(argv)
+  const shared = resolveSharedOpts(flags, { requireCompanySlug: true })
+  const data = await apiFetch<QuotaResponse>(
+    shared,
+    `${companyPrefix(shared)}/storage-quota`,
+  )
+  const output =
+    typeof flags.output === "string" ? flags.output.toLowerCase() : "table"
+  if (output === "json") {
+    process.stdout.write(JSON.stringify(data, null, 2) + "\n")
+    return
+  }
+  const pct =
+    data.limit > 0 ? ((data.used / data.limit) * 100).toFixed(1) + "%" : "—"
+  printDetail(
+    {
+      used: humanBytes(data.used),
+      limit: humanBytes(data.limit),
+      remaining: humanBytes(data.remaining),
+      utilization: pct,
+    },
+    flags,
+  )
+}
+
+// ── Export ──────────────────────────────────────────────────────────────
+
+export const STORAGE_HANDLERS = {
+  bucketsList,
+  bucketsGet,
+  mediaList,
+  mediaGet,
+  usage,
+  quota,
+}