bamboohr-cli 1.0.17 → 2.0.0-gc22cadf.3

package/dist/index.js

@@ -1,12 +1,5 @@
 #!/usr/bin/env node
 
-// src/index.ts
-import { readFileSync as readFileSync2 } from "fs";
-import { dirname, join as join2 } from "path";
-import { fileURLToPath } from "url";
-import { styleText } from "util";
-import { Command as Command6 } from "commander";
-
 // ../../cli-utils/dist/cache.js
 import { readFileSync, writeFileSync, mkdirSync, statSync } from "fs";
 import { homedir } from "os";
@@ -51,6 +44,224 @@ async function cacheGetOrFetch(options, key, fetcher) {
   return data;
 }
 
+// ../../cli-utils/dist/bootstrap.js
+import { readFileSync as readFileSync2 } from "fs";
+import { dirname, join as join2 } from "path";
+import { fileURLToPath } from "url";
+function readPackageVersion(importMetaUrl) {
+  try {
+    const here = dirname(fileURLToPath(importMetaUrl));
+    const pkg = JSON.parse(readFileSync2(join2(here, "..", "package.json"), "utf-8"));
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+// ../../cli-utils/dist/validators.js
+import { InvalidArgumentError } from "commander";
+function positiveInt(raw) {
+  const n = parseInt(raw, 10);
+  if (Number.isNaN(n) || n < 1) {
+    throw new InvalidArgumentError(`Must be a positive integer (got "${raw}")`);
+  }
+  return n;
+}
+
+// ../../cli-utils/dist/errors.js
+import { CommanderError } from "commander";
+var EXIT = {
+  SUCCESS: 0,
+  GENERIC: 1,
+  USAGE: 2,
+  NOT_FOUND: 3,
+  FORBIDDEN: 4,
+  CONFLICT: 5,
+  AUTH: 6
+};
+var TYPE_EXIT = {
+  usage: EXIT.USAGE,
+  not_found: EXIT.NOT_FOUND,
+  forbidden: EXIT.FORBIDDEN,
+  conflict: EXIT.CONFLICT,
+  auth: EXIT.AUTH,
+  rate_limited: EXIT.GENERIC,
+  server: EXIT.GENERIC,
+  network: EXIT.GENERIC,
+  unknown: EXIT.GENERIC
+};
+var NETWORK_CODES = ["ENOTFOUND", "ECONNREFUSED", "ECONNRESET", "ETIMEDOUT"];
+function httpStatus(err) {
+  const e = err;
+  return e?.response?.status ?? e?.statusCode;
+}
+function responseDetail(err) {
+  const e = err;
+  const data = e?.response?.data;
+  if (data && typeof data === "object")
+    return data;
+  const body = e?.body;
+  if (typeof body === "string") {
+    try {
+      const parsed = JSON.parse(body);
+      return parsed.error ?? parsed;
+    } catch {
+      return void 0;
+    }
+  }
+  if (body && typeof body === "object") {
+    return body.error ?? body;
+  }
+  return void 0;
+}
+function errorCode(err) {
+  return err?.code;
+}
+function normalize(err, opts) {
+  const message = err instanceof Error ? err.message : String(err);
+  if (err instanceof CommanderError) {
+    return {
+      type: "usage",
+      message: message || "Invalid command usage",
+      recovery: "Check the command syntax and flags; run the command with --help.",
+      retryable: false
+    };
+  }
+  const status = httpStatus(err);
+  const detail = responseDetail(err);
+  if (status !== void 0) {
+    switch (status) {
+      case 400:
+        return {
+          type: "usage",
+          status,
+          message: "Bad request (HTTP 400)",
+          recovery: "Check parameter values (ids, keys, query syntax) against the API.",
+          retryable: false,
+          detail
+        };
+      case 401:
+        return {
+          type: "auth",
+          status,
+          message: "Authentication failed (HTTP 401)",
+          recovery: opts.authRecovery,
+          retryable: false
+        };
+      case 403:
+        return {
+          type: "forbidden",
+          status,
+          message: "Forbidden (HTTP 403)",
+          recovery: `Your ${opts.service} account lacks permission for this operation; check token scope and resource permissions.`,
+          retryable: false,
+          detail
+        };
+      case 404:
+        return {
+          type: "not_found",
+          status,
+          message: "Not found (HTTP 404)",
+          recovery: "Verify the id/key exists and that you have access to it.",
+          retryable: false,
+          detail
+        };
+      case 409:
+        return {
+          type: "conflict",
+          status,
+          message: "Conflict (HTTP 409)",
+          recovery: "The resource changed or already exists; re-fetch current state and retry.",
+          retryable: false,
+          detail
+        };
+      case 429:
+        return {
+          type: "rate_limited",
+          status,
+          message: "Rate limited (HTTP 429)",
+          recovery: "Wait and retry the request.",
+          retryable: true
+        };
+    }
+    if (status >= 500) {
+      return {
+        type: "server",
+        status,
+        message: `Server error (HTTP ${status})`,
+        recovery: `${opts.service} returned an internal error; retry shortly.`,
+        retryable: true,
+        detail
+      };
+    }
+    return {
+      type: "unknown",
+      status,
+      message: `${opts.service} error (HTTP ${status}): ${message}`,
+      recovery: "Inspect the detail field for the API response.",
+      retryable: false,
+      detail
+    };
+  }
+  const code = errorCode(err);
+  if (code && NETWORK_CODES.includes(code) || NETWORK_CODES.some((c) => message.includes(c))) {
+    return {
+      type: "network",
+      message: `Cannot connect to ${opts.service}: ${message}`,
+      recovery: opts.networkRecovery ?? "Verify the *_URL is correct, the server is reachable, and you are on the VPN if required.",
+      retryable: true
+    };
+  }
+  return { type: "unknown", message, recovery: "Unexpected error; inspect the message.", retryable: false };
+}
+function classifyError(err, opts) {
+  const base = normalize(err, opts);
+  const n = opts.adapt ? opts.adapt(base, err) : base;
+  return {
+    envelope: {
+      error: {
+        type: n.type,
+        message: n.message,
+        recovery: n.recovery,
+        retryable: n.retryable,
+        ...n.detail !== void 0 ? { detail: n.detail } : {}
+      }
+    },
+    exitCode: TYPE_EXIT[n.type]
+  };
+}
+function createErrorHandler(opts) {
+  return (err) => {
+    const { envelope, exitCode } = classifyError(err, opts);
+    process.stderr.write(`${JSON.stringify(envelope)}
+`);
+    return process.exit(exitCode);
+  };
+}
+function isCleanCommanderExit(err) {
+  return err instanceof CommanderError && (err.exitCode === 0 || err.code === "commander.helpDisplayed" || err.code === "commander.help" || err.code === "commander.version");
+}
+function routeErrors(cmd) {
+  cmd.exitOverride();
+  cmd.configureOutput({ writeErr: () => void 0 });
+  cmd.commands.forEach(routeErrors);
+}
+async function runCli(program, opts) {
+  routeErrors(program);
+  try {
+    await program.parseAsync();
+  } catch (err) {
+    if (isCleanCommanderExit(err)) {
+      process.exit(err.exitCode ?? 0);
+    }
+    createErrorHandler(opts)(err);
+  }
+}
+
+// src/program.ts
+import { styleText } from "util";
+import { Command as Command6 } from "commander";
+
 // src/utils/cached.ts
 var CACHE_NAME = "bamboohr";
 var TWELVE_HOURS = 432e5;
@@ -115,68 +326,6 @@ function output(data) {
   process.stdout.write(`${JSON.stringify(data, null, prettyPrint ? 2 : void 0)}
 `);
 }
-function handleError(err) {
-  const message = err instanceof Error ? err.message : String(err);
-  const axiosStatus = err?.response?.status;
-  if (axiosStatus === 400) {
-    const responseData = err?.response?.data;
-    const apiErrors = responseData && typeof responseData === "object" ? responseData : void 0;
-    process.stderr.write(
-      `${JSON.stringify({
-        error: "Bad request (HTTP 400)",
-        detail: apiErrors ?? message,
-        hint: "Check that all parameters are valid (employee IDs, field names, date formats, etc.)."
-      })}
-`
-    );
-  } else if (axiosStatus === 401) {
-    process.stderr.write(
-      `${JSON.stringify({
-        error: "Authentication failed (HTTP 401)",
-        ...getCredentialInfo()
-      })}
-`
-    );
-  } else if (axiosStatus === 403) {
-    const responseData = err?.response?.data;
-    process.stderr.write(
-      `${JSON.stringify({
-        error: "Forbidden (HTTP 403)",
-        detail: responseData && typeof responseData === "object" ? responseData : message,
-        hint: "Your account does not have permission for this operation. Check your BambooHR access level."
-      })}
-`
-    );
-  } else if (axiosStatus === 404) {
-    process.stderr.write(
-      `${JSON.stringify({
-        error: "Not found (HTTP 404)",
-        hint: "Resource not found. Note: BambooHR also returns 404 for invalid credentials \u2014 verify that BAMBOO_TOKEN and BAMBOO_COMPANY_DOMAIN are correct."
-      })}
-`
-    );
-  } else if (message.includes("ENOTFOUND") || message.includes("ECONNREFUSED") || message.includes("ECONNRESET")) {
-    process.stderr.write(
-      `${JSON.stringify({
-        error: `Cannot connect to BambooHR API: ${message}`,
-        hint: "Verify that BAMBOO_COMPANY_DOMAIN is correct and you have internet connectivity."
-      })}
-`
-    );
-  } else {
-    const responseData = err?.response?.data;
-    const detail = responseData && typeof responseData === "object" ? responseData : void 0;
-    process.stderr.write(
-      `${JSON.stringify({
-        error: message,
-        ...axiosStatus !== void 0 && { statusCode: axiosStatus },
-        ...detail && { detail }
-      })}
-`
-    );
-  }
-  process.exit(1);
-}
 
 // src/utils/transformers/base.ts
 function bamboohrBaseUrl() {
@@ -311,7 +460,7 @@ Examples:
 
 // src/commands/employee/get.ts
 function get(parent) {
-  parent.command("get [id]").description("Get employee data by ID (default: current user)").option("--fields <fields>", "Comma-separated field names", "firstName,lastName,email,jobTitle").option("--include-future", "Include future-dated values from history fields").option("--with-photos", "Include the employee's signed photo URL and photoUploaded flag").addHelpText(
+  parent.command("get [employeeId]").description("Get employee data by ID (default: current user)").option("--fields <fields>", "Comma-separated field names", "firstName,lastName,email,jobTitle").option("--include-future", "Include future-dated values from history fields").option("--with-photos", "Include the employee's signed photo URL and photoUploaded flag").addHelpText(
     "after",
     `
 Examples:
@@ -320,16 +469,18 @@ Examples:
   $ bamboohr employee get 123 --fields "firstName,lastName,department,hireDate"
   $ bamboohr employee get 123 --include-future
   $ bamboohr employee get 123 --with-photos`
-  ).action(async (id, opts) => {
-    const client = getClient();
-    const fields2 = opts.withPhotos ? mergeFields(opts.fields, ["photoUrl", "photoUploaded"]) : opts.fields;
-    const result = await client.employees.get({
-      id: id ?? "0",
-      fields: fields2,
-      onlyCurrent: !opts.includeFuture
-    });
-    output(transformEmployee(result, { withPhotos: opts.withPhotos }));
-  });
+  ).action(
+    async (employeeId, opts) => {
+      const client = getClient();
+      const fields2 = opts.withPhotos ? mergeFields(opts.fields, ["photoUrl", "photoUploaded"]) : opts.fields;
+      const result = await client.employees.get({
+        id: employeeId ?? "0",
+        fields: fields2,
+        onlyCurrent: !opts.includeFuture
+      });
+      output(transformEmployee(result, { withPhotos: opts.withPhotos }));
+    }
+  );
 }
 function mergeFields(existing, extra) {
   const set = new Set(
@@ -343,16 +494,16 @@ function mergeFields(existing, extra) {
 import { Option } from "commander";
 var GOAL_FILTERS = ["open", "closed", "all"];
 function goals(parent) {
-  parent.command("goals <id>").description("Get employee performance goals").addOption(new Option("--filter <filter>", "Filter goals by status").choices(GOAL_FILTERS).default("all")).addHelpText(
+  parent.command("goals <employeeId>").description("Get employee performance goals").addOption(new Option("--filter <filter>", "Filter goals by status").choices(GOAL_FILTERS).default("all")).addHelpText(
     "after",
     `
 Examples:
   $ bamboohr employee goals 123
   $ bamboohr employee goals 123 --filter open`
-  ).action(async (id, opts) => {
+  ).action(async (employeeId, opts) => {
     const client = getClient();
     const result = await client.goals.get({
-      employeeId: id,
+      employeeId,
       filter: opts.filter === "all" ? void 0 : opts.filter
     });
     output(transformGoals(result));
@@ -364,16 +515,16 @@ import { writeFileSync as writeFileSync2 } from "fs";
 import { Option as Option2 } from "commander";
 var PHOTO_SIZES = ["original", "large", "medium", "small", "xs", "tiny"];
 function photo(parent) {
-  parent.command("photo <id>").description("Download employee photo").requiredOption("--output <path>", "File path to save photo").addOption(new Option2("--size <size>", "Photo size").choices(PHOTO_SIZES).default("medium")).addHelpText(
+  parent.command("photo <employeeId>").description("Download employee photo").requiredOption("--output <path>", "File path to save photo").addOption(new Option2("--size <size>", "Photo size").choices(PHOTO_SIZES).default("medium")).addHelpText(
     "after",
     `
 Examples:
   $ bamboohr employee photo 123 --output ./photo.jpg
   $ bamboohr employee photo 123 --output ./photo.jpg --size large`
-  ).action(async (id, opts) => {
+  ).action(async (employeeId, opts) => {
     const client = getClient();
     const buffer = await client.employees.getPhoto({
-      employeeId: id,
+      employeeId,
       size: opts.size
     });
     writeFileSync2(opts.output, buffer);
@@ -439,8 +590,8 @@ Examples:
 }
 
 // src/commands/employee/index.ts
-function registerEmployeeCommands(program2) {
-  const employee = program2.command("employee").description("Employee operations").addHelpText(
+function registerEmployeeCommands(program) {
+  const employee = program.command("employee").description("Employee operations").addHelpText(
     "after",
     `
 Examples:
@@ -484,8 +635,8 @@ function list(parent) {
 }
 
 // src/commands/file/index.ts
-function registerFileCommands(program2) {
-  const file = program2.command("file").description("Company file operations").addHelpText(
+function registerFileCommands(program) {
+  const file = program.command("file").description("Company file operations").addHelpText(
     "after",
     `
 Examples:
@@ -537,8 +688,8 @@ function locations(parent) {
 }
 
 // src/commands/meta/index.ts
-function registerMetaCommands(program2) {
-  const meta = program2.command("meta").description("Metadata operations").addHelpText(
+function registerMetaCommands(program) {
+  const meta = program.command("meta").description("Metadata operations").addHelpText(
     "after",
     `
 Examples:
@@ -573,18 +724,6 @@ Examples:
 
 // src/commands/timeoff/create.ts
 import { Option as Option3 } from "commander";
-
-// src/utils/cli.ts
-import { InvalidArgumentError } from "commander";
-function positiveInt(raw) {
-  const n = parseInt(raw, 10);
-  if (Number.isNaN(n) || n < 1) {
-    throw new InvalidArgumentError(`Must be a positive integer (got "${raw}")`);
-  }
-  return n;
-}
-
-// src/commands/timeoff/create.ts
 function create(parent) {
   parent.command("create [employeeId]").description("Create a time off request (defaults to current user)").requiredOption("--start-date <date>", "Start date (YYYY-MM-DD)").requiredOption("--end-date <date>", "End date (YYYY-MM-DD)").requiredOption("--type-id <id>", 'Time off type ID (use "timeoff types" to find IDs)', positiveInt).requiredOption("--amount <amount>", "Total amount of time off (in days or hours depending on type)", parseFloat).addOption(
     new Option3("--status <status>", "Request status").choices(["requested", "approved"]).default("requested")
@@ -618,7 +757,7 @@ Examples:
 // src/commands/timeoff/requests.ts
 import { Option as Option4 } from "commander";
 function requests(parent) {
-  parent.command("requests").description("Get time off requests (defaults to current user)").option("--id <id>", "Specific request ID", positiveInt).addOption(new Option4("--action <action>", "Access level filter").choices(["view", "approve"])).option("--employee <id>", "Filter by employee ID").option("--all", "Show all visible requests instead of just current user").option("--start-date <date>", "Start date (YYYY-MM-DD)").option("--end-date <date>", "End date (YYYY-MM-DD)").addOption(
+  parent.command("requests").description("Get time off requests (defaults to current user)").option("--request-id <id>", "Specific request ID", positiveInt).addOption(new Option4("--action <action>", "Access level filter").choices(["view", "approve"])).option("--employee-id <id>", "Filter by employee ID").option("--all", "Show all visible requests instead of just current user").option("--start-date <date>", "Start date (YYYY-MM-DD)").option("--end-date <date>", "End date (YYYY-MM-DD)").addOption(
     new Option4("--status <status>", "Filter by request status").choices([
       "approved",
       "denied",
@@ -626,32 +765,32 @@ function requests(parent) {
       "requested",
       "canceled"
     ])
-  ).option("--type <typeId>", "Filter by time off type ID").addHelpText(
+  ).option("--type-id <typeId>", "Filter by time off type ID").addHelpText(
     "after",
     `
 Examples:
   $ bamboohr timeoff requests
   $ bamboohr timeoff requests --status requested
   $ bamboohr timeoff requests --all --action approve --status requested
-  $ bamboohr timeoff requests --employee 123 --start-date 2026-01-01 --end-date 2026-03-31`
+  $ bamboohr timeoff requests --employee-id 123 --start-date 2026-01-01 --end-date 2026-03-31`
   ).action(
     async (opts) => {
       const year = (/* @__PURE__ */ new Date()).getFullYear();
       const start = opts.startDate ?? `${year}-01-01`;
       const end = opts.endDate ?? `${year}-12-31`;
       const client = getClient();
-      let employeeId = opts.employee;
+      let employeeId = opts.employeeId;
       if (!employeeId && !opts.all) {
         employeeId = await resolveEmployeeId(client);
       }
       const result = await client.timeOff.getRequests({
-        id: opts.id,
+        id: opts.requestId,
         action: opts.action,
         employeeId,
         start,
         end,
         status: opts.status,
-        type: opts.type
+        type: opts.typeId
       });
       output(transformTimeOffRequests(result));
     }
@@ -715,8 +854,8 @@ Examples:
 }
 
 // src/commands/timeoff/index.ts
-function registerTimeoffCommands(program2) {
-  const timeoff = program2.command("timeoff").description("Time off operations").addHelpText(
+function registerTimeoffCommands(program) {
+  const timeoff = program.command("timeoff").description("Time off operations").addHelpText(
     "after",
     `
 Examples:
@@ -736,31 +875,22 @@ Examples:
   updateStatus(timeoff);
 }
 
-// src/index.ts
-function readPackageVersion() {
-  try {
-    const here = dirname(fileURLToPath(import.meta.url));
-    const pkgPath = join2(here, "..", "package.json");
-    const pkg = JSON.parse(readFileSync2(pkgPath, "utf-8"));
-    return pkg.version ?? "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-}
+// src/program.ts
 var DIM = "\x1B[2m";
 var RESET = "\x1B[0m";
-var program = new Command6();
-program.name("bamboohr").description("BambooHR CLI").version(readPackageVersion()).configureHelp({
-  styleTitle: (str) => styleText("bold", str),
-  styleUsage: (str) => styleText("dim", str),
-  styleCommandDescription: (str) => styleText("dim", str),
-  styleOptionDescription: (str) => styleText("dim", str),
-  styleSubcommandDescription: (str) => styleText("dim", str)
-}).addHelpText("beforeAll", `
+function buildProgram() {
+  const program = new Command6();
+  program.name("bamboohr").description("BambooHR CLI").version(readPackageVersion(import.meta.url)).configureHelp({
+    styleTitle: (str) => styleText("bold", str),
+    styleUsage: (str) => styleText("dim", str),
+    styleCommandDescription: (str) => styleText("dim", str),
+    styleOptionDescription: (str) => styleText("dim", str),
+    styleSubcommandDescription: (str) => styleText("dim", str)
+  }).addHelpText("beforeAll", `
 ${styleText("bold", "bamboohr")} ${DIM}\u2014 BambooHR CLI${RESET}
 `).addHelpText(
-  "after",
-  `
+    "after",
+    `
 ${styleText("bold", "Environment:")}
   BAMBOO_TOKEN            BambooHR API token ${DIM}(generate in BambooHR > Settings > API Keys)${RESET}
   BAMBOO_COMPANY_DOMAIN   Company subdomain ${DIM}(e.g., "mycompany" for mycompany.bamboohr.com)${RESET}
@@ -772,24 +902,34 @@ ${styleText("bold", "Examples:")}
   ${DIM}$${RESET} bamboohr employee photo 123 --output ./photo.jpg
   ${DIM}$${RESET} bamboohr timeoff types --requestable
   ${DIM}$${RESET} bamboohr timeoff create 504 --start-date 2026-04-01 --end-date 2026-04-01 --type-id 83 --amount 1
-  ${DIM}$${RESET} bamboohr timeoff create 504 --start-date 2026-04-01 --end-date 2026-04-01 --type-id 83 --amount 1 --note "Doctor appointment"
   ${DIM}$${RESET} bamboohr timeoff requests --status requested --start-date 2026-01-01 --end-date 2026-12-31
   ${DIM}$${RESET} bamboohr timeoff whos-out
   ${DIM}$${RESET} bamboohr timeoff update-status 7890 --status approved
   ${DIM}$${RESET} bamboohr file list
   ${DIM}$${RESET} bamboohr meta fields
 `
-);
-program.option("--pretty", "Pretty-print JSON output");
-program.hook("preAction", (thisCommand) => {
-  if (thisCommand.optsWithGlobals().pretty) setPretty(true);
-});
-registerEmployeeCommands(program);
-registerTimeoffCommands(program);
-registerFileCommands(program);
-registerMetaCommands(program);
-try {
-  await program.parseAsync();
-} catch (err) {
-  handleError(err);
+  );
+  program.option("--pretty", "Pretty-print JSON output");
+  program.hook("preAction", (thisCommand) => {
+    if (thisCommand.optsWithGlobals().pretty) setPretty(true);
+  });
+  registerEmployeeCommands(program);
+  registerTimeoffCommands(program);
+  registerFileCommands(program);
+  registerMetaCommands(program);
+  return program;
 }
+
+// src/index.ts
+await runCli(buildProgram(), {
+  service: "BambooHR",
+  authRecovery: "Set BAMBOO_TOKEN and BAMBOO_COMPANY_DOMAIN in your shell profile (~/.zshrc).",
+  networkRecovery: "Verify BAMBOO_COMPANY_DOMAIN is correct and you have internet connectivity.",
+  // BambooHR returns HTTP 404 for invalid credentials as well as genuinely
+  // missing resources — it cannot distinguish them, so keep not_found but
+  // document the ambiguity in the recovery hint (design §4.9).
+  adapt: (normalized) => normalized.status === 404 ? {
+    ...normalized,
+    recovery: "BambooHR returns 404 for invalid credentials too \u2014 verify BAMBOO_TOKEN and BAMBOO_COMPANY_DOMAIN, then confirm the resource id exists."
+  } : normalized
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bamboohr-cli",
-  "version": "1.0.17",
+  "version": "2.0.0-gc22cadf.3",
   "publish": true,
   "type": "module",
   "main": "dist/index.js",
@@ -23,8 +23,8 @@
     "typescript": "^5.7.2",
     "vitest": "^4.0.16",
     "cli-utils": "1.0.0",
-    "config-eslint": "0.0.0",
-    "config-typescript": "0.0.0"
+    "config-typescript": "0.0.0",
+    "config-eslint": "0.0.0"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -35,6 +35,6 @@
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
     "test": "vitest run",
-    "test:integration": "vitest run tests/integration"
+    "test:integration": "vitest run --config vitest.integration.config.ts"
   }
 }