bamboohr-debug-bundle

# 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

```bash
#!/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)

```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

- [BambooHR Support](https://www.bamboohr.com/contact-support/)
- [BambooHR Status Page](https://status.bamboohr.com)

## Next Steps

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