@kyoji2/intercom-cli 0.1.0

package/src/commands/conversations.ts

@@ -0,0 +1,350 @@
+import ora from "ora";
+import { createClient, handleIntercomError } from "../client.ts";
+import { CLIError, type GlobalOptions, getTokenAsync, output } from "../utils/index.ts";
+
+export interface ConversationListOptions extends GlobalOptions {
+  limit?: string;
+}
+
+export interface ConversationGetOptions extends GlobalOptions {
+  id: string;
+}
+
+export interface ConversationSearchOptions extends GlobalOptions {
+  json?: string;
+  state?: string;
+  assignee?: string;
+  limit?: string;
+}
+
+export interface ConversationReplyOptions extends GlobalOptions {
+  id: string;
+  adminId: string;
+  body: string;
+  json?: string;
+}
+
+export interface ConversationAssignOptions extends GlobalOptions {
+  id: string;
+  adminId: string;
+  assigneeId: string;
+}
+
+export interface ConversationCloseOptions extends GlobalOptions {
+  id: string;
+  adminId: string;
+}
+
+export interface ConversationOpenOptions extends GlobalOptions {
+  id: string;
+  adminId: string;
+}
+
+export interface ConversationSnoozeOptions extends GlobalOptions {
+  id: string;
+  adminId: string;
+  until: 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 cmdConversationList(options: ConversationListOptions): Promise<void> {
+  const token = await requireToken();
+  const spinner = ora("Listing conversations...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+    const limit = options.limit ? Number.parseInt(options.limit, 10) : 25;
+
+    const result = await client.conversations.list({ per_page: Math.min(limit, 50) });
+
+    spinner.stop();
+
+    const conversations: unknown[] = [];
+    for await (const conv of result) {
+      conversations.push({
+        id: conv.id,
+        state: conv.state,
+        title: conv.title,
+        created_at: conv.created_at,
+        updated_at: conv.updated_at,
+        waiting_since: conv.waiting_since,
+        snoozed_until: conv.snoozed_until,
+        open: conv.open,
+        read: conv.read,
+        priority: conv.priority,
+      });
+      if (conversations.length >= limit) break;
+    }
+
+    output({ total: conversations.length, conversations }, options.format);
+  } catch (error) {
+    spinner.fail("Failed to list conversations");
+    handleIntercomError(error);
+  }
+}
+
+export async function cmdConversationGet(options: ConversationGetOptions): Promise<void> {
+  const token = await requireToken();
+  const spinner = ora("Fetching conversation...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+    const conv = await client.conversations.find({ conversation_id: options.id });
+
+    spinner.stop();
+
+    output(
+      {
+        id: conv.id,
+        state: conv.state,
+        title: conv.title,
+        created_at: conv.created_at,
+        updated_at: conv.updated_at,
+        waiting_since: conv.waiting_since,
+        snoozed_until: conv.snoozed_until,
+        open: conv.open,
+        read: conv.read,
+        priority: conv.priority,
+        source: conv.source,
+        contacts: conv.contacts,
+        teammates: conv.teammates,
+        admin_assignee_id: conv.admin_assignee_id,
+        team_assignee_id: conv.team_assignee_id,
+        tags: conv.tags,
+        first_contact_reply: conv.first_contact_reply,
+        sla_applied: conv.sla_applied,
+        statistics: conv.statistics,
+        conversation_parts: conv.conversation_parts,
+      },
+      options.format,
+    );
+  } catch (error) {
+    spinner.fail("Failed to fetch conversation");
+    handleIntercomError(error);
+  }
+}
+
+export async function cmdConversationSearch(options: ConversationSearchOptions): Promise<void> {
+  const token = await requireToken();
+  const spinner = ora("Searching conversations...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+
+    let query: Record<string, unknown>;
+    if (options.json) {
+      query = JSON.parse(options.json);
+    } else if (options.state) {
+      query = {
+        query: {
+          field: "state",
+          operator: "=",
+          value: options.state,
+        },
+      };
+    } else if (options.assignee) {
+      query = {
+        query: {
+          field: "admin_assignee_id",
+          operator: "=",
+          value: Number.parseInt(options.assignee, 10),
+        },
+      };
+    } else {
+      throw new CLIError("Search requires --json, --state, or --assignee", 400);
+    }
+
+    if (options.limit) {
+      query.pagination = { per_page: Number.parseInt(options.limit, 10) };
+    }
+
+    const searchPayload = { query: query.query, pagination: query.pagination };
+    const result = await client.conversations.search(
+      searchPayload as Parameters<typeof client.conversations.search>[0],
+    );
+
+    spinner.stop();
+
+    const conversations: unknown[] = [];
+    for await (const conv of result) {
+      conversations.push({
+        id: conv.id,
+        state: conv.state,
+        title: conv.title,
+        created_at: conv.created_at,
+        updated_at: conv.updated_at,
+      });
+      if (options.limit && conversations.length >= Number.parseInt(options.limit, 10)) break;
+    }
+
+    output({ total: conversations.length, conversations }, options.format);
+  } catch (error) {
+    spinner.fail("Failed to search conversations");
+    handleIntercomError(error);
+  }
+}
+
+export async function cmdConversationReply(options: ConversationReplyOptions): Promise<void> {
+  const token = await requireToken();
+  const spinner = ora("Sending reply...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+
+    const result = await client.conversations.reply({
+      conversation_id: options.id,
+      body: {
+        message_type: "comment",
+        type: "admin",
+        admin_id: options.adminId,
+        body: options.body,
+      },
+    });
+
+    spinner.succeed("Reply sent");
+
+    output(
+      {
+        id: result.id,
+        state: result.state,
+        conversation_parts: result.conversation_parts,
+      },
+      options.format,
+    );
+  } catch (error) {
+    spinner.fail("Failed to send reply");
+    handleIntercomError(error);
+  }
+}
+
+export async function cmdConversationAssign(options: ConversationAssignOptions): Promise<void> {
+  const token = await requireToken();
+  const spinner = ora("Assigning conversation...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+
+    const result = await client.conversations.manage({
+      conversation_id: options.id,
+      body: {
+        message_type: "assignment",
+        type: "admin",
+        admin_id: options.adminId,
+        assignee_id: options.assigneeId,
+      },
+    });
+
+    spinner.succeed("Conversation assigned");
+
+    output(
+      {
+        id: result.id,
+        admin_assignee_id: result.admin_assignee_id,
+      },
+      options.format,
+    );
+  } catch (error) {
+    spinner.fail("Failed to assign conversation");
+    handleIntercomError(error);
+  }
+}
+
+export async function cmdConversationClose(options: ConversationCloseOptions): Promise<void> {
+  const token = await requireToken();
+  const spinner = ora("Closing conversation...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+
+    const result = await client.conversations.manage({
+      conversation_id: options.id,
+      body: {
+        message_type: "close",
+        type: "admin",
+        admin_id: options.adminId,
+      },
+    });
+
+    spinner.succeed("Conversation closed");
+
+    output(
+      {
+        id: result.id,
+        state: result.state,
+      },
+      options.format,
+    );
+  } catch (error) {
+    spinner.fail("Failed to close conversation");
+    handleIntercomError(error);
+  }
+}
+
+export async function cmdConversationOpen(options: ConversationOpenOptions): Promise<void> {
+  const token = await requireToken();
+  const spinner = ora("Opening conversation...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+
+    const result = await client.conversations.manage({
+      conversation_id: options.id,
+      body: {
+        message_type: "open",
+        admin_id: options.adminId,
+      },
+    });
+
+    spinner.succeed("Conversation opened");
+
+    output(
+      {
+        id: result.id,
+        state: result.state,
+      },
+      options.format,
+    );
+  } catch (error) {
+    spinner.fail("Failed to open conversation");
+    handleIntercomError(error);
+  }
+}
+
+export async function cmdConversationSnooze(options: ConversationSnoozeOptions): Promise<void> {
+  const token = await requireToken();
+  const spinner = ora("Snoozing conversation...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+
+    const result = await client.conversations.manage({
+      conversation_id: options.id,
+      body: {
+        message_type: "snoozed",
+        admin_id: options.adminId,
+        snoozed_until: Number.parseInt(options.until, 10),
+      },
+    });
+
+    spinner.succeed("Conversation snoozed");
+
+    output(
+      {
+        id: result.id,
+        state: result.state,
+        snoozed_until: result.snoozed_until,
+      },
+      options.format,
+    );
+  } catch (error) {
+    spinner.fail("Failed to snooze conversation");
+    handleIntercomError(error);
+  }
+}

package/src/commands/events.ts

@@ -0,0 +1,91 @@
+import ora from "ora";
+import { createClient, handleIntercomError } from "../client.ts";
+import { CLIError, type GlobalOptions, getTokenAsync, output } from "../utils/index.ts";
+
+export interface EventTrackOptions extends GlobalOptions {
+  name: string;
+  userId?: string;
+  email?: string;
+  metadata?: string;
+}
+
+export interface EventListOptions extends GlobalOptions {
+  userId: 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 cmdEventTrack(options: EventTrackOptions): Promise<void> {
+  const token = await requireToken();
+  const spinner = ora("Tracking event...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+
+    if (!options.userId && !options.email) {
+      throw new CLIError("Event requires --user-id or --email", 400);
+    }
+
+    const payload: Record<string, unknown> = {
+      event_name: options.name,
+      created_at: Math.floor(Date.now() / 1000),
+    };
+
+    if (options.userId) payload.user_id = options.userId;
+    if (options.email) payload.email = options.email;
+    if (options.metadata) payload.metadata = JSON.parse(options.metadata);
+
+    await client.events.create(payload as Parameters<typeof client.events.create>[0]);
+
+    spinner.succeed("Event tracked");
+
+    output(
+      {
+        status: "success",
+        event_name: options.name,
+        user_id: options.userId,
+        email: options.email,
+      },
+      options.format,
+    );
+  } catch (error) {
+    spinner.fail("Failed to track event");
+    handleIntercomError(error);
+  }
+}
+
+export async function cmdEventList(options: EventListOptions): Promise<void> {
+  const token = await requireToken();
+  const spinner = ora("Fetching events...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+    const result = await client.events.list({
+      type: "user",
+      user_id: options.userId,
+    });
+
+    spinner.stop();
+
+    const events =
+      result.events
+        ?.filter((event): event is NonNullable<typeof event> => event != null)
+        .map((event) => ({
+          name: event.name,
+          first: event.first,
+          last: event.last,
+          count: event.count,
+        })) ?? [];
+
+    output({ total: events.length, events }, options.format);
+  } catch (error) {
+    spinner.fail("Failed to fetch events");
+    handleIntercomError(error);
+  }
+}

package/src/commands/index.ts

@@ -0,0 +1,82 @@
+// Auth commands
+
+export type { AdminGetOptions } from "./admins.ts";
+// Admin commands
+export { cmdAdminGet, cmdAdminList } from "./admins.ts";
+export type {
+  ArticleCreateOptions,
+  ArticleDeleteOptions,
+  ArticleGetOptions,
+  ArticleListOptions,
+  ArticleSearchOptions,
+  ArticleUpdateOptions,
+} from "./articles.ts";
+// Article commands
+export {
+  cmdArticleCreate,
+  cmdArticleDelete,
+  cmdArticleGet,
+  cmdArticleList,
+  cmdArticleSearch,
+  cmdArticleUpdate,
+} from "./articles.ts";
+export type { LoginOptions } from "./auth.ts";
+export { cmdLogin, cmdLogout, cmdWhoami } from "./auth.ts";
+export type { CompanyCreateOptions, CompanyGetOptions, CompanyListOptions, CompanyUpdateOptions } from "./companies.ts";
+// Company commands
+export { cmdCompanyCreate, cmdCompanyGet, cmdCompanyList, cmdCompanyUpdate } from "./companies.ts";
+export type {
+  ContactAttachCompanyOptions,
+  ContactCreateOptions,
+  ContactDeleteOptions,
+  ContactGetOptions,
+  ContactListOptions,
+  ContactNoteOptions,
+  ContactNotesListOptions,
+  ContactSearchOptions,
+  ContactTagOptions,
+  ContactUpdateOptions,
+} from "./contacts.ts";
+// Contact commands
+export {
+  cmdContactAttachCompany,
+  cmdContactCreate,
+  cmdContactDelete,
+  cmdContactGet,
+  cmdContactList,
+  cmdContactNote,
+  cmdContactNotes,
+  cmdContactSearch,
+  cmdContactTag,
+  cmdContactUntag,
+  cmdContactUpdate,
+} from "./contacts.ts";
+export type {
+  ConversationAssignOptions,
+  ConversationCloseOptions,
+  ConversationGetOptions,
+  ConversationListOptions,
+  ConversationOpenOptions,
+  ConversationReplyOptions,
+  ConversationSearchOptions,
+  ConversationSnoozeOptions,
+} from "./conversations.ts";
+// Conversation commands
+export {
+  cmdConversationAssign,
+  cmdConversationClose,
+  cmdConversationGet,
+  cmdConversationList,
+  cmdConversationOpen,
+  cmdConversationReply,
+  cmdConversationSearch,
+  cmdConversationSnooze,
+} from "./conversations.ts";
+export type { EventListOptions, EventTrackOptions } from "./events.ts";
+// Event commands
+export { cmdEventList, cmdEventTrack } from "./events.ts";
+// Overview commands
+export { cmdContext, cmdSchema } from "./overview.ts";
+export type { TagCreateOptions, TagDeleteOptions, TagGetOptions } from "./tags.ts";
+// Tag commands
+export { cmdTagCreate, cmdTagDelete, cmdTagGet, cmdTagList } from "./tags.ts";

package/src/commands/overview.ts

@@ -0,0 +1,128 @@
+import ora from "ora";
+import { createClient, handleIntercomError } from "../client.ts";
+import { CLIError, type GlobalOptions, getTokenAsync, output } from "../utils/index.ts";
+
+export async function cmdContext(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 context...").start();
+
+  try {
+    const client = createClient({ token, dryRun: options.dryRun });
+
+    const [admin, admins] = await Promise.all([client.admins.identify(), client.admins.list()]);
+
+    if (!admin) {
+      throw new CLIError("Could not identify admin", 401, "The token may be invalid or expired.");
+    }
+
+    spinner.stop();
+
+    output(
+      {
+        current_admin: {
+          id: admin.id,
+          name: admin.name,
+          email: admin.email,
+        },
+        workspace: admin.app
+          ? {
+              id: admin.app.id_code,
+              name: admin.app.name,
+              region: admin.app.region,
+              timezone: admin.app.timezone,
+            }
+          : undefined,
+        team: {
+          total_admins: admins.admins?.length ?? 0,
+          admins: admins.admins?.map((a) => ({
+            id: a?.id,
+            name: a?.name,
+            email: a?.email,
+          })),
+        },
+      },
+      options.format,
+    );
+  } catch (error) {
+    spinner.fail("Failed to fetch context");
+    handleIntercomError(error);
+  }
+}
+
+export function cmdSchema(): void {
+  const schema = {
+    api_version: "2.11",
+    sdk: "intercom-client@7.0.1",
+    resources: {
+      admins: {
+        methods: ["identify", "list", "find", "away", "listAllActivityLogs"],
+        description: "Manage workspace admins and their away status",
+      },
+      contacts: {
+        methods: ["create", "find", "update", "delete", "search", "list"],
+        subresources: {
+          notes: ["create", "list"],
+          tags: ["create", "list", "delete"],
+          companies: ["create", "list", "delete"],
+        },
+        description: "Manage customer contacts (users and leads)",
+      },
+      conversations: {
+        methods: ["create", "find", "update", "list", "search", "redact", "convert"],
+        subresources: {
+          parts: ["create"],
+        },
+        description: "Manage customer conversations and replies",
+      },
+      companies: {
+        methods: ["create", "update", "find", "list", "delete", "scroll"],
+        subresources: {
+          contacts: ["list"],
+        },
+        description: "Manage companies and their contacts",
+      },
+      tags: {
+        methods: ["list", "create", "find", "delete"],
+        description: "Manage tags for contacts and conversations",
+      },
+      articles: {
+        methods: ["list", "create", "find", "update", "delete", "search"],
+        description: "Manage help center articles",
+      },
+      events: {
+        methods: ["create", "list"],
+        description: "Track and list custom user events",
+      },
+      helpCenters: {
+        methods: ["find", "list"],
+        description: "Manage help centers",
+      },
+      collections: {
+        methods: ["create", "find", "update", "delete", "list"],
+        description: "Manage article collections",
+      },
+      teams: {
+        methods: ["list", "find"],
+        description: "Manage teams",
+      },
+      segments: {
+        methods: ["list", "find"],
+        description: "Manage user segments",
+      },
+    },
+    usage_examples: {
+      create_contact: 'intercom contact create --email "user@example.com" --name "John Doe"',
+      search_contacts: 'intercom contact search --email "user@example.com"',
+      list_conversations: "intercom conversation list --limit 10",
+      reply_conversation: 'intercom conversation reply <id> --admin <admin-id> --body "Thank you!"',
+      create_tag: 'intercom tag create "VIP Customer"',
+      search_articles: 'intercom article search "getting started"',
+    },
+  };
+
+  console.log(JSON.stringify(schema, null, 2));
+}