huntr-cli 1.0.9

package/src/config/token-manager.ts

@@ -0,0 +1,139 @@
+import { password } from '@inquirer/prompts';
+import { ConfigManager } from './config-manager';
+import { KeychainManager } from './keychain-manager';
+import { ClerkSessionManager } from './clerk-session-manager';
+import type { TokenProvider } from '../api/client';
+
+export interface TokenOptions {
+  token?: string;
+  usePrompt?: boolean;
+}
+
+export class TokenManager {
+  private configManager: ConfigManager;
+  private keychainManager: KeychainManager;
+  readonly clerkSession: ClerkSessionManager;
+
+  constructor() {
+    this.configManager = new ConfigManager();
+    this.keychainManager = new KeychainManager();
+    this.clerkSession = new ClerkSessionManager();
+  }
+
+  /**
+   * Returns a TokenProvider for use with HuntrPersonalApi.
+   *
+   * Resolution order:
+   *   1. CLI --token argument (static, passed via options)
+   *   2. HUNTR_API_TOKEN env var (static)
+   *   3. Stored Clerk session cookie → auto-refresh on every call
+   *   4. Static token from config file or keychain
+   *   5. Interactive prompt
+   */
+  async getTokenProvider(options: TokenOptions = {}): Promise<TokenProvider> {
+    // 1. CLI argument — static token
+    if (options.token) {
+      return options.token;
+    }
+
+    // 2. Environment variable — static token
+    const envToken = process.env.HUNTR_API_TOKEN;
+    if (envToken) {
+      return envToken;
+    }
+
+    // 3. Clerk session — dynamic refresh
+    if (await this.clerkSession.hasSession()) {
+      return () => this.clerkSession.getFreshToken();
+    }
+
+    // 4. Static token from config or keychain
+    const configToken = this.configManager.getToken();
+    if (configToken) return configToken;
+
+    const keychainToken = await this.keychainManager.getToken();
+    if (keychainToken) return keychainToken;
+
+    // 5. Interactive prompt — static token (short-lived, but usable)
+    if (options.usePrompt !== false) {
+      const promptedToken = await password({
+        message: 'Enter your Huntr API token:',
+        mask: '*',
+      });
+
+      if (promptedToken) {
+        const saveChoice = await this.promptSaveLocation();
+        if (saveChoice !== 'none') {
+          await this.saveToken(promptedToken, saveChoice);
+        }
+        return promptedToken;
+      }
+    }
+
+    throw new Error(
+      'No Huntr credentials found. Options:\n' +
+      '  • Clerk session (recommended): huntr config set-session <__session-cookie>\n' +
+      '  • Static token:                huntr config set-token <token> [--keychain]\n' +
+      '  • CLI flag:                    huntr --token <token> <command>\n' +
+      '  • Environment:                 HUNTR_API_TOKEN=<token> huntr <command>',
+    );
+  }
+
+  /**
+   * Legacy helper — returns a resolved static token string.
+   * Use getTokenProvider() for new code so session refresh works.
+   */
+  async getToken(options: TokenOptions = {}): Promise<string> {
+    if (options.token) return options.token;
+    const envToken = process.env.HUNTR_API_TOKEN;
+    if (envToken) return envToken;
+    const configToken = this.configManager.getToken();
+    if (configToken) return configToken;
+    const keychainToken = await this.keychainManager.getToken();
+    if (keychainToken) return keychainToken;
+    throw new Error('No static token found. Try huntr config set-token or set-session.');
+  }
+
+  private async promptSaveLocation(): Promise<'config' | 'keychain' | 'none'> {
+    const { select } = await import('@inquirer/prompts');
+    return await select({
+      message: 'Where would you like to save this token?',
+      choices: [
+        { name: 'Save to config file (~/.huntr/config.json)', value: 'config' as const },
+        { name: 'Save to macOS Keychain (secure)', value: 'keychain' as const },
+        { name: 'Do not save (enter each time)', value: 'none' as const },
+      ],
+    }) as 'config' | 'keychain' | 'none';
+  }
+
+  async saveToken(token: string, location: 'config' | 'keychain'): Promise<void> {
+    if (location === 'config') {
+      this.configManager.setToken(token);
+    } else {
+      await this.keychainManager.setToken(token);
+    }
+  }
+
+  async clearToken(location?: 'config' | 'keychain' | 'all'): Promise<void> {
+    if (!location || location === 'all' || location === 'config') {
+      this.configManager.clearToken();
+    }
+    if (!location || location === 'all' || location === 'keychain') {
+      await this.keychainManager.deleteToken();
+    }
+  }
+
+  async showTokenSources(): Promise<{
+    env: boolean;
+    config: boolean;
+    keychain: boolean;
+    clerkSession: boolean;
+  }> {
+    return {
+      env: !!process.env.HUNTR_API_TOKEN,
+      config: !!this.configManager.getToken(),
+      keychain: !!(await this.keychainManager.getToken()),
+      clerkSession: await this.clerkSession.hasSession(),
+    };
+  }
+}

package/src/lib/list-options.ts

@@ -0,0 +1,370 @@
+/**
+ * Shared CLI options for list commands (boards, jobs, activities).
+ * Provides consistent flag parsing and validation across all list subcommands.
+ */
+
+export type OutputFormat = 'table' | 'json' | 'csv' | 'pdf' | 'excel';
+
+export interface ListOptions {
+  /** Output format: table (default), json, csv, pdf, or excel */
+  format: OutputFormat;
+  /** Number of days to filter to (activities only, default: all) */
+  days?: number;
+  /** Action types to filter (activities only, comma-separated) */
+  types?: string[];
+  /** Selected fields to include in output (comma-separated) */
+  fields?: string[];
+}
+
+/**
+ * Parses common list options from CLI arguments.
+ * Supports aliases: -f/--format, -d/--days, --json (legacy compatibility), --fields.
+ */
+export function parseListOptions(opts: Record<string, unknown>): ListOptions {
+  let format: OutputFormat = 'table';
+
+  // Handle legacy --json flag
+  if (opts.json) {
+    format = 'json';
+  }
+  // Handle new --format flag (takes precedence over --json)
+  if (opts.format) {
+    const fmt = String(opts.format).toLowerCase();
+    if (!['table', 'json', 'csv', 'pdf', 'excel'].includes(fmt)) {
+      throw new Error(`Invalid format: ${fmt}. Must be table, json, csv, pdf, or excel.`);
+    }
+    format = fmt as OutputFormat;
+  }
+
+  let days: number | undefined;
+  if (opts.days) {
+    const d = parseInt(String(opts.days), 10);
+    if (isNaN(d) || d < 1 || d > 365) {
+      throw new Error('Days must be a number between 1 and 365');
+    }
+    days = d;
+  }
+
+  // Legacy --week flag for activities (maps to 7 days)
+  if (opts.week && !days) {
+    days = 7;
+  }
+
+  let types: string[] | undefined;
+  if (opts.types) {
+    types = String(opts.types)
+      .split(',')
+      .map(t => t.trim())
+      .filter(t => t.length > 0);
+  }
+
+  let fields: string[] | undefined;
+  if (opts.fields) {
+    fields = String(opts.fields)
+      .split(',')
+      .map(f => f.trim())
+      .filter(f => f.length > 0);
+  }
+
+  return { format, days, types, fields };
+}
+
+/**
+ * Formats table output with consistent column widths.
+ */
+export function formatTable<T extends Record<string, unknown>>(rows: T[]): string {
+  if (rows.length === 0) return '';
+
+  const keys = Object.keys(rows[0]);
+  const colWidths: Record<string, number> = {};
+
+  // Calculate column widths
+  for (const key of keys) {
+    colWidths[key] = key.length;
+    for (const row of rows) {
+      const val = String(row[key] ?? '');
+      colWidths[key] = Math.max(colWidths[key], val.length);
+    }
+  }
+
+  // Format header
+  const header = keys.map(k => k.padEnd(colWidths[k])).join('  ');
+  const divider = keys.map(k => '─'.repeat(colWidths[k])).join('  ');
+
+  // Format rows
+  const lines = [header, divider];
+  for (const row of rows) {
+    const line = keys.map(k => String(row[k] ?? '').padEnd(colWidths[k])).join('  ');
+    lines.push(line);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Converts array of objects to CSV with proper escaping.
+ */
+export function formatCsv<T extends Record<string, unknown>>(rows: T[], headers?: string[]): string {
+  if (rows.length === 0) return headers ? headers.join(',') : '';
+
+  const keys = headers || Object.keys(rows[0]);
+  const lines = [keys.map(escapeCsvField).join(',')];
+
+  for (const row of rows) {
+    const values = keys.map(k => {
+      const val = row[k];
+      return escapeCsvField(String(val ?? ''));
+    });
+    lines.push(values.join(','));
+  }
+
+  return lines.join('\n');
+}
+
+function escapeCsvField(field: string): string {
+  if (field.includes(',') || field.includes('"') || field.includes('\n')) {
+    return `"${field.replace(/"/g, '""')}"`;
+  }
+  return field;
+}
+
+/**
+ * Validates and filters fields based on available fields.
+ * If no fields are requested, returns all available fields.
+ * Throws an error if requested fields don't exist.
+ */
+export function validateFields(availableFields: string[], requestedFields?: string[]): string[] {
+  if (!requestedFields || requestedFields.length === 0) {
+    return availableFields;
+  }
+
+  const invalid = requestedFields.filter(f => !availableFields.includes(f));
+  if (invalid.length > 0) {
+    const invalidStr = invalid.join(', ');
+    const availableStr = availableFields.join(', ');
+    throw new Error(
+      `Unknown field(s): ${invalidStr}\nAvailable fields: ${availableStr}`,
+    );
+  }
+
+  return requestedFields;
+}
+
+/**
+ * Formats table output with specific fields and consistent column widths.
+ * @param rows Data rows
+ * @param headers Field names to include (in order)
+ */
+export function formatTableWithFields<T extends Record<string, unknown>>(
+  rows: T[],
+  headers: string[],
+): string {
+  if (rows.length === 0) return '';
+
+  const colWidths: Record<string, number> = {};
+
+  // Calculate column widths
+  for (const key of headers) {
+    colWidths[key] = key.length;
+    for (const row of rows) {
+      const val = String(row[key] ?? '');
+      colWidths[key] = Math.max(colWidths[key], val.length);
+    }
+  }
+
+  // Format header
+  const header = headers.map(k => k.padEnd(colWidths[k])).join('  ');
+  const divider = headers.map(k => '─'.repeat(colWidths[k])).join('  ');
+
+  // Format rows
+  const lines = [header, divider];
+  for (const row of rows) {
+    const line = headers.map(k => String(row[k] ?? '').padEnd(colWidths[k])).join('  ');
+    lines.push(line);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Formats CSV output with specific fields.
+ * @param rows Data rows
+ * @param headers Field names to include (in order)
+ */
+export function formatCsvWithFields<T extends Record<string, unknown>>(
+  rows: T[],
+  headers: string[],
+): string {
+  if (rows.length === 0) return headers.join(',');
+
+  const lines = [headers.map(escapeCsvField).join(',')];
+
+  for (const row of rows) {
+    const values = headers.map(h => {
+      const val = row[h];
+      return escapeCsvField(String(val ?? ''));
+    });
+    lines.push(values.join(','));
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Formats JSON output with specific fields.
+ * @param rows Data rows
+ * @param headers Field names to include (in order)
+ */
+export function formatJsonWithFields<T extends Record<string, unknown>>(
+  rows: T[],
+  headers: string[],
+): string {
+  const filtered = rows.map(row => {
+    const obj: Record<string, unknown> = {};
+    for (const header of headers) {
+      obj[header] = row[header];
+    }
+    return obj;
+  });
+  return JSON.stringify(filtered, null, 2);
+}
+
+/**
+ * Formats PDF output with specific fields.
+ * Requires pdfkit to be installed.
+ * @param rows Data rows
+ * @param headers Field names to include (in order)
+ * @param title Optional title for the PDF
+ */
+export function formatPdf<T extends Record<string, unknown>>(
+  rows: T[],
+  headers: string[],
+  title?: string,
+): Buffer {
+  // Dynamically import pdfkit to avoid hard dependency at load time
+  // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
+  const PDFDocument = require('pdfkit');
+
+  const doc = new PDFDocument({ margin: 40, size: 'letter' });
+  const chunks: Buffer[] = [];
+
+  // Collect output
+  doc.on('data', (chunk: Buffer) => chunks.push(chunk));
+
+  // Title
+  if (title) {
+    doc.fontSize(16).font('Helvetica-Bold').text(title, { underline: true });
+    doc.moveDown();
+  }
+
+  // Metadata
+  const now = new Date();
+  doc
+    .fontSize(10)
+    .font('Helvetica')
+    .text(`Generated: ${now.toISOString()}`, { lineGap: 5 });
+  doc.moveDown();
+
+  // Table header
+  const colWidth = (doc.page.width - 80) / headers.length;
+  const yStart = doc.y;
+
+  // Header background
+  doc.rect(40, yStart, doc.page.width - 80, 25).fill('#e8e8e8');
+
+  // Header text
+  doc.fontSize(10).font('Helvetica-Bold').fillColor('black');
+  headers.forEach((header, i) => {
+    doc.text(header, 40 + i * colWidth + 5, yStart + 5, {
+      width: colWidth - 10,
+      ellipsis: true,
+    });
+  });
+
+  doc.moveDown(1.5);
+
+  // Data rows
+  doc.font('Helvetica').fontSize(9);
+  const rowHeight = 20;
+
+  for (const row of rows) {
+    const yRow = doc.y;
+
+    // Alternate row background
+    if (rows.indexOf(row) % 2 === 0) {
+      doc.rect(40, yRow, doc.page.width - 80, rowHeight).fill('#f5f5f5');
+      doc.fillColor('black');
+    }
+
+    headers.forEach((header, i) => {
+      const val = String(row[header] ?? '');
+      doc.text(val, 40 + i * colWidth + 5, yRow + 3, {
+        width: colWidth - 10,
+        ellipsis: true,
+      });
+    });
+
+    doc.moveDown(1.2);
+  }
+
+  // Footer
+  doc.fontSize(9).font('Helvetica').text('huntr-cli', { align: 'center' });
+
+  doc.end();
+
+  return Buffer.concat(chunks);
+}
+
+/**
+ * Formats Excel output with specific fields.
+ * Requires exceljs to be installed.
+ * @param rows Data rows
+ * @param headers Field names to include (in order)
+ * @param title Optional sheet title
+ */
+export async function formatExcel<T extends Record<string, unknown>>(
+  rows: T[],
+  headers: string[],
+  title?: string,
+): Promise<Buffer> {
+  // Dynamically import exceljs to avoid hard dependency at load time
+  // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
+  const ExcelJS = require('exceljs');
+
+  const workbook = new ExcelJS.Workbook();
+  const worksheet = workbook.addWorksheet(title || 'Data', {
+    pageSetup: { paperSize: 9, orientation: 'landscape' },
+  });
+
+  // Add header row
+  worksheet.addRow(headers);
+  const headerRow = worksheet.getRow(1);
+  headerRow.font = { bold: true, color: { argb: 'FFFFFFFF' } };
+  headerRow.fill = {
+    type: 'pattern',
+    pattern: 'solid',
+    fgColor: { argb: 'FF4472C4' },
+  };
+  headerRow.alignment = { horizontal: 'center', vertical: 'center' };
+
+  // Add data rows
+  for (const row of rows) {
+    const values = headers.map(h => row[h] ?? '');
+    worksheet.addRow(values);
+  }
+
+  // Auto-adjust column widths
+  headers.forEach((header, i) => {
+    let maxLen = header.length;
+    for (const row of rows) {
+      const val = String(row[header] ?? '');
+      maxLen = Math.max(maxLen, val.length);
+    }
+    const col = worksheet.getColumn(i + 1);
+    col.width = Math.min(maxLen + 2, 50); // Cap at 50 chars
+  });
+
+  // Generate buffer
+  const buffer = await workbook.xlsx.writeBuffer();
+  return buffer as Buffer;
+}

package/src/types/personal.ts

@@ -0,0 +1,114 @@
+// Personal API types (for /api endpoints with Clerk auth)
+
+export interface Board {
+  id: string;
+  _id: string;
+  name?: string;
+  createdAt: string;
+  updatedAt?: string;
+  lists?: BoardList[];
+}
+
+export interface BoardList {
+  id: string;
+  _id: string;
+  name: string;
+  order?: number;
+}
+
+// Company as returned inside job action data
+export interface JobCompany {
+  _id: string;
+  id: string;
+  name: string;
+  color?: string;
+}
+
+// Job as returned by /api/board/{boardId}/jobs — keyed object map
+export interface PersonalJob {
+  _id: string;
+  id: string;
+  title: string;
+  url?: string;
+  rootDomain?: string;
+  htmlDescription?: string;
+  _company: string; // company ID ref
+  _list?: string;
+  _board: string;
+  _activities?: string[];
+  _notes?: string[];
+  salary?: {
+    min?: number;
+    max?: number;
+    currency?: string;
+  };
+  location?: {
+    address?: string;
+    name?: string;
+    url?: string;
+    lat?: string;
+    lng?: string;
+  };
+  createdAt: string;
+  updatedAt?: string;
+  lastMovedAt?: string;
+}
+
+// Jobs response is an object map { [jobId]: PersonalJob }
+export interface PersonalJobsResponse {
+  jobs: Record<string, PersonalJob>;
+}
+
+// Action as returned by /api/board/{boardId}/actions — keyed object map
+export interface PersonalAction {
+  _id: string;
+  id: string;
+  actionType: string;
+  date: string;
+  createdAt: string;
+  updatedAt?: string;
+  data: {
+    _job?: string;
+    _company?: string;
+    _board?: string;
+    _fromList?: string;
+    _toList?: string;
+    note?: ActionNote | null;
+    job?: { _id: string; id: string; title: string };
+    company?: JobCompany;
+    fromList?: { _id: string; id: string; name: string } | null;
+    toList?: { _id: string; id: string; name: string } | null;
+    activity?: unknown;
+    activityCategory?: unknown;
+    contact?: unknown;
+  };
+}
+
+export interface ActionNote {
+  _id: string;
+  id: string;
+  text: string;
+}
+
+export interface PersonalActivity {
+  id: string;
+  _id: string;
+  title?: string;
+  note?: string;
+  completed: boolean;
+  completedAt?: string;
+  createdAt: string;
+  jobId?: string;
+  boardId?: string;
+}
+
+export interface UserProfile {
+  id: string;
+  _id?: string;
+  email: string;
+  givenName?: string;
+  familyName?: string;
+  firstName?: string;
+  lastName?: string;
+  createdAt: string;
+}