@kyoji2/intercom-cli 0.1.0

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@kyoji2/intercom-cli",
+  "version": "0.1.0",
+  "description": "AI-native CLI for Intercom - manage customer conversations, contacts, messages, and support",
+  "author": "kyoji2",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kyoji2/intercom-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kyoji2/intercom-cli/issues"
+  },
+  "homepage": "https://github.com/kyoji2/intercom-cli#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "module": "src/index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./src/client.ts",
+    "./client": "./src/client.ts",
+    "./utils": "./src/utils/index.ts"
+  },
+  "bin": {
+    "intercom": "dist/index.js"
+  },
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "bun --watch src/index.ts",
+    "test": "bun test",
+    "lint": "biome check ./src ./tests",
+    "lint:fix": "biome check --write ./src ./tests",
+    "format": "biome format --write ./src ./tests",
+    "build": "bun build src/index.ts --outdir dist --target bun && chmod +x dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "intercom-client": "^7.0.1",
+    "@toon-format/toon": "^2.1.0",
+    "commander": "^14.0.2",
+    "ora": "^9.0.0",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.11",
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "keywords": [
+    "intercom",
+    "customer-support",
+    "conversations",
+    "contacts",
+    "cli",
+    "ai-native"
+  ],
+  "license": "MIT"
+}

package/src/client.ts

@@ -0,0 +1,132 @@
+import type { Intercom } from "intercom-client";
+import { IntercomClient, IntercomError } from "intercom-client";
+import { CLIError } from "./utils/output.ts";
+
+export interface ClientOptions {
+  token: string;
+  dryRun?: boolean;
+}
+
+export interface Logger {
+  log: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+}
+
+const defaultLogger: Logger = {
+  log: (msg) => console.log(msg),
+  warn: (msg) => console.warn(msg),
+  error: (msg) => console.error(msg),
+};
+
+export function createClient(options: ClientOptions, logger: Logger = defaultLogger): IntercomClient {
+  const client = new IntercomClient({ token: options.token });
+
+  if (options.dryRun) {
+    return createDryRunProxy(client, logger);
+  }
+
+  return client;
+}
+
+function createDryRunProxy(client: IntercomClient, logger: Logger): IntercomClient {
+  const writeMethodPatterns = [
+    "create",
+    "update",
+    "delete",
+    "add",
+    "remove",
+    "attach",
+    "detach",
+    "assign",
+    "close",
+    "open",
+    "snooze",
+    "redact",
+    "convert",
+    "away",
+    "tag",
+    "untag",
+  ];
+
+  const createNestedProxy = <T extends object>(target: T, path: string[]): T => {
+    return new Proxy(target, {
+      get(obj, prop: string) {
+        const value = (obj as Record<string, unknown>)[prop];
+        const currentPath = [...path, prop];
+
+        if (typeof value === "function") {
+          const isWriteMethod = writeMethodPatterns.some((pattern) =>
+            prop.toLowerCase().includes(pattern.toLowerCase()),
+          );
+
+          if (isWriteMethod) {
+            return (...args: unknown[]) => {
+              logger.log(`[DRY RUN] ${currentPath.join(".")}`);
+              if (args.length > 0 && typeof args[0] === "object") {
+                const filtered = Object.fromEntries(
+                  Object.entries(args[0] as Record<string, unknown>).filter(
+                    ([k]) => !k.toLowerCase().includes("token"),
+                  ),
+                );
+                logger.log(`Payload: ${JSON.stringify(filtered, null, 2)}`);
+              }
+              return Promise.resolve(getDryRunResponse(prop));
+            };
+          }
+
+          return value.bind(obj);
+        }
+
+        if (value && typeof value === "object") {
+          return createNestedProxy(value, currentPath);
+        }
+
+        return value;
+      },
+    });
+  };
+
+  return createNestedProxy(client, ["client"]);
+}
+
+function getDryRunResponse(method: string): unknown {
+  if (method.includes("delete") || method.includes("remove")) {
+    return { deleted: true, id: "dry-run-id" };
+  }
+
+  if (method.includes("list")) {
+    return { data: [], pages: { next: null } };
+  }
+
+  return {
+    id: "dry-run-id",
+    type: "dry-run",
+    created_at: Math.floor(Date.now() / 1000),
+  };
+}
+
+export function handleIntercomError(error: unknown): never {
+  if (error instanceof IntercomError) {
+    let hint: string | undefined;
+    if (error.statusCode === 401) {
+      hint = "Authentication failed. Try running 'intercom login' again.";
+    } else if (error.statusCode === 404) {
+      hint = "The requested resource was not found. Verify the ID is correct.";
+    } else if (error.statusCode === 400) {
+      hint = "Invalid request. Check your input parameters.";
+    } else if (error.statusCode === 429) {
+      hint = "Rate limit exceeded. Wait a few minutes before trying again.";
+    }
+    throw new CLIError(error.message, error.statusCode ?? 500, hint);
+  }
+
+  if (error instanceof CLIError) {
+    throw error;
+  }
+
+  throw new CLIError(`Unexpected error: ${error}`, 500, "Check the CLI logs or report this issue.");
+}
+
+export { IntercomClient, IntercomError };
+export type { Intercom };

package/src/commands/admins.ts

@@ -0,0 +1,77 @@
+import ora from "ora";
+import { createClient, handleIntercomError } from "../client.ts";
+import { CLIError, type GlobalOptions, getTokenAsync, output } from "../utils/index.ts";
+
+export interface AdminGetOptions extends GlobalOptions {
+  id: string;
+}
+
+export async function cmdAdminList(options: GlobalOptions): Promise<void> {
+  const token = await getTokenAsync();
+  if (!token) {
+    throw new CLIError("Not logged in", 401, "Run 'intercom login' to authenticate.");
+  }
+
+  const spinner = ora("Fetching admins...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+    const result = await client.admins.list();
+
+    spinner.stop();
+
+    output(
+      {
+        admins:
+          result.admins?.map((admin) => ({
+            id: admin?.id,
+            name: admin?.name,
+            email: admin?.email,
+            type: admin?.type,
+            away_mode_enabled: admin?.away_mode_enabled,
+          })) ?? [],
+      },
+      options.format,
+    );
+  } catch (error) {
+    spinner.fail("Failed to fetch admins");
+    handleIntercomError(error);
+  }
+}
+
+export async function cmdAdminGet(options: AdminGetOptions): Promise<void> {
+  const token = await getTokenAsync();
+  if (!token) {
+    throw new CLIError("Not logged in", 401, "Run 'intercom login' to authenticate.");
+  }
+
+  const spinner = ora("Fetching admin...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+    const admin = await client.admins.find({ admin_id: Number(options.id) });
+
+    spinner.stop();
+
+    if (!admin) {
+      throw new CLIError("Admin not found", 404);
+    }
+
+    output(
+      {
+        id: admin.id,
+        name: admin.name,
+        email: admin.email,
+        type: admin.type,
+        away_mode_enabled: admin.away_mode_enabled,
+        away_mode_reassign: admin.away_mode_reassign,
+        has_inbox_seat: admin.has_inbox_seat,
+        team_ids: admin.team_ids,
+      },
+      options.format,
+    );
+  } catch (error) {
+    spinner.fail("Failed to fetch admin");
+    handleIntercomError(error);
+  }
+}

package/src/commands/articles.ts

@@ -0,0 +1,229 @@
+import ora from "ora";
+import { createClient, handleIntercomError } from "../client.ts";
+import { CLIError, type GlobalOptions, getTokenAsync, output } from "../utils/index.ts";
+
+export interface ArticleListOptions extends GlobalOptions {
+  limit?: string;
+}
+
+export interface ArticleGetOptions extends GlobalOptions {
+  id: string;
+}
+
+export interface ArticleSearchOptions extends GlobalOptions {
+  query: string;
+  limit?: string;
+}
+
+export interface ArticleCreateOptions extends GlobalOptions {
+  title: string;
+  authorId: string;
+  body?: string;
+  description?: string;
+  state?: string;
+  parentId?: string;
+  parentType?: string;
+}
+
+export interface ArticleUpdateOptions extends GlobalOptions {
+  id: string;
+  json: string;
+}
+
+export interface ArticleDeleteOptions extends GlobalOptions {
+  id: string;
+}
+
+async function requireToken(): Promise<string> {
+  const token = await getTokenAsync();
+  if (!token) {
+    throw new CLIError("Not logged in", 401, "Run 'intercom login' to authenticate.");
+  }
+  return token;
+}
+
+export async function cmdArticleList(options: ArticleListOptions): Promise<void> {
+  const token = await requireToken();
+  const spinner = ora("Listing articles...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+    const limit = options.limit ? Number.parseInt(options.limit, 10) : 25;
+
+    const result = await client.articles.list({ per_page: Math.min(limit, 50) });
+
+    spinner.stop();
+
+    const articles: unknown[] = [];
+    for await (const article of result) {
+      articles.push({
+        id: article.id,
+        title: article.title,
+        description: article.description,
+        state: article.state,
+        url: article.url,
+        created_at: article.created_at,
+        updated_at: article.updated_at,
+      });
+      if (articles.length >= limit) break;
+    }
+
+    output({ total: articles.length, articles }, options.format);
+  } catch (error) {
+    spinner.fail("Failed to list articles");
+    handleIntercomError(error);
+  }
+}
+
+export async function cmdArticleGet(options: ArticleGetOptions): Promise<void> {
+  const token = await requireToken();
+  const spinner = ora("Fetching article...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+    const article = await client.articles.find({ article_id: Number(options.id) });
+
+    spinner.stop();
+
+    output(
+      {
+        id: article.id,
+        title: article.title,
+        description: article.description,
+        body: article.body,
+        state: article.state,
+        url: article.url,
+        author_id: article.author_id,
+        parent_id: article.parent_id,
+        parent_type: article.parent_type,
+        created_at: article.created_at,
+        updated_at: article.updated_at,
+        statistics: article.statistics,
+      },
+      options.format,
+    );
+  } catch (error) {
+    spinner.fail("Failed to fetch article");
+    handleIntercomError(error);
+  }
+}
+
+export async function cmdArticleSearch(options: ArticleSearchOptions): Promise<void> {
+  const token = await requireToken();
+  const spinner = ora("Searching articles...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+    const result = await client.articles.search({
+      phrase: options.query,
+      state: "published",
+    });
+
+    spinner.stop();
+
+    const limit = options.limit ? Number.parseInt(options.limit, 10) : 25;
+    const allArticles =
+      (result.data?.articles as Array<{
+        id?: string;
+        title?: string;
+        description?: string;
+        url?: string;
+        state?: string;
+      }>) ?? [];
+    const articles = allArticles.slice(0, limit).map((article) => ({
+      id: article.id,
+      title: article.title,
+      description: article.description,
+      url: article.url,
+      state: article.state,
+    }));
+
+    output({ total: articles.length, articles }, options.format);
+  } catch (error) {
+    spinner.fail("Failed to search articles");
+    handleIntercomError(error);
+  }
+}
+
+export async function cmdArticleCreate(options: ArticleCreateOptions): Promise<void> {
+  const token = await requireToken();
+  const spinner = ora("Creating article...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+
+    const payload: Record<string, unknown> = {
+      title: options.title,
+      author_id: Number(options.authorId),
+    };
+
+    if (options.body) payload.body = options.body;
+    if (options.description) payload.description = options.description;
+    if (options.state) payload.state = options.state;
+    if (options.parentId) payload.parent_id = Number(options.parentId);
+    if (options.parentType) payload.parent_type = options.parentType;
+
+    const article = await client.articles.create(payload as Parameters<typeof client.articles.create>[0]);
+
+    spinner.succeed("Article created");
+
+    output(
+      {
+        id: article.id,
+        title: article.title,
+        state: article.state,
+        url: article.url,
+        created_at: article.created_at,
+      },
+      options.format,
+    );
+  } catch (error) {
+    spinner.fail("Failed to create article");
+    handleIntercomError(error);
+  }
+}
+
+export async function cmdArticleUpdate(options: ArticleUpdateOptions): Promise<void> {
+  const token = await requireToken();
+  const spinner = ora("Updating article...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+
+    const parsed = JSON.parse(options.json);
+    const payload = { article_id: Number(options.id), ...parsed };
+
+    const article = await client.articles.update(payload as Parameters<typeof client.articles.update>[0]);
+
+    spinner.succeed("Article updated");
+
+    output(
+      {
+        id: article.id,
+        title: article.title,
+        updated_at: article.updated_at,
+      },
+      options.format,
+    );
+  } catch (error) {
+    spinner.fail("Failed to update article");
+    handleIntercomError(error);
+  }
+}
+
+export async function cmdArticleDelete(options: ArticleDeleteOptions): Promise<void> {
+  const token = await requireToken();
+  const spinner = ora("Deleting article...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+    const result = await client.articles.delete({ article_id: Number(options.id) });
+
+    spinner.succeed("Article deleted");
+
+    output({ deleted: true, id: result.id }, options.format);
+  } catch (error) {
+    spinner.fail("Failed to delete article");
+    handleIntercomError(error);
+  }
+}

package/src/commands/auth.ts

@@ -0,0 +1,115 @@
+import ora from "ora";
+import { createClient, handleIntercomError } from "../client.ts";
+import { CLIError, deleteConfig, type GlobalOptions, getTokenAsync, output, saveConfig } from "../utils/index.ts";
+
+export interface LoginOptions extends GlobalOptions {
+  token?: string;
+}
+
+export async function cmdLogin(options: LoginOptions): Promise<void> {
+  let token = options.token;
+
+  if (!token) {
+    const spinner = ora("Waiting for token input...").start();
+    spinner.stop();
+
+    process.stdout.write("Enter your Intercom Access Token: ");
+    const input = await new Promise<string>((resolve) => {
+      let data = "";
+      process.stdin.setEncoding("utf8");
+      process.stdin.on("data", (chunk) => {
+        data += chunk;
+        if (data.includes("\n")) {
+          process.stdin.pause();
+          resolve(data.trim());
+        }
+      });
+      process.stdin.resume();
+    });
+    token = input;
+  }
+
+  if (!token || token.trim().length === 0) {
+    throw new CLIError("No token provided", 400, "Provide a token as argument or via prompt.");
+  }
+
+  const spinner = ora("Verifying token...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+    const admin = await client.admins.identify();
+
+    if (!admin) {
+      throw new CLIError("Could not verify token", 401, "The token may be invalid or expired.");
+    }
+
+    await saveConfig({ token });
+    spinner.succeed("Logged in successfully");
+
+    output(
+      {
+        status: "success",
+        admin: {
+          id: admin.id,
+          name: admin.name,
+          email: admin.email,
+        },
+        workspace: admin.app ? { id: admin.app.id_code, name: admin.app.name } : undefined,
+      },
+      options.format,
+    );
+  } catch (error) {
+    spinner.fail("Login failed");
+    handleIntercomError(error);
+  }
+}
+
+export async function cmdLogout(options: GlobalOptions): Promise<void> {
+  await deleteConfig();
+  output({ status: "success", message: "Logged out successfully" }, options.format);
+}
+
+export async function cmdWhoami(options: GlobalOptions): Promise<void> {
+  const token = await getTokenAsync();
+  if (!token) {
+    throw new CLIError("Not logged in", 401, "Run 'intercom login' to authenticate.");
+  }
+
+  const spinner = ora("Fetching account info...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+    const admin = await client.admins.identify();
+
+    if (!admin) {
+      throw new CLIError("Could not identify admin", 401, "The token may be invalid or expired.");
+    }
+
+    spinner.stop();
+
+    output(
+      {
+        admin: {
+          id: admin.id,
+          name: admin.name,
+          email: admin.email,
+          type: admin.type,
+          away_mode_enabled: admin.away_mode_enabled,
+          away_mode_reassign: admin.away_mode_reassign,
+        },
+        workspace: admin.app
+          ? {
+              id: admin.app.id_code,
+              name: admin.app.name,
+              region: admin.app.region,
+              timezone: admin.app.timezone,
+            }
+          : undefined,
+      },
+      options.format,
+    );
+  } catch (error) {
+    spinner.fail("Failed to fetch account info");
+    handleIntercomError(error);
+  }
+}