bamboohr-cli 1.0.13 → 1.0.15

package/README.md

@@ -0,0 +1,91 @@
+# bamboohr-cli
+
+Command-line interface for the [BambooHR API](https://documentation.bamboohr.com/reference). 17 commands across 4 domains — employees, time off, files, and metadata.
+
+## Install
+
+```bash
+npm install -g bamboohr-cli
+```
+
+## Setup
+
+Set two environment variables in your shell profile:
+
+```bash
+export BAMBOO_TOKEN="your-api-token"           # BambooHR > Settings > API Keys
+export BAMBOO_COMPANY_DOMAIN="mycompany"        # the subdomain in mycompany.bamboohr.com
+```
+
+## Commands
+
+All commands output JSON. Add `--pretty` to pretty-print.
+
+### employee
+
+| Command | Description |
+|---------|-------------|
+| `bamboohr employee get [id]` | Get employee by ID (defaults to current user) |
+| `bamboohr employee search [query]` | Search employees by name, supervisor, department, location, division |
+| `bamboohr employee directory` | Get the full company directory |
+| `bamboohr employee photo <id>` | Download employee photo (`--size`: original, large, medium, small, xs, tiny) |
+| `bamboohr employee goals <id>` | Get performance goals (`--status`: open, closed, all) |
+
+### timeoff
+
+| Command | Description |
+|---------|-------------|
+| `bamboohr timeoff types` | List time off types (`--requestable` to filter) |
+| `bamboohr timeoff create [employeeId]` | Create a time off request (defaults to current user) |
+| `bamboohr timeoff requests` | List requests (`--status`, `--start`, `--end`, `--employee`, `--type`) |
+| `bamboohr timeoff balance [employeeId]` | Estimate time off balance (`--end` to project to future date) |
+| `bamboohr timeoff whos-out` | View who's out today and upcoming |
+| `bamboohr timeoff update-status <requestId>` | Approve, deny, or cancel a request |
+
+### file
+
+| Command | Description |
+|---------|-------------|
+| `bamboohr file list` | List all company files and categories |
+| `bamboohr file get <fileId>` | Download a company file |
+
+### meta
+
+| Command | Description |
+|---------|-------------|
+| `bamboohr meta fields` | List all available BambooHR fields |
+| `bamboohr meta departments` | List all departments |
+| `bamboohr meta locations` | List all office locations |
+| `bamboohr meta divisions` | List all divisions |
+
+## Pagination
+
+List commands accept `--limit` to control page size. Responses include a `nextPage` token — pass it back as `--offset` to fetch the next page. When `nextPage` is `null`, there are no more results.
+
+## Examples
+
+```bash
+# Look up your own employee record
+bamboohr employee get
+
+# Find someone by name
+bamboohr employee search "Jane"
+
+# Filter by supervisor (use "me" for your direct reports)
+bamboohr employee search --supervisor me
+
+# Download a photo
+bamboohr employee photo 123 --output ./photo.jpg --size large
+
+# Check who's out this week
+bamboohr timeoff whos-out
+
+# Request a day off
+bamboohr timeoff create --start 2026-04-20 --end 2026-04-20 --type-id 83 --amount 1
+
+# See pending requests for approval
+bamboohr timeoff requests --status requested --start 2026-01-01 --end 2026-12-31
+
+# List available fields for custom queries
+bamboohr meta fields
+```

package/dist/index.js

@@ -1,6 +1,9 @@
 #!/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";
 
@@ -114,7 +117,7 @@ function stripResponse(obj) {
   const record = obj;
   const result = {};
   for (const [key, value] of Object.entries(record)) {
-    if (key === "self" || key === "_links" || key === "_expandable" || key === "expand" || key === "avatarUrls" || key === "avatarId" || key === "iconUrl") {
+    if (value === null || value === void 0) {
       continue;
     }
     result[key] = stripResponse(value);
@@ -180,8 +183,16 @@ function handleError(err) {
 `
     );
   } else {
-    process.stderr.write(`${JSON.stringify({ error: message })}
-`);
+    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);
 }
@@ -218,10 +229,9 @@ Examples:
 
 // src/commands/employee/goals.ts
 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(["open", "closed", "all"]).default("all")
-  ).addHelpText(
+  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:
@@ -240,10 +250,9 @@ Examples:
 // src/commands/employee/photo.ts
 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(["original", "large", "medium", "small", "xs", "tiny"]).default("medium")
-  ).addHelpText(
+  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:
@@ -451,8 +460,20 @@ 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>", "Start date (YYYY-MM-DD)").requiredOption("--end <date>", "End date (YYYY-MM-DD)").requiredOption("--type-id <id>", 'Time off type ID (use "timeoff types" to find IDs)', parseInt).requiredOption("--amount <amount>", "Total amount of time off (in days or hours depending on type)", parseFloat).addOption(
+  parent.command("create [employeeId]").description("Create a time off request (defaults to current user)").requiredOption("--start <date>", "Start date (YYYY-MM-DD)").requiredOption("--end <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",
@@ -482,7 +503,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", parseInt).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>", "Start date (YYYY-MM-DD)").option("--end <date>", "End date (YYYY-MM-DD)").addOption(
+  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>", "Start date (YYYY-MM-DD)").option("--end <date>", "End date (YYYY-MM-DD)").addOption(
     new Option4("--status <status>", "Filter by request status").choices([
       "approved",
       "denied",
@@ -601,10 +622,20 @@ Examples:
 }
 
 // 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";
+  }
+}
 var DIM = "\x1B[2m";
 var RESET = "\x1B[0m";
 var program = new Command6();
-program.name("bamboohr").description("BambooHR CLI").version("1.0.0").configureHelp({
+program.name("bamboohr").description("BambooHR CLI").version(readPackageVersion()).configureHelp({
   styleTitle: (str) => styleText("bold", str),
   styleUsage: (str) => styleText("dim", str),
   styleCommandDescription: (str) => styleText("dim", str),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bamboohr-cli",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "publish": true,
   "type": "module",
   "main": "dist/index.js",
@@ -12,7 +12,7 @@
   ],
   "dependencies": {
     "commander": "^13.1.0",
-    "bamboohr-client": "1.0.20"
+    "bamboohr-client": "1.0.22"
   },
   "devDependencies": {
     "@types/node": "24.10.4",
@@ -22,9 +22,9 @@
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "vitest": "^4.0.16",
-    "config-typescript": "0.0.0",
+    "cli-utils": "1.0.0",
     "config-eslint": "0.0.0",
-    "cli-utils": "1.0.0"
+    "config-typescript": "0.0.0"
   },
   "engines": {
     "node": ">=22.0.0"