BambooHR Debug Bundle Skill

BambooHR Debug Bundle

Overview

Collect all diagnostic information for BambooHR API troubleshooting or support tickets. Captures connectivity tests, API response details, environment info, and redacted configuration.

Prerequisites

BambooHR environment variables set
curl available for API tests
Permission to collect environment info

Instructions

Step 1: Complete Debug Bundle Script

#!/bin/bash
# bamboohr-debug-bundle.sh — Run this, then send the .tar.gz to support

set -euo pipefail

BUNDLE_DIR="bamboohr-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

DOMAIN="${BAMBOOHR_COMPANY_DOMAIN:?Set BAMBOOHR_COMPANY_DOMAIN}"
API_KEY="${BAMBOOHR_API_KEY:?Set BAMBOOHR_API_KEY}"
BASE="https://api.bamboohr.com/api/gateway.php/${DOMAIN}/v1"

exec > >(tee "$BUNDLE_DIR/summary.txt") 2>&1

echo "=== BambooHR Debug Bundle ==="
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
echo "Company Domain: ${DOMAIN}"
echo "API Key: ${API_KEY:0:4}****${API_KEY: -4}"
echo ""

# ── Environment ──────────────────────────────────────
echo "--- Runtime Environment ---"
echo "Node.js: $(node --version 2>/dev/null || echo 'not installed')"
echo "npm: $(npm --version 2>/dev/null || echo 'not installed')"
echo "Python: $(python3 --version 2>/dev/null || echo 'not installed')"
echo "curl: $(curl --version 2>/dev/null | head -1)"
echo "OS: $(uname -a)"
echo ""

# ── API Connectivity Test ────────────────────────────
echo "--- API Connectivity ---"
echo -n "Directory endpoint: "
curl -s -o "$BUNDLE_DIR/directory-response.json" \
  -w "HTTP %{http_code} | %{time_total}s | %{size_download} bytes\n" \
  -u "${API_KEY}:x" \
  -H "Accept: application/json" \
  "${BASE}/employees/directory"

echo -n "Employee endpoint: "
curl -s -o "$BUNDLE_DIR/employee-response.json" \
  -w "HTTP %{http_code} | %{time_total}s | %{size_download} bytes\n" \
  -u "${API_KEY}:x" \
  -H "Accept: application/json" \
  "${BASE}/employees/0/?fields=firstName"

echo -n "Time off types: "
curl -s -o "$BUNDLE_DIR/timeoff-types-response.json" \
  -w "HTTP %{http_code} | %{time_total}s\n" \
  -u "${API_KEY}:x" \
  -H "Accept: application/json" \
  "${BASE}/meta/time_off/types"

echo ""

# ── Response Headers (verbose for one endpoint) ─────
echo "--- Response Headers (directory) ---"
curl -s -I -u "${API_KEY}:x" \
  -H "Accept: application/json" \
  "${BASE}/employees/directory" \
  | grep -iE "^(x-bamboohr|content-type|retry-after|date|server)" \
  > "$BUNDLE_DIR/response-headers.txt"
cat "$BUNDLE_DIR/response-headers.txt"
echo ""

# ── Project Dependencies ─────────────────────────────
echo "--- Project Dependencies ---"
if [ -f package.json ]; then
  node -e "
    const pkg = require('./package.json');
    const deps = {...pkg.dependencies, ...pkg.devDependencies};
    const bamboo = Object.entries(deps).filter(([k]) => k.includes('bamboo'));
    const http = Object.entries(deps).filter(([k]) => ['axios','node-fetch','got','ky'].includes(k));
    console.log('BambooHR packages:', bamboo.length ? bamboo.map(([k,v]) => k+'@'+v).join(', ') : 'none (using fetch)');
    console.log('HTTP clients:', http.length ? http.map(([k,v]) => k+'@'+v).join(', ') : 'native fetch');
  " 2>/dev/null || echo "Could not parse package.json"
fi
echo ""

# ── Configuration (redacted) ─────────────────────────
echo "--- Configuration (redacted) ---"
if [ -f .env ]; then
  sed 's/=.*/=***REDACTED***/' .env > "$BUNDLE_DIR/config-redacted.txt"
  echo "Found .env with $(wc -l < .env) lines"
else
  echo "No .env file found"
fi

# ── Redact sensitive data from API responses ─────────
for f in "$BUNDLE_DIR"/*-response.json; do
  if [ -f "$f" ]; then
    # Remove email addresses and phone numbers from responses
    sed -i 's/[a-zA-Z0-9._%+-]*@[a-zA-Z0-9.-]*/***@redacted/g' "$f"
    sed -i 's/[0-9]\{3\}[-. ][0-9]\{3\}[-. ][0-9]\{4\}/***-***-****/g' "$f"
  fi
done

echo ""
echo "--- Bundle Complete ---"

# ── Package ──────────────────────────────────────────
tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
echo "Created: $BUNDLE_DIR.tar.gz ($(du -h "$BUNDLE_DIR.tar.gz" | cut -f1))"
echo ""
echo "BEFORE SHARING: Review $BUNDLE_DIR/ for any remaining PII"

Step 2: Programmatic Debug Info (TypeScript)

import { BambooHRClient, BambooHRApiError } from './bamboohr/client';

interface DiagnosticResult {
  timestamp: string;
  environment: Record<string, string>;
  connectivity: {
    endpoint: string;
    status: number;
    latencyMs: number;
    error?: string;
  }[];
}

async function collectDiagnostics(client: BambooHRClient): Promise<DiagnosticResult> {
  const endpoints = [
    '/employees/directory',
    '/meta/time_off/types',
    '/meta/lists/',
  ];

  const connectivity = await Promise.all(
    endpoints.map(async (endpoint) => {
      const start = Date.now();
      try {
        await client.request('GET', endpoint);
        return { endpoint, status: 200, latencyMs: Date.now() - start };
      } catch (err) {
        const status = err instanceof BambooHRApiError ? err.status : 0;
        return {
          endpoint, status, latencyMs: Date.now() - start,
          error: (err as Error).message,
        };
      }
    }),
  );

  return {
    timestamp: new Date().toISOString(),
    environment: {
      nodeVersion: process.version,
      platform: process.platform,
      companyDomain: process.env.BAMBOOHR_COMPANY_DOMAIN || 'NOT SET',
      apiKeySet: process.env.BAMBOOHR_API_KEY ? 'yes' : 'NO',
    },
    connectivity,
  };
}

Output

bamboohr-debug-YYYYMMDD-HHMMSS.tar.gz archive containing:
- summary.txt — Environment, connectivity, and dependency info
- directory-response.json — Redacted API response sample
- response-headers.txt — BambooHR-specific headers
- config-redacted.txt — Environment config with secrets removed

Sensitive Data Handling

Always redact before sharing:

API keys and tokens
Employee emails, phone numbers, SSNs
Home addresses and personal info
Salary and compensation data

Safe to include:

HTTP status codes and error messages
Response latencies and sizes
X-BambooHR-Error-Message header values
SDK/runtime versions

Error Handling

| Issue | Cause | Solution | |-------|-------|----------| | curl not found | Not installed | Install curl or use Node.js version | | Permission denied | Script not executable | chmod +x bamboohr-debug-bundle.sh | | Empty response files | Auth failure | Check API key before running | | Large bundle size | Too many response files | Reduce to key endpoints only |

Resources

Next Steps

For rate limit issues, see bamboohr-rate-limits.

Agent Skills: BambooHR Debug Bundle

Install this agent skill to your local

Skill Files