@stephendolan/helpscout-cli 1.0.0

package/dist/cli.js

@@ -0,0 +1,918 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command as Command7 } from "commander";
+
+// src/lib/output.ts
+import { convert } from "html-to-text";
+var globalOutputOptions = {};
+function setOutputOptions(options) {
+  globalOutputOptions = options;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function htmlToPlainText(html) {
+  const text = convert(html, {
+    wordwrap: false,
+    preserveNewlines: false,
+    selectors: [
+      { selector: "a", options: { ignoreHref: true } },
+      { selector: "img", format: "skip" }
+    ]
+  });
+  return text.replace(/\n{3,}/g, "\n\n").replace(/[ \t]+/g, " ").trim();
+}
+function convertBodiesToPlainText(data) {
+  if (Array.isArray(data)) {
+    return data.map(convertBodiesToPlainText);
+  }
+  if (isObject(data)) {
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+      if (key === "body" && typeof value === "string") {
+        result[key] = htmlToPlainText(value);
+      } else {
+        result[key] = convertBodiesToPlainText(value);
+      }
+    }
+    return result;
+  }
+  return data;
+}
+function stripMetadata(data) {
+  if (Array.isArray(data)) {
+    return data.map(stripMetadata);
+  }
+  if (isObject(data)) {
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+      if (key === "_links" || key === "_embedded") {
+        continue;
+      }
+      result[key] = stripMetadata(value);
+    }
+    return result;
+  }
+  return data;
+}
+function stripTagStyles(data) {
+  if (Array.isArray(data)) {
+    return data.map(stripTagStyles);
+  }
+  if (isObject(data)) {
+    const result = {};
+    const isTag = "id" in data && "name" in data && "slug" in data;
+    for (const [key, value] of Object.entries(data)) {
+      if (isTag && (key === "color" || key === "styles")) {
+        continue;
+      }
+      result[key] = stripTagStyles(value);
+    }
+    return result;
+  }
+  return data;
+}
+function selectFields(data, fields) {
+  if (Array.isArray(data)) {
+    return data.map((item) => selectFields(item, fields));
+  }
+  if (isObject(data)) {
+    const hasRequestedFields = fields.some((f) => f in data);
+    if (hasRequestedFields) {
+      const result2 = {};
+      for (const field of fields) {
+        if (field in data) {
+          result2[field] = data[field];
+        }
+      }
+      return result2;
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+      result[key] = selectFields(value, fields);
+    }
+    return result;
+  }
+  return data;
+}
+function outputJson(data, options = {}) {
+  const mergedOptions = { ...globalOutputOptions, ...options };
+  let processed = data;
+  if (mergedOptions.slim) {
+    processed = stripMetadata(processed);
+  }
+  if (mergedOptions.plain) {
+    processed = convertBodiesToPlainText(processed);
+  }
+  processed = stripTagStyles(processed);
+  if (mergedOptions.fields) {
+    const fieldList = mergedOptions.fields.split(",").map((f) => f.trim());
+    processed = selectFields(processed, fieldList);
+  }
+  const jsonString = mergedOptions.compact ? JSON.stringify(processed) : JSON.stringify(processed, null, 2);
+  console.log(jsonString);
+}
+
+// src/commands/auth.ts
+import { Command } from "commander";
+
+// src/lib/auth.ts
+import { Entry } from "@napi-rs/keyring";
+
+// src/lib/config.ts
+import Conf from "conf";
+var store = new Conf({
+  projectName: "helpscout-cli"
+});
+var config = {
+  getDefaultMailbox() {
+    return store.get("defaultMailbox") || process.env.HELPSCOUT_MAILBOX_ID;
+  },
+  setDefaultMailbox(mailboxId) {
+    store.set("defaultMailbox", mailboxId);
+  },
+  clearDefaultMailbox() {
+    store.delete("defaultMailbox");
+  },
+  clear() {
+    store.clear();
+  }
+};
+
+// src/lib/auth.ts
+var SERVICE_NAME = "helpscout-cli";
+var ACCESS_TOKEN_ACCOUNT = "access-token";
+var REFRESH_TOKEN_ACCOUNT = "refresh-token";
+var APP_ID_ACCOUNT = "app-id";
+var APP_SECRET_ACCOUNT = "app-secret";
+var KEYRING_UNAVAILABLE_ERROR = "Keychain storage unavailable. Cannot store credentials securely.\nOn Linux, install libsecret: sudo apt-get install libsecret-1-dev\nThen reinstall: npm install -g @stephendolan/helpscout-cli\nAlternatively, use HELPSCOUT_APP_ID and HELPSCOUT_APP_SECRET environment variables.";
+var keyringCache = /* @__PURE__ */ new Map();
+function getKeyring(account) {
+  if (keyringCache.has(account)) {
+    return keyringCache.get(account);
+  }
+  try {
+    const entry = new Entry(SERVICE_NAME, account);
+    keyringCache.set(account, entry);
+    return entry;
+  } catch {
+    keyringCache.set(account, null);
+    return null;
+  }
+}
+async function getPassword(account) {
+  const entry = getKeyring(account);
+  if (entry) {
+    try {
+      return entry.getPassword();
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+async function setPassword(account, value) {
+  const entry = getKeyring(account);
+  if (!entry) {
+    throw new Error(KEYRING_UNAVAILABLE_ERROR);
+  }
+  entry.setPassword(value);
+}
+async function deletePassword(account) {
+  const entry = getKeyring(account);
+  if (entry) {
+    return entry.deletePassword();
+  }
+  return false;
+}
+var AuthManager = class {
+  async getAccessToken() {
+    return getPassword(ACCESS_TOKEN_ACCOUNT);
+  }
+  async setAccessToken(token) {
+    return setPassword(ACCESS_TOKEN_ACCOUNT, token);
+  }
+  async getRefreshToken() {
+    return getPassword(REFRESH_TOKEN_ACCOUNT);
+  }
+  async setRefreshToken(token) {
+    return setPassword(REFRESH_TOKEN_ACCOUNT, token);
+  }
+  async getAppId() {
+    const keychainValue = await getPassword(APP_ID_ACCOUNT);
+    return keychainValue || process.env.HELPSCOUT_APP_ID || null;
+  }
+  async setAppId(appId) {
+    return setPassword(APP_ID_ACCOUNT, appId);
+  }
+  async getAppSecret() {
+    const keychainValue = await getPassword(APP_SECRET_ACCOUNT);
+    return keychainValue || process.env.HELPSCOUT_APP_SECRET || null;
+  }
+  async setAppSecret(appSecret) {
+    return setPassword(APP_SECRET_ACCOUNT, appSecret);
+  }
+  async isAuthenticated() {
+    return await this.getAccessToken() !== null;
+  }
+  async logout() {
+    await deletePassword(ACCESS_TOKEN_ACCOUNT);
+    await deletePassword(REFRESH_TOKEN_ACCOUNT);
+    config.clearDefaultMailbox();
+  }
+  async clearAll() {
+    await deletePassword(ACCESS_TOKEN_ACCOUNT);
+    await deletePassword(REFRESH_TOKEN_ACCOUNT);
+    await deletePassword(APP_ID_ACCOUNT);
+    await deletePassword(APP_SECRET_ACCOUNT);
+    config.clear();
+  }
+};
+var auth = new AuthManager();
+
+// src/lib/errors.ts
+var HelpScoutCliError = class extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = "HelpScoutCliError";
+  }
+};
+var HelpScoutApiError = class extends Error {
+  constructor(message, apiError, statusCode) {
+    super(message);
+    this.apiError = apiError;
+    this.statusCode = statusCode;
+    this.name = "HelpScoutApiError";
+  }
+};
+var ERROR_STATUS_CODES = {
+  bad_request: 400,
+  unauthorized: 401,
+  forbidden: 403,
+  not_found: 404,
+  conflict: 409,
+  too_many_requests: 429,
+  internal_server_error: 500,
+  service_unavailable: 503
+};
+function sanitizeErrorMessage(message) {
+  const sensitivePatterns = [
+    /Bearer\s+[\w\-._~+/]+=*/gi,
+    /token[=:]\s*[\w\-._~+/]+=*/gi,
+    /client[_-]?secret[=:]\s*[\w\-._~+/]+=*/gi,
+    /authorization:\s*bearer\s+[\w\-._~+/]+=*/gi
+  ];
+  let sanitized = message;
+  for (const pattern of sensitivePatterns) {
+    sanitized = sanitized.replace(pattern, "[REDACTED]");
+  }
+  return sanitized.length > 500 ? sanitized.substring(0, 500) + "..." : sanitized;
+}
+function isErrorObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function sanitizeApiError(error) {
+  if (!isErrorObject(error)) {
+    return {
+      name: "api_error",
+      detail: "An error occurred"
+    };
+  }
+  const apiError = error;
+  let detail = "An error occurred";
+  if (apiError.error_description) {
+    detail = apiError.error_description;
+  } else if (apiError.message) {
+    detail = apiError.message;
+  } else if (apiError._embedded?.errors?.length) {
+    detail = apiError._embedded.errors.map((e) => e.message || e.path).filter(Boolean).join("; ");
+  }
+  return {
+    name: apiError.error || "api_error",
+    detail: sanitizeErrorMessage(detail)
+  };
+}
+function formatErrorResponse(name, detail, statusCode) {
+  const hint = name === "too_many_requests" ? "Help Scout API limit: 200 requests/minute. Wait a moment and retry." : void 0;
+  const response = {
+    error: { name, detail, statusCode }
+  };
+  if (hint) {
+    response.hint = hint;
+  }
+  outputJson(response);
+  process.exit(1);
+}
+function handleHelpScoutError(error) {
+  if (error instanceof HelpScoutCliError) {
+    const sanitized = sanitizeErrorMessage(error.message);
+    formatErrorResponse("cli_error", sanitized, error.statusCode || 1);
+  }
+  if (error instanceof HelpScoutApiError) {
+    const hsError = sanitizeApiError(error.apiError);
+    formatErrorResponse(
+      hsError.name,
+      hsError.detail,
+      error.statusCode || ERROR_STATUS_CODES[hsError.name] || 500
+    );
+  }
+  if (error instanceof Error) {
+    const sanitized = sanitizeErrorMessage(error.message);
+    formatErrorResponse("unknown_error", sanitized, 1);
+  }
+  formatErrorResponse("unknown_error", "An unexpected error occurred", 1);
+}
+
+// src/lib/api-client.ts
+import dotenv from "dotenv";
+dotenv.config();
+var API_BASE = "https://api.helpscout.net/v2";
+var TOKEN_URL = "https://api.helpscout.net/v2/oauth2/token";
+var HelpScoutClient = class {
+  accessToken = null;
+  clearToken() {
+    this.accessToken = null;
+  }
+  async refreshAccessToken() {
+    const appId = await auth.getAppId();
+    const appSecret = await auth.getAppSecret();
+    const refreshToken = await auth.getRefreshToken();
+    if (!appId || !appSecret) {
+      throw new HelpScoutCliError(
+        "Not configured. Please run: helpscout auth login",
+        401
+      );
+    }
+    if (refreshToken) {
+      try {
+        const response2 = await fetch(TOKEN_URL, {
+          method: "POST",
+          headers: { "Content-Type": "application/x-www-form-urlencoded" },
+          body: new URLSearchParams({
+            grant_type: "refresh_token",
+            client_id: appId,
+            client_secret: appSecret,
+            refresh_token: refreshToken
+          })
+        });
+        if (response2.ok) {
+          const data2 = await response2.json();
+          await auth.setAccessToken(data2.access_token);
+          if (data2.refresh_token) {
+            await auth.setRefreshToken(data2.refresh_token);
+          }
+          this.accessToken = data2.access_token;
+          return data2.access_token;
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        console.error(JSON.stringify({ warning: "Refresh token failed, using client credentials", reason: message }));
+      }
+    }
+    let response;
+    try {
+      response = await fetch(TOKEN_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          grant_type: "client_credentials",
+          client_id: appId,
+          client_secret: appSecret
+        })
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown network error";
+      throw new HelpScoutCliError(`Network request failed during authentication: ${message}`, 0);
+    }
+    if (!response.ok) {
+      const error = await response.json();
+      throw new HelpScoutApiError("OAuth token request failed", error, response.status);
+    }
+    const data = await response.json();
+    await auth.setAccessToken(data.access_token);
+    this.accessToken = data.access_token;
+    return data.access_token;
+  }
+  async getAccessToken() {
+    if (this.accessToken) {
+      return this.accessToken;
+    }
+    const storedToken = await auth.getAccessToken();
+    if (storedToken) {
+      this.accessToken = storedToken;
+      return storedToken;
+    }
+    return this.refreshAccessToken();
+  }
+  async request(method, path, options = {}) {
+    const { params, body, retry = true, rateLimitRetry = true } = options;
+    const url = new URL(`${API_BASE}${path}`);
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== void 0) {
+          url.searchParams.set(key, String(value));
+        }
+      });
+    }
+    const token = await this.getAccessToken();
+    const fetchOptions = {
+      method,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json"
+      }
+    };
+    if (body) {
+      fetchOptions.body = JSON.stringify(body);
+    }
+    let response;
+    try {
+      response = await fetch(url.toString(), fetchOptions);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown network error";
+      throw new HelpScoutCliError(`Network request failed: ${message}`, 0);
+    }
+    if (response.status === 401 && retry) {
+      this.accessToken = null;
+      await this.refreshAccessToken();
+      return this.request(method, path, { ...options, retry: false });
+    }
+    if (response.status === 429 && rateLimitRetry) {
+      const retryAfter = parseInt(response.headers.get("Retry-After") || "60", 10);
+      const waitSeconds = Math.min(retryAfter, 120);
+      console.error(JSON.stringify({ warning: `Rate limited. Waiting ${waitSeconds}s before retry...` }));
+      await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1e3));
+      return this.request(method, path, { ...options, rateLimitRetry: false });
+    }
+    if (response.status === 204) {
+      return {};
+    }
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new HelpScoutApiError("API request failed", error, response.status);
+    }
+    return response.json();
+  }
+  // Conversations
+  async listConversations(params = {}) {
+    const response = await this.request(
+      "GET",
+      "/conversations",
+      { params }
+    );
+    return {
+      conversations: response._embedded?.conversations || [],
+      page: response.page
+    };
+  }
+  async listAllConversations(params = {}) {
+    const allConversations = [];
+    let page = 1;
+    let totalPages = 1;
+    do {
+      const result = await this.listConversations({ ...params, page });
+      allConversations.push(...result.conversations);
+      totalPages = result.page.totalPages;
+      page++;
+    } while (page <= totalPages);
+    return allConversations;
+  }
+  async getConversation(conversationId, embed) {
+    const params = embed ? { embed } : void 0;
+    return this.request("GET", `/conversations/${conversationId}`, { params });
+  }
+  async getConversationThreads(conversationId) {
+    const response = await this.request(
+      "GET",
+      `/conversations/${conversationId}/threads`
+    );
+    return response._embedded?.threads || [];
+  }
+  async updateConversation(conversationId, data) {
+    await this.request("PATCH", `/conversations/${conversationId}`, { body: data });
+  }
+  async deleteConversation(conversationId) {
+    await this.request("DELETE", `/conversations/${conversationId}`);
+  }
+  async addConversationTag(conversationId, tag) {
+    await this.request("PUT", `/conversations/${conversationId}/tags`, {
+      body: { tags: [tag] }
+    });
+  }
+  async removeConversationTag(conversationId, tag) {
+    const conversation = await this.getConversation(conversationId);
+    const existingTags = conversation?.tags?.map((t) => t.name) || [];
+    const newTags = existingTags.filter((t) => t !== tag);
+    await this.request("PUT", `/conversations/${conversationId}/tags`, {
+      body: { tags: newTags }
+    });
+  }
+  async createReply(conversationId, data) {
+    await this.request("POST", `/conversations/${conversationId}/reply`, { body: data });
+  }
+  async createNote(conversationId, data) {
+    await this.request("POST", `/conversations/${conversationId}/notes`, { body: data });
+  }
+  // Customers
+  async listCustomers(params = {}) {
+    const response = await this.request(
+      "GET",
+      "/customers",
+      { params }
+    );
+    return {
+      customers: response._embedded?.customers || [],
+      page: response.page
+    };
+  }
+  async getCustomer(customerId) {
+    return this.request("GET", `/customers/${customerId}`);
+  }
+  async createCustomer(data) {
+    await this.request("POST", "/customers", { body: data });
+  }
+  async updateCustomer(customerId, data) {
+    await this.request("PUT", `/customers/${customerId}`, { body: data });
+  }
+  async deleteCustomer(customerId) {
+    await this.request("DELETE", `/customers/${customerId}`);
+  }
+  // Tags
+  async listTags(page) {
+    const response = await this.request(
+      "GET",
+      "/tags",
+      { params: page ? { page } : void 0 }
+    );
+    return {
+      tags: response._embedded?.tags || [],
+      page: response.page
+    };
+  }
+  async getTag(tagId) {
+    return this.request("GET", `/tags/${tagId}`);
+  }
+  // Workflows
+  async listWorkflows(params = {}) {
+    const response = await this.request(
+      "GET",
+      "/workflows",
+      { params: { mailboxId: params.mailbox, type: params.type, page: params.page } }
+    );
+    return {
+      workflows: response._embedded?.workflows || [],
+      page: response.page
+    };
+  }
+  async runWorkflow(workflowId, conversationIds) {
+    await this.request("POST", `/workflows/${workflowId}/run`, {
+      body: { conversationIds }
+    });
+  }
+  async updateWorkflowStatus(workflowId, status) {
+    await this.request("PATCH", `/workflows/${workflowId}`, {
+      body: { op: "replace", path: "/status", value: status }
+    });
+  }
+  // Mailboxes
+  async listMailboxes(page) {
+    const response = await this.request(
+      "GET",
+      "/mailboxes",
+      { params: page ? { page } : void 0 }
+    );
+    return {
+      mailboxes: response._embedded?.mailboxes || [],
+      page: response.page
+    };
+  }
+  async getMailbox(mailboxId) {
+    return this.request("GET", `/mailboxes/${mailboxId}`);
+  }
+};
+var client = new HelpScoutClient();
+
+// src/lib/command-utils.ts
+function withErrorHandling(fn) {
+  return async (...args) => {
+    try {
+      await fn(...args);
+    } catch (error) {
+      handleHelpScoutError(error);
+    }
+  };
+}
+function parseIdArg(value, resourceType = "resource") {
+  const parsed = parseInt(value, 10);
+  if (isNaN(parsed) || parsed <= 0) {
+    throw new HelpScoutCliError(`Invalid ${resourceType} ID: "${value}"`, 400);
+  }
+  return parsed;
+}
+function requireAtLeastOneField(data, operation) {
+  const hasFields = Object.values(data).some((v) => v !== void 0);
+  if (!hasFields) {
+    throw new HelpScoutCliError(`${operation} requires at least one field to update`, 400);
+  }
+}
+async function confirmDelete(resourceType, skipConfirmation) {
+  if (skipConfirmation) {
+    return true;
+  }
+  const readline = await import("readline");
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr
+  });
+  return new Promise((resolve) => {
+    rl.question(`Delete ${resourceType}? (y/N) `, (answer) => {
+      rl.close();
+      if (answer.toLowerCase() !== "y") {
+        outputJson({ cancelled: true, message: "Deletion cancelled" });
+        process.exit(0);
+      }
+      resolve(true);
+    });
+  });
+}
+
+// src/commands/auth.ts
+function createAuthCommand() {
+  const cmd = new Command("auth").description("Authentication operations");
+  cmd.command("login").description("Configure Help Scout API credentials").requiredOption("--app-id <id>", "Help Scout App ID").requiredOption("--app-secret <secret>", "Help Scout App Secret").action(withErrorHandling(async (options) => {
+    await auth.setAppId(options.appId);
+    await auth.setAppSecret(options.appSecret);
+    client.clearToken();
+    await client.refreshAccessToken();
+    outputJson({ message: "Successfully authenticated with Help Scout" });
+  }));
+  cmd.command("logout").description("Remove stored credentials").action(withErrorHandling(async () => {
+    await auth.logout();
+    client.clearToken();
+    outputJson({ message: "Logged out successfully" });
+  }));
+  cmd.command("status").description("Check authentication status").action(withErrorHandling(async () => {
+    const hasToken = await auth.isAuthenticated();
+    const hasAppId = !!await auth.getAppId();
+    const hasAppSecret = !!await auth.getAppSecret();
+    outputJson({
+      authenticated: hasToken,
+      configured: hasAppId && hasAppSecret
+    });
+  }));
+  cmd.command("refresh").description("Refresh access token").action(withErrorHandling(async () => {
+    client.clearToken();
+    await client.refreshAccessToken();
+    outputJson({ message: "Access token refreshed" });
+  }));
+  return cmd;
+}
+
+// src/commands/mailboxes.ts
+import { Command as Command2 } from "commander";
+function createMailboxesCommand() {
+  const cmd = new Command2("mailboxes").description("Mailbox operations");
+  cmd.command("list").description("List mailboxes").option("--page <number>", "Page number").action(withErrorHandling(async (options) => {
+    const result = await client.listMailboxes(options.page ? parseInt(options.page, 10) : void 0);
+    outputJson(result);
+  }));
+  cmd.command("view").description("View a mailbox").argument("<id>", "Mailbox ID").action(withErrorHandling(async (id) => {
+    const mailbox = await client.getMailbox(parseIdArg(id, "mailbox"));
+    outputJson(mailbox);
+  }));
+  cmd.command("set-default").description("Set default mailbox").argument("<id>", "Mailbox ID").action(withErrorHandling(async (id) => {
+    const mailboxId = parseIdArg(id, "mailbox");
+    config.setDefaultMailbox(String(mailboxId));
+    outputJson({ message: `Default mailbox set to ${mailboxId}` });
+  }));
+  cmd.command("get-default").description("Get default mailbox").action(withErrorHandling(async () => {
+    const mailboxId = config.getDefaultMailbox();
+    outputJson({ defaultMailbox: mailboxId || null });
+  }));
+  cmd.command("clear-default").description("Clear default mailbox").action(withErrorHandling(async () => {
+    config.clearDefaultMailbox();
+    outputJson({ message: "Default mailbox cleared" });
+  }));
+  return cmd;
+}
+
+// src/commands/conversations.ts
+import { Command as Command3 } from "commander";
+function summarizeConversations(conversations) {
+  const byStatus = {};
+  const byTag = {};
+  for (const conv of conversations) {
+    byStatus[conv.status] = (byStatus[conv.status] || 0) + 1;
+    for (const tag of conv.tags || []) {
+      byTag[tag.name] = (byTag[tag.name] || 0) + 1;
+    }
+  }
+  return {
+    total: conversations.length,
+    byStatus,
+    byTag,
+    conversations: conversations.map((c) => ({
+      id: c.id,
+      subject: c.subject,
+      status: c.status,
+      tags: (c.tags || []).map((t) => t.name),
+      preview: c.preview
+    }))
+  };
+}
+function createConversationsCommand() {
+  const cmd = new Command3("conversations").description("Conversation operations");
+  cmd.command("list").description("List conversations").option("-m, --mailbox <id>", "Filter by mailbox ID").option("-s, --status <status>", "Filter by status (active, all, closed, open, pending, spam)").option("-t, --tag <tags>", "Filter by tag(s), comma-separated").option("--assigned-to <id>", "Filter by assignee user ID").option("--modified-since <date>", "Filter by modified date (ISO 8601)").option("--sort-field <field>", "Sort by field (createdAt, modifiedAt, number, status, subject)").option("--sort-order <order>", "Sort order (asc, desc)").option("--page <number>", "Page number").option("--embed <resources>", "Embed resources (threads)").option("-q, --query <query>", "Advanced search query (see https://docs.helpscout.com/article/47-search-filters-with-operators)").option("--summary", "Output aggregated summary instead of full conversation list").action(withErrorHandling(async (options) => {
+    if (options.summary) {
+      const allConversations = await client.listAllConversations({
+        mailbox: options.mailbox,
+        status: options.status,
+        tag: options.tag,
+        assignedTo: options.assignedTo,
+        modifiedSince: options.modifiedSince,
+        query: options.query
+      });
+      const summary = summarizeConversations(allConversations);
+      outputJson(summary);
+      return;
+    }
+    const result = await client.listConversations({
+      mailbox: options.mailbox,
+      status: options.status,
+      tag: options.tag,
+      assignedTo: options.assignedTo,
+      modifiedSince: options.modifiedSince,
+      sortField: options.sortField,
+      sortOrder: options.sortOrder,
+      page: options.page ? parseInt(options.page, 10) : void 0,
+      embed: options.embed,
+      query: options.query
+    });
+    outputJson(result);
+  }));
+  cmd.command("view").description("View a conversation").argument("<id>", "Conversation ID").option("--embed <resources>", "Embed resources (threads)").action(withErrorHandling(async (id, options) => {
+    const conversation = await client.getConversation(parseIdArg(id, "conversation"), options.embed);
+    outputJson(conversation);
+  }));
+  cmd.command("threads").description("List threads for a conversation (defaults to email communications only)").argument("<id>", "Conversation ID").option("--include-notes", "Include internal notes").option("--all", "Show all thread types including lineitems, workflows, etc.").option("-t, --type <types>", "Filter by specific thread type(s), comma-separated (customer, message, note, lineitem, chat, phone, forwardchild, forwardparent, beaconchat)").action(withErrorHandling(async (id, options) => {
+    let threads = await client.getConversationThreads(parseIdArg(id, "conversation"));
+    if (options.type) {
+      const types = options.type.split(",").map((t) => t.trim().toLowerCase());
+      threads = threads.filter((t) => types.includes(t.type));
+    } else if (!options.all) {
+      const allowedTypes = options.includeNotes ? ["customer", "message", "note", "chat", "phone"] : ["customer", "message", "chat", "phone"];
+      threads = threads.filter((t) => allowedTypes.includes(t.type));
+    }
+    outputJson(threads);
+  }));
+  cmd.command("delete").description("Delete a conversation").argument("<id>", "Conversation ID").option("-y, --yes", "Skip confirmation").action(withErrorHandling(async (id, options) => {
+    await confirmDelete("conversation", options.yes);
+    await client.deleteConversation(parseIdArg(id, "conversation"));
+    outputJson({ message: "Conversation deleted" });
+  }));
+  cmd.command("add-tag").description("Add a tag to a conversation").argument("<id>", "Conversation ID").argument("<tag>", "Tag name").action(withErrorHandling(async (id, tag) => {
+    await client.addConversationTag(parseIdArg(id, "conversation"), tag);
+    outputJson({ message: `Tag "${tag}" added` });
+  }));
+  cmd.command("remove-tag").description("Remove a tag from a conversation").argument("<id>", "Conversation ID").argument("<tag>", "Tag name").action(withErrorHandling(async (id, tag) => {
+    await client.removeConversationTag(parseIdArg(id, "conversation"), tag);
+    outputJson({ message: `Tag "${tag}" removed` });
+  }));
+  cmd.command("reply").description("Reply to a conversation").argument("<id>", "Conversation ID").requiredOption("--text <text>", "Reply text").option("--user <id>", "User ID sending the reply").option("--draft", "Save as draft").option("--status <status>", "Set conversation status after reply (active, closed, pending)").action(withErrorHandling(async (id, options) => {
+    await client.createReply(parseIdArg(id, "conversation"), {
+      text: options.text,
+      user: options.user ? parseIdArg(options.user, "user") : void 0,
+      draft: options.draft,
+      status: options.status
+    });
+    outputJson({ message: "Reply sent" });
+  }));
+  cmd.command("note").description("Add a note to a conversation").argument("<id>", "Conversation ID").requiredOption("--text <text>", "Note text").option("--user <id>", "User ID adding the note").action(withErrorHandling(async (id, options) => {
+    await client.createNote(parseIdArg(id, "conversation"), {
+      text: options.text,
+      user: options.user ? parseIdArg(options.user, "user") : void 0
+    });
+    outputJson({ message: "Note added" });
+  }));
+  return cmd;
+}
+
+// src/commands/customers.ts
+import { Command as Command4 } from "commander";
+function createCustomersCommand() {
+  const cmd = new Command4("customers").description("Customer operations");
+  cmd.command("list").description("List customers").option("-m, --mailbox <id>", "Filter by mailbox ID").option("--first-name <name>", "Filter by first name").option("--last-name <name>", "Filter by last name").option("--modified-since <date>", "Filter by modified date (ISO 8601)").option("--sort-field <field>", "Sort by field (createdAt, firstName, lastName, modifiedAt)").option("--sort-order <order>", "Sort order (asc, desc)").option("--page <number>", "Page number").option("-q, --query <query>", "Advanced search query").action(withErrorHandling(async (options) => {
+    const result = await client.listCustomers({
+      mailbox: options.mailbox,
+      firstName: options.firstName,
+      lastName: options.lastName,
+      modifiedSince: options.modifiedSince,
+      sortField: options.sortField,
+      sortOrder: options.sortOrder,
+      page: options.page ? parseInt(options.page, 10) : void 0,
+      query: options.query
+    });
+    outputJson(result);
+  }));
+  cmd.command("view").description("View a customer").argument("<id>", "Customer ID").action(withErrorHandling(async (id) => {
+    const customer = await client.getCustomer(parseIdArg(id, "customer"));
+    outputJson(customer);
+  }));
+  cmd.command("create").description("Create a customer").option("--first-name <name>", "First name").option("--last-name <name>", "Last name").option("--email <email>", "Email address").option("--phone <phone>", "Phone number").action(withErrorHandling(async (options) => {
+    const data = {
+      ...options.firstName && { firstName: options.firstName },
+      ...options.lastName && { lastName: options.lastName },
+      ...options.email && { emails: [{ type: "work", value: options.email }] },
+      ...options.phone && { phones: [{ type: "work", value: options.phone }] }
+    };
+    requireAtLeastOneField(data, "Customer create");
+    await client.createCustomer(data);
+    outputJson({ message: "Customer created" });
+  }));
+  cmd.command("update").description("Update a customer").argument("<id>", "Customer ID").option("--first-name <name>", "First name").option("--last-name <name>", "Last name").option("--job-title <title>", "Job title").option("--location <location>", "Location").option("--organization <org>", "Organization").option("--background <text>", "Background notes").action(withErrorHandling(async (id, options) => {
+    const data = {
+      ...options.firstName && { firstName: options.firstName },
+      ...options.lastName && { lastName: options.lastName },
+      ...options.jobTitle && { jobTitle: options.jobTitle },
+      ...options.location && { location: options.location },
+      ...options.organization && { organization: options.organization },
+      ...options.background && { background: options.background }
+    };
+    requireAtLeastOneField(data, "Customer update");
+    await client.updateCustomer(parseIdArg(id, "customer"), data);
+    outputJson({ message: "Customer updated" });
+  }));
+  cmd.command("delete").description("Delete a customer").argument("<id>", "Customer ID").option("-y, --yes", "Skip confirmation").action(withErrorHandling(async (id, options) => {
+    await confirmDelete("customer", options.yes);
+    await client.deleteCustomer(parseIdArg(id, "customer"));
+    outputJson({ message: "Customer deleted" });
+  }));
+  return cmd;
+}
+
+// src/commands/tags.ts
+import { Command as Command5 } from "commander";
+function createTagsCommand() {
+  const cmd = new Command5("tags").description("Tag operations");
+  cmd.command("list").description("List all tags").option("--page <number>", "Page number").action(withErrorHandling(async (options) => {
+    const result = await client.listTags(options.page ? parseInt(options.page, 10) : void 0);
+    outputJson(result);
+  }));
+  cmd.command("view").description("View a tag").argument("<id>", "Tag ID").action(withErrorHandling(async (id) => {
+    const tag = await client.getTag(parseIdArg(id, "tag"));
+    outputJson(tag);
+  }));
+  return cmd;
+}
+
+// src/commands/workflows.ts
+import { Command as Command6 } from "commander";
+function createWorkflowsCommand() {
+  const cmd = new Command6("workflows").description("Workflow operations");
+  cmd.command("list").description("List workflows").option("-m, --mailbox <id>", "Filter by mailbox ID").option("-t, --type <type>", "Filter by type (manual, automatic)").option("--page <number>", "Page number").action(withErrorHandling(async (options) => {
+    const result = await client.listWorkflows({
+      mailbox: options.mailbox ? parseIdArg(options.mailbox, "mailbox") : void 0,
+      type: options.type,
+      page: options.page ? parseInt(options.page, 10) : void 0
+    });
+    outputJson(result);
+  }));
+  cmd.command("run").description("Run a manual workflow on conversations").argument("<workflow-id>", "Workflow ID").requiredOption("--conversations <ids>", "Comma-separated conversation IDs").action(withErrorHandling(async (workflowId, options) => {
+    const conversationIds = options.conversations.split(",").map((id) => parseIdArg(id.trim(), "conversation"));
+    await client.runWorkflow(parseIdArg(workflowId, "workflow"), conversationIds);
+    outputJson({ message: "Workflow executed" });
+  }));
+  cmd.command("activate").description("Activate a workflow").argument("<id>", "Workflow ID").action(withErrorHandling(async (id) => {
+    await client.updateWorkflowStatus(parseIdArg(id, "workflow"), "active");
+    outputJson({ message: "Workflow activated" });
+  }));
+  cmd.command("deactivate").description("Deactivate a workflow").argument("<id>", "Workflow ID").action(withErrorHandling(async (id) => {
+    await client.updateWorkflowStatus(parseIdArg(id, "workflow"), "inactive");
+    outputJson({ message: "Workflow deactivated" });
+  }));
+  return cmd;
+}
+
+// src/cli.ts
+var program = new Command7();
+program.name("helpscout").description("A command-line interface for Help Scout").version("1.0.0").option("-c, --compact", "Minified JSON output (single line)").option("-p, --plain", "Strip HTML from body fields, output plain text").option("--include-metadata", "Include _links and _embedded in responses (stripped by default)").option("-f, --fields <fields>", "Comma-separated list of fields to include in output").hook("preAction", (thisCommand) => {
+  const options = thisCommand.opts();
+  setOutputOptions({
+    compact: options.compact,
+    slim: !options.includeMetadata,
+    plain: options.plain,
+    fields: options.fields
+  });
+});
+program.addCommand(createAuthCommand());
+program.addCommand(createMailboxesCommand());
+program.addCommand(createConversationsCommand());
+program.addCommand(createCustomersCommand());
+program.addCommand(createTagsCommand());
+program.addCommand(createWorkflowsCommand());
+program.parseAsync().catch(() => {
+  process.exit(1);
+});
+//# sourceMappingURL=cli.js.map