bamboohr-cli 1.0.17 → 2.0.0-g40cd2b1.10

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,263 @@ 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/builders.js
+var EXAMPLES = /* @__PURE__ */ new WeakSet();
+function commandPath(cmd) {
+  const parts = [];
+  for (let c = cmd; c; c = c.parent)
+    parts.unshift(c.name());
+  return parts.join(" ");
+}
+function exampleLine(path, entry) {
+  if (typeof entry === "string")
+    return entry ? `  ${path} ${entry}` : `  ${path}`;
+  if ("raw" in entry)
+    return `  ${entry.raw}`;
+  const [args, comment] = entry;
+  const line = args ? `${path} ${args}` : path;
+  return `  ${line}  # ${comment}`;
+}
+function examples(cmd, entries) {
+  EXAMPLES.add(cmd);
+  return cmd.addHelpText("after", () => {
+    const path = commandPath(cmd);
+    return `
+Examples:
+${entries.map((e) => exampleLine(path, e)).join("\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 CliAuthError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CliAuthError";
+  }
+};
+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
+    };
+  }
+  if (err instanceof CliAuthError) {
+    return { type: "auth", message: message || "Missing credentials", recovery: opts.authRecovery, 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;
+  if (n.type === "auth" && n.detail === void 0 && opts.credentialInfo) {
+    n.detail = opts.credentialInfo();
+  }
+  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;
@@ -67,41 +317,12 @@ function getMetaFields(client) {
 
 // src/utils/client.ts
 import { BambooHRClient } from "bamboohr-client";
-
-// src/utils/credentials.ts
-function getCredentialInfo() {
-  const companyDomain = process.env.BAMBOO_COMPANY_DOMAIN;
-  const token = process.env.BAMBOO_TOKEN;
-  return {
-    environment: {
-      BAMBOO_COMPANY_DOMAIN: {
-        value: companyDomain ?? null,
-        description: 'Company subdomain (e.g., "mycompany" for mycompany.bamboohr.com)'
-      },
-      BAMBOO_TOKEN: {
-        value: token ? "<set>" : null,
-        description: "BambooHR API token"
-      }
-    },
-    tokenUrl: `https://${companyDomain ?? "<companyDomain>"}.bamboohr.com/app/settings/permissions/api_keys`,
-    hint: "Export environment variables in your shell profile (e.g., ~/.zshrc)."
-  };
-}
-
-// src/utils/client.ts
 function getClient() {
   const apiToken = process.env.BAMBOO_TOKEN;
   const companyDomain = process.env.BAMBOO_COMPANY_DOMAIN;
   if (!apiToken || !companyDomain) {
     const missing = [...!apiToken ? ["BAMBOO_TOKEN"] : [], ...!companyDomain ? ["BAMBOO_COMPANY_DOMAIN"] : []];
-    process.stderr.write(
-      `${JSON.stringify({
-        error: `Missing required environment variables: ${missing.join(", ")}`,
-        ...getCredentialInfo()
-      })}
-`
-    );
-    process.exit(1);
+    throw new CliAuthError(`Missing required environment variables: ${missing.join(", ")}`);
   }
   return new BambooHRClient({ apiToken, companyDomain });
 }
@@ -115,68 +336,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() {
@@ -296,13 +455,9 @@ function transformFields(fields2) {
 
 // src/commands/employee/directory.ts
 function directory(parent) {
-  parent.command("directory").description("Get the company employee directory").option("--with-photos", "Include each employee's signed photo URL and photoUploaded flag (large)").addHelpText(
-    "after",
-    `
-Examples:
-  $ bamboohr employee directory
-  $ bamboohr employee directory --with-photos`
-  ).action(async (opts) => {
+  const cmd = parent.command("directory").description("Get the company employee directory").option("--with-photos", "Include each employee's signed photo URL and photoUploaded flag (large)");
+  examples(cmd, ["", "--with-photos"]);
+  cmd.action(async (opts) => {
     const client = getClient();
     const result = await getDirectory(client);
     output(transformEmployeeDirectory(result, { withPhotos: opts.withPhotos }));
@@ -311,25 +466,26 @@ 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(
-    "after",
-    `
-Examples:
-  $ bamboohr employee get
-  $ bamboohr employee get 123
-  $ 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 }));
-  });
+  const cmd = 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");
+  examples(cmd, [
+    "",
+    "123",
+    ['123 --fields "firstName,lastName,department,hireDate"', "custom fields"],
+    "123 --include-future",
+    "123 --with-photos"
+  ]);
+  cmd.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 +499,12 @@ 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(
-    "after",
-    `
-Examples:
-  $ bamboohr employee goals 123
-  $ bamboohr employee goals 123 --filter open`
-  ).action(async (id, opts) => {
+  const cmd = parent.command("goals <employeeId>").description("Get employee performance goals").addOption(new Option("--filter <filter>", "Filter goals by status").choices(GOAL_FILTERS).default("all"));
+  examples(cmd, ["123", ["123 --filter open", "only open goals"], ["123 --filter closed", "only closed goals"]]);
+  cmd.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 +516,12 @@ 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(
-    "after",
-    `
-Examples:
-  $ bamboohr employee photo 123 --output ./photo.jpg
-  $ bamboohr employee photo 123 --output ./photo.jpg --size large`
-  ).action(async (id, opts) => {
+  const cmd = 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"));
+  examples(cmd, [["123 --output ./photo.jpg", "medium size (default)"], "123 --output ./photo.jpg --size large"]);
+  cmd.action(async (employeeId, opts) => {
     const client = getClient();
     const buffer = await client.employees.getPhoto({
-      employeeId: id,
+      employeeId,
       size: opts.size
     });
     writeFileSync2(opts.output, buffer);
@@ -390,16 +538,15 @@ async function resolveEmployeeId(client, employeeId) {
 
 // src/commands/employee/search.ts
 function search(parent) {
-  parent.command("search [query]").description("Search and filter employees").option("--supervisor <name>", 'Filter by supervisor name (use "me" for current user)').option("--department <name>", "Filter by department").option("--location <name>", "Filter by location").option("--division <name>", "Filter by division").option("--with-photos", "Include each result's signed photo URL and photoUploaded flag").addHelpText(
-    "after",
-    `
-Examples:
-  bamboohr employee search john
-  bamboohr employee search --supervisor me
-  bamboohr employee search --department "R&D" --location Sofia
-  bamboohr employee search --supervisor "Borislav Mihaylov"
-  bamboohr employee search john --with-photos`
-  ).action(
+  const cmd = parent.command("search [query]").description("Search and filter employees").option("--supervisor <name>", 'Filter by supervisor name (use "me" for current user)').option("--department <name>", "Filter by department").option("--location <name>", "Filter by location").option("--division <name>", "Filter by division").option("--with-photos", "Include each result's signed photo URL and photoUploaded flag");
+  examples(cmd, [
+    "john",
+    "--supervisor me",
+    ['--department "R&D" --location Sofia', "filter by dept and location"],
+    '--supervisor "Borislav Mihaylov"',
+    "john --with-photos"
+  ]);
+  cmd.action(
     async (query, opts) => {
       const client = getClient();
       const dir = await getDirectory(client);
@@ -439,18 +586,15 @@ Examples:
 }
 
 // src/commands/employee/index.ts
-function registerEmployeeCommands(program2) {
-  const employee = program2.command("employee").description("Employee operations").addHelpText(
-    "after",
-    `
-Examples:
-  $ bamboohr employee get
-  $ bamboohr employee get 123 --fields "firstName,lastName,department"
-  $ bamboohr employee directory
-  $ bamboohr employee photo 123 --output ./photo.jpg
-  $ bamboohr employee goals 123 --filter open
-`
-  );
+function registerEmployeeCommands(program) {
+  const employee = program.command("employee").description("Employee operations");
+  examples(employee, [
+    "get",
+    ['get 123 --fields "firstName,lastName,department"', "custom fields"],
+    "directory",
+    ["photo 123 --output ./photo.jpg", "download photo"],
+    ["goals 123 --filter open", "open goals"]
+  ]);
   get(employee);
   search(employee);
   directory(employee);
@@ -461,12 +605,9 @@ Examples:
 // src/commands/file/get.ts
 import { writeFileSync as writeFileSync3 } from "fs";
 function get2(parent) {
-  parent.command("get <fileId>").description("Download a company file").requiredOption("--output <path>", "File path to save to").addHelpText(
-    "after",
-    `
-Examples:
-  $ bamboohr file get 42 --output ./handbook.pdf`
-  ).action(async (fileId, opts) => {
+  const cmd = parent.command("get <fileId>").description("Download a company file").requiredOption("--output <path>", "File path to save to");
+  examples(cmd, ["42 --output ./handbook.pdf"]);
+  cmd.action(async (fileId, opts) => {
     const client = getClient();
     const buffer = await client.files.get({ fileId });
     writeFileSync3(opts.output, buffer);
@@ -476,7 +617,9 @@ Examples:
 
 // src/commands/file/list.ts
 function list(parent) {
-  parent.command("list").description("List all company files and categories").addHelpText("after", "\nExamples:\n  $ bamboohr file list").action(async () => {
+  const cmd = parent.command("list").description("List all company files and categories");
+  examples(cmd, [""]);
+  cmd.action(async () => {
     const client = getClient();
     const result = await client.files.list();
     output(transformCompanyFiles(result));
@@ -484,22 +627,18 @@ function list(parent) {
 }
 
 // src/commands/file/index.ts
-function registerFileCommands(program2) {
-  const file = program2.command("file").description("Company file operations").addHelpText(
-    "after",
-    `
-Examples:
-  $ bamboohr file list
-  $ bamboohr file get 42 --output ./handbook.pdf
-`
-  );
+function registerFileCommands(program) {
+  const file = program.command("file").description("Company file operations");
+  examples(file, ["list", ["get 42 --output ./handbook.pdf", "download a file"]]);
   list(file);
   get2(file);
 }
 
 // src/commands/meta/departments.ts
 function departments(parent) {
-  parent.command("departments").description("List all departments").addHelpText("after", "\nExamples:\n  bamboohr meta departments").action(async () => {
+  const cmd = parent.command("departments").description("List all departments");
+  examples(cmd, [""]);
+  cmd.action(async () => {
     const client = getClient();
     const dir = await getDirectory(client);
     const unique = [...new Set(dir.employees.map((e) => e.department).filter(Boolean))].sort();
@@ -509,7 +648,9 @@ function departments(parent) {
 
 // src/commands/meta/divisions.ts
 function divisions(parent) {
-  parent.command("divisions").description("List all divisions").addHelpText("after", "\nExamples:\n  bamboohr meta divisions").action(async () => {
+  const cmd = parent.command("divisions").description("List all divisions");
+  examples(cmd, [""]);
+  cmd.action(async () => {
     const client = getClient();
     const dir = await getDirectory(client);
     const unique = [...new Set(dir.employees.map((e) => e.division).filter(Boolean))].sort();
@@ -519,7 +660,9 @@ function divisions(parent) {
 
 // src/commands/meta/fields.ts
 function fields(parent) {
-  parent.command("fields").description("List all available BambooHR fields").addHelpText("after", "\nExamples:\n  $ bamboohr meta fields").action(async () => {
+  const cmd = parent.command("fields").description("List all available BambooHR fields");
+  examples(cmd, [""]);
+  cmd.action(async () => {
     const client = getClient();
     const result = await getMetaFields(client);
     output(transformFields(result));
@@ -528,7 +671,9 @@ function fields(parent) {
 
 // src/commands/meta/locations.ts
 function locations(parent) {
-  parent.command("locations").description("List all office locations").addHelpText("after", "\nExamples:\n  bamboohr meta locations").action(async () => {
+  const cmd = parent.command("locations").description("List all office locations");
+  examples(cmd, [""]);
+  cmd.action(async () => {
     const client = getClient();
     const dir = await getDirectory(client);
     const unique = [...new Set(dir.employees.map((e) => e.location).filter(Boolean))].sort();
@@ -537,17 +682,9 @@ function locations(parent) {
 }
 
 // src/commands/meta/index.ts
-function registerMetaCommands(program2) {
-  const meta = program2.command("meta").description("Metadata operations").addHelpText(
-    "after",
-    `
-Examples:
-  $ bamboohr meta fields
-  $ bamboohr meta departments
-  $ bamboohr meta locations
-  $ bamboohr meta divisions
-`
-  );
+function registerMetaCommands(program) {
+  const meta = program.command("meta").description("Metadata operations");
+  examples(meta, ["fields", "departments", "locations", "divisions"]);
   fields(meta);
   departments(meta);
   locations(meta);
@@ -556,14 +693,9 @@ Examples:
 
 // src/commands/timeoff/balance.ts
 function balance(parent) {
-  parent.command("balance [employeeId]").description("Estimate time off balance (defaults to current user)").option("--date <date>", "Future date to estimate balance for (YYYY-MM-DD)").addHelpText(
-    "after",
-    `
-Examples:
-  $ bamboohr timeoff balance
-  $ bamboohr timeoff balance 123
-  $ bamboohr timeoff balance --date 2026-06-30`
-  ).action(async (employeeId, opts) => {
+  const cmd = parent.command("balance [employeeId]").description("Estimate time off balance (defaults to current user)").option("--date <date>", "Future date to estimate balance for (YYYY-MM-DD)");
+  examples(cmd, ["", "123", ["--date 2026-06-30", "balance at a future date"]]);
+  cmd.action(async (employeeId, opts) => {
     const client = getClient();
     const id = await resolveEmployeeId(client, employeeId);
     const result = await client.timeOff.getBalance({ employeeId: id, date: opts.date });
@@ -573,28 +705,18 @@ 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(
+  const cmd = 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")
-  ).option("--note <text>", "Note to include with the request").option("--dates <json>", `Per-day amounts as JSON array, e.g. '[{"ymd":"2026-03-21","amount":4}]' for half-day`).addHelpText(
-    "after",
-    `
-Examples:
-  $ bamboohr timeoff create --start-date 2026-04-01 --end-date 2026-04-01 --type-id 83 --amount 1
-  $ bamboohr timeoff create 504 --start-date 2026-04-01 --end-date 2026-04-01 --type-id 83 --amount 1 --note "Doctor appointment"`
-  ).action(
+  ).option("--note <text>", "Note to include with the request").option("--dates <json>", `Per-day amounts as JSON array, e.g. '[{"ymd":"2026-03-21","amount":4}]' for half-day`);
+  examples(cmd, [
+    "--start-date 2026-04-01 --end-date 2026-04-01 --type-id 83 --amount 1",
+    [
+      '504 --start-date 2026-04-01 --end-date 2026-04-01 --type-id 83 --amount 1 --note "Doctor appointment"',
+      "for another employee"
+    ]
+  ]);
+  cmd.action(
     async (employeeId, opts) => {
       const client = getClient();
       const id = await resolveEmployeeId(client, employeeId);
@@ -618,7 +740,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(
+  const cmd = 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 +748,31 @@ function requests(parent) {
       "requested",
       "canceled"
     ])
-  ).option("--type <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`
-  ).action(
+  ).option("--type-id <typeId>", "Filter by time off type ID");
+  examples(cmd, [
+    "",
+    "--status requested",
+    ["--all --action approve --status requested", "all pending approvals"],
+    ["--employee-id 123 --start-date 2026-01-01 --end-date 2026-03-31", "Q1 for employee 123"]
+  ]);
+  cmd.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));
     }
@@ -660,13 +781,9 @@ Examples:
 
 // src/commands/timeoff/types.ts
 function types(parent) {
-  parent.command("types").description("List available time off types").option("--requestable", "Only show types the user can request").addHelpText(
-    "after",
-    `
-Examples:
-  $ bamboohr timeoff types
-  $ bamboohr timeoff types --requestable`
-  ).action(async (opts) => {
+  const cmd = parent.command("types").description("List available time off types").option("--requestable", "Only show types the user can request");
+  examples(cmd, ["", ["--requestable", "only types the current user can request"]]);
+  cmd.action(async (opts) => {
     const client = getClient();
     const result = opts.requestable ? await client.timeOff.getTypes({ mode: "request" }) : await getTimeOffTypes(client);
     output(transformTimeOffTypesResponse(result));
@@ -676,16 +793,15 @@ Examples:
 // src/commands/timeoff/update-status.ts
 import { Option as Option5 } from "commander";
 function updateStatus(parent) {
-  parent.command("update-status <requestId>").description("Update time off request status (approve, deny, cancel)").addOption(
+  const cmd = parent.command("update-status <requestId>").description("Update time off request status (approve, deny, cancel)").addOption(
     new Option5("--status <status>", "New status").choices(["approved", "denied", "canceled"]).makeOptionMandatory()
-  ).option("--note <text>", "Note to attach to the status change").addHelpText(
-    "after",
-    `
-Examples:
-  $ bamboohr timeoff update-status 7890 --status approved
-  $ bamboohr timeoff update-status 7890 --status denied --note "Team at capacity that week"
-  $ bamboohr timeoff update-status 7890 --status canceled`
-  ).action(async (requestId, opts) => {
+  ).option("--note <text>", "Note to attach to the status change");
+  examples(cmd, [
+    "7890 --status approved",
+    ['7890 --status denied --note "Team at capacity that week"', "deny with note"],
+    "7890 --status canceled"
+  ]);
+  cmd.action(async (requestId, opts) => {
     const client = getClient();
     const result = await client.timeOff.updateRequestStatus({
       requestId,
@@ -698,13 +814,9 @@ Examples:
 
 // src/commands/timeoff/whos-out.ts
 function whosOut(parent) {
-  parent.command("whos-out").description("View who's out \u2014 upcoming time off and holidays").option("--start-date <date>", "Start date (YYYY-MM-DD, defaults to today)").option("--end-date <date>", "End date (YYYY-MM-DD, defaults to today)").addHelpText(
-    "after",
-    `
-Examples:
-  $ bamboohr timeoff whos-out
-  $ bamboohr timeoff whos-out --start-date 2026-03-20 --end-date 2026-04-03`
-  ).action(async (opts) => {
+  const cmd = parent.command("whos-out").description("View who's out \u2014 upcoming time off and holidays").option("--start-date <date>", "Start date (YYYY-MM-DD, defaults to today)").option("--end-date <date>", "End date (YYYY-MM-DD, defaults to today)");
+  examples(cmd, ["", ["--start-date 2026-03-20 --end-date 2026-04-03", "two-week window"]]);
+  cmd.action(async (opts) => {
     const client = getClient();
     const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
     const start = opts.startDate ?? today;
@@ -715,19 +827,16 @@ Examples:
 }
 
 // src/commands/timeoff/index.ts
-function registerTimeoffCommands(program2) {
-  const timeoff = program2.command("timeoff").description("Time off operations").addHelpText(
-    "after",
-    `
-Examples:
-  $ bamboohr timeoff types --requestable
-  $ bamboohr timeoff create 504 --start-date 2026-04-01 --end-date 2026-04-01 --type-id 83 --amount 1
-  $ bamboohr timeoff requests --status requested --start-date 2026-01-01 --end-date 2026-12-31
-  $ bamboohr timeoff balance 504
-  $ bamboohr timeoff whos-out
-  $ bamboohr timeoff update-status 7890 --status approved
-`
-  );
+function registerTimeoffCommands(program) {
+  const timeoff = program.command("timeoff").description("Time off operations");
+  examples(timeoff, [
+    "types --requestable",
+    "create 504 --start-date 2026-04-01 --end-date 2026-04-01 --type-id 83 --amount 1",
+    ["requests --status requested --start-date 2026-01-01 --end-date 2026-12-31", "pending requests in date range"],
+    "balance 504",
+    "whos-out",
+    "update-status 7890 --status approved"
+  ]);
   types(timeoff);
   create(timeoff);
   requests(timeoff);
@@ -736,31 +845,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 +872,54 @@ ${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/utils/credentials.ts
+function getCredentialInfo() {
+  const companyDomain = process.env.BAMBOO_COMPANY_DOMAIN;
+  const token = process.env.BAMBOO_TOKEN;
+  return {
+    environment: {
+      BAMBOO_COMPANY_DOMAIN: {
+        value: companyDomain ?? null,
+        description: 'Company subdomain (e.g., "mycompany" for mycompany.bamboohr.com)'
+      },
+      BAMBOO_TOKEN: {
+        value: token ? "<set>" : null,
+        description: "BambooHR API token"
+      }
+    },
+    tokenUrl: `https://${companyDomain ?? "<companyDomain>"}.bamboohr.com/app/settings/permissions/api_keys`
+  };
+}
+
+// src/index.ts
+await runCli(buildProgram(), {
+  credentialInfo: getCredentialInfo,
+  service: "BambooHR",
+  authRecovery: "Set the BAMBOO_TOKEN and BAMBOO_COMPANY_DOMAIN environment variables.",
+  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-g40cd2b1.10",
   "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"
   }
 }