hubspot-debug-bundle

# HubSpot Debug Bundle

## Overview

Collect all necessary diagnostic information for HubSpot API troubleshooting and support ticket escalation, including correlation IDs, rate limit state, and SDK versions.

## Prerequisites

- `@hubspot/api-client` installed
- Access to application logs
- `HUBSPOT_ACCESS_TOKEN` environment variable set

## Instructions

### Step 1: Create Debug Bundle Script

```bash
#!/bin/bash
# hubspot-debug-bundle.sh

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

echo "=== HubSpot Debug Bundle ===" > "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"
```

### Step 2: Collect Environment and SDK Info

```bash
echo "--- Runtime ---" >> "$BUNDLE_DIR/summary.txt"
node --version >> "$BUNDLE_DIR/summary.txt" 2>&1
npm --version >> "$BUNDLE_DIR/summary.txt" 2>&1
echo "HUBSPOT_ACCESS_TOKEN: ${HUBSPOT_ACCESS_TOKEN:+[SET]}" >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

# SDK version
echo "--- @hubspot/api-client ---" >> "$BUNDLE_DIR/summary.txt"
npm list @hubspot/api-client 2>/dev/null >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"
```

### Step 3: Test API Connectivity and Rate Limits

```bash
echo "--- API Connectivity ---" >> "$BUNDLE_DIR/summary.txt"

# Test the API and capture headers
curl -sI https://api.hubapi.com/crm/v3/objects/contacts?limit=1 \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}" \
  > "$BUNDLE_DIR/api-headers.txt" 2>&1

# Extract key info
echo "HTTP Status: $(head -1 "$BUNDLE_DIR/api-headers.txt")" >> "$BUNDLE_DIR/summary.txt"
grep -i "x-hubspot-ratelimit" "$BUNDLE_DIR/api-headers.txt" >> "$BUNDLE_DIR/summary.txt"
grep -i "x-request-id" "$BUNDLE_DIR/api-headers.txt" >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

# Test specific endpoints
for endpoint in contacts companies deals tickets; do
  STATUS=$(curl -so /dev/null -w "%{http_code}" \
    "https://api.hubapi.com/crm/v3/objects/${endpoint}?limit=1" \
    -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}")
  echo "${endpoint}: HTTP ${STATUS}" >> "$BUNDLE_DIR/summary.txt"
done
echo "" >> "$BUNDLE_DIR/summary.txt"

# Check scopes via token info
echo "--- Token Info ---" >> "$BUNDLE_DIR/summary.txt"
curl -s "https://api.hubapi.com/oauth/v1/access-tokens/${HUBSPOT_ACCESS_TOKEN}" \
  2>/dev/null | jq '{user: .user, hub_id: .hub_id, scopes: .scopes, token_type: .token_type}' \
  >> "$BUNDLE_DIR/summary.txt" 2>/dev/null || echo "Token info unavailable (private app tokens)" >> "$BUNDLE_DIR/summary.txt"
```

### Step 4: Collect Application Logs (Redacted)

```bash
echo "--- Recent Logs (redacted) ---" >> "$BUNDLE_DIR/summary.txt"

# Collect recent HubSpot-related errors from application logs
if [ -f "logs/app.log" ]; then
  grep -i "hubspot\|hubapi\|crm/v3" logs/app.log 2>/dev/null | tail -100 \
    | sed -E 's/pat-[a-z0-9-]+/[REDACTED_TOKEN]/g' \
    | sed -E 's/"email":"[^"]+/"email":"[REDACTED]/g' \
    > "$BUNDLE_DIR/logs-redacted.txt"
fi

# Capture correlationIds from recent errors
grep -oP '"correlationId":"[^"]+"' logs/app.log 2>/dev/null | sort -u \
  > "$BUNDLE_DIR/correlation-ids.txt"

# Redact all secrets from config
if [ -f ".env" ]; then
  sed 's/=.*/=***REDACTED***/' .env > "$BUNDLE_DIR/config-redacted.txt"
fi
```

### Step 5: Package and Verify

```bash
# Check HubSpot status page
echo "--- HubSpot Status ---" >> "$BUNDLE_DIR/summary.txt"
curl -s https://status.hubspot.com/api/v2/summary.json 2>/dev/null \
  | jq '{status: .status.description, incidents: [.incidents[] | {name, status}]}' \
  >> "$BUNDLE_DIR/summary.txt" 2>/dev/null || echo "Status page unreachable" >> "$BUNDLE_DIR/summary.txt"

# Package
tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
rm -rf "$BUNDLE_DIR"
echo ""
echo "Bundle created: $BUNDLE_DIR.tar.gz"
echo "REVIEW FOR SENSITIVE DATA BEFORE SHARING"
```

### Programmatic Debug Info

```typescript
import * as hubspot from '@hubspot/api-client';

async function collectHubSpotDiagnostics() {
  const client = new hubspot.Client({
    accessToken: process.env.HUBSPOT_ACCESS_TOKEN!,
  });

  const diagnostics: Record<string, any> = {
    timestamp: new Date().toISOString(),
    sdkVersion: require('@hubspot/api-client/package.json').version,
    nodeVersion: process.version,
  };

  // Test each CRM object type
  const objectTypes = ['contacts', 'companies', 'deals', 'tickets'];
  for (const objType of objectTypes) {
    try {
      const start = Date.now();
      await client.apiRequest({
        method: 'GET',
        path: `/crm/v3/objects/${objType}?limit=1`,
      });
      diagnostics[objType] = { status: 'OK', latencyMs: Date.now() - start };
    } catch (error: any) {
      diagnostics[objType] = {
        status: 'ERROR',
        code: error.code || error.statusCode,
        message: error.body?.message || error.message,
        correlationId: error.body?.correlationId,
      };
    }
  }

  return diagnostics;
}
```

## Output

- `hubspot-debug-YYYYMMDD-HHMMSS.tar.gz` archive containing:
  - `summary.txt` -- environment, SDK version, API status, rate limits
  - `api-headers.txt` -- raw HTTP response headers
  - `correlation-ids.txt` -- unique error correlation IDs
  - `logs-redacted.txt` -- recent logs with secrets removed
  - `config-redacted.txt` -- configuration (values masked)

## Error Handling

| Item | Purpose | Included |
|------|---------|----------|
| SDK version | Version-specific bugs | Yes |
| HTTP status per object | Scope/permission issues | Yes |
| Rate limit headers | Throttling diagnosis | Yes |
| Correlation IDs | HubSpot support reference | Yes |
| HubSpot status page | Platform outage detection | Yes |

## Examples

### What to Redact Before Sharing

**ALWAYS REDACT:**
- Access tokens (start with `pat-` or JWT)
- Email addresses and phone numbers
- Company names from test data
- Portal IDs (unless sharing with HubSpot support)

**Safe to Include:**
- Error messages and categories
- Correlation IDs (HubSpot support needs these)
- HTTP status codes
- SDK/runtime versions
- Rate limit remaining counts

## Resources

- [HubSpot Support Portal](https://help.hubspot.com/)
- [HubSpot Status Page](https://status.hubspot.com)
- [Error Handling Guide](https://developers.hubspot.com/docs/api-reference/error-handling)

## Next Steps

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