miro-debug-bundle

# Miro Debug Bundle

## Overview

Collect all diagnostic information needed to troubleshoot Miro REST API v2 integration issues and file effective support tickets.

## Prerequisites

- Access token (even expired ones are useful for diagnostics)
- `curl` and `jq` available
- Application logs accessible

## Instructions

### Step 1: Create the Debug Bundle Script

```bash
#!/bin/bash
# miro-debug-bundle.sh — Collect Miro API diagnostics
set -euo pipefail

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

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

### Step 2: Collect Environment Info

```bash
# Runtime environment
echo "--- Environment ---" >> "$BUNDLE_DIR/summary.txt"
echo "Node.js: $(node --version 2>/dev/null || echo 'not installed')" >> "$BUNDLE_DIR/summary.txt"
echo "npm: $(npm --version 2>/dev/null || echo 'not installed')" >> "$BUNDLE_DIR/summary.txt"
echo "OS: $(uname -srm)" >> "$BUNDLE_DIR/summary.txt"

# SDK version
echo "--- SDK Version ---" >> "$BUNDLE_DIR/summary.txt"
npm list @mirohq/miro-api 2>/dev/null >> "$BUNDLE_DIR/summary.txt" || echo "@mirohq/miro-api: not found" >> "$BUNDLE_DIR/summary.txt"

# Token presence (never log the actual token)
echo "--- Token Status ---" >> "$BUNDLE_DIR/summary.txt"
echo "MIRO_ACCESS_TOKEN: ${MIRO_ACCESS_TOKEN:+SET (length: ${#MIRO_ACCESS_TOKEN})}" >> "$BUNDLE_DIR/summary.txt"
echo "MIRO_CLIENT_ID: ${MIRO_CLIENT_ID:+SET}" >> "$BUNDLE_DIR/summary.txt"
echo "MIRO_REFRESH_TOKEN: ${MIRO_REFRESH_TOKEN:+SET}" >> "$BUNDLE_DIR/summary.txt"
```

### Step 3: API Connectivity Tests

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

# DNS resolution
echo -n "DNS resolve api.miro.com: " >> "$BUNDLE_DIR/summary.txt"
nslookup api.miro.com 2>/dev/null | grep "Address" | tail -1 >> "$BUNDLE_DIR/summary.txt" || echo "FAILED" >> "$BUNDLE_DIR/summary.txt"

# HTTPS connectivity (no auth needed)
echo -n "HTTPS to api.miro.com: " >> "$BUNDLE_DIR/summary.txt"
curl -s -o /dev/null -w "%{http_code} (%{time_total}s)" https://api.miro.com 2>&1 >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

# Authenticated API test
echo -n "GET /v2/boards: " >> "$BUNDLE_DIR/summary.txt"
curl -s -o "$BUNDLE_DIR/boards-response.json" -w "%{http_code} (%{time_total}s)" \
  -H "Authorization: Bearer ${MIRO_ACCESS_TOKEN:-none}" \
  "https://api.miro.com/v2/boards?limit=1" 2>&1 >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

# Rate limit status from response headers
echo "--- Rate Limit Status ---" >> "$BUNDLE_DIR/summary.txt"
curl -s -D "$BUNDLE_DIR/response-headers.txt" -o /dev/null \
  -H "Authorization: Bearer ${MIRO_ACCESS_TOKEN:-none}" \
  "https://api.miro.com/v2/boards?limit=1" 2>/dev/null
grep -i "x-ratelimit\|retry-after" "$BUNDLE_DIR/response-headers.txt" >> "$BUNDLE_DIR/summary.txt" 2>/dev/null || echo "No rate limit headers found" >> "$BUNDLE_DIR/summary.txt"

# Token info (scopes, user_id, team_id)
echo "--- Token Info ---" >> "$BUNDLE_DIR/summary.txt"
curl -s -H "Authorization: Bearer ${MIRO_ACCESS_TOKEN:-none}" \
  "https://api.miro.com/v1/oauth-token" 2>/dev/null | \
  jq '{scopes, team_id: .team.id, user_id: .user.id}' >> "$BUNDLE_DIR/summary.txt" 2>/dev/null || echo "Token introspection failed" >> "$BUNDLE_DIR/summary.txt"

# Miro platform status
echo "--- Miro Platform Status ---" >> "$BUNDLE_DIR/summary.txt"
curl -s "https://status.miro.com/api/v2/status.json" 2>/dev/null | \
  jq '.status' >> "$BUNDLE_DIR/summary.txt" 2>/dev/null || echo "Status page unreachable" >> "$BUNDLE_DIR/summary.txt"
```

### Step 4: Capture Recent Errors (Redacted)

```bash
echo "--- Recent Application Errors ---" >> "$BUNDLE_DIR/summary.txt"

# Search for Miro-related errors in common log locations
for logpath in \
  "$(npm prefix 2>/dev/null)/logs" \
  "$HOME/.npm/_logs" \
  "/var/log/app" \
  "./logs"; do
  if [ -d "$logpath" ]; then
    grep -ri "miro\|api\.miro\.com" "$logpath"/*.log 2>/dev/null | \
      tail -30 | \
      sed 's/Bearer [A-Za-z0-9._-]*/Bearer [REDACTED]/g' \
      >> "$BUNDLE_DIR/error-logs.txt" 2>/dev/null
  fi
done

# Redact .env file
if [ -f .env ]; then
  echo "--- Config (redacted) ---" > "$BUNDLE_DIR/config-redacted.txt"
  sed 's/=.*/=[REDACTED]/' .env >> "$BUNDLE_DIR/config-redacted.txt"
fi
```

### Step 5: Package the Bundle

```bash
# Remove raw response bodies that might contain sensitive data
rm -f "$BUNDLE_DIR/boards-response.json" "$BUNDLE_DIR/response-headers.txt"

tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
rm -rf "$BUNDLE_DIR"

echo ""
echo "Bundle created: $BUNDLE_DIR.tar.gz"
echo "Review contents before sharing with Miro support."
```

## Sensitive Data Handling

**ALWAYS redact before sharing:**
- Access tokens and refresh tokens
- Client secrets
- User email addresses and names
- Board content that may contain proprietary information

**Safe to include:**
- HTTP status codes and error messages
- Rate limit header values
- SDK and Node.js versions
- Token scopes (not the token itself)
- Request IDs (`X-Request-Id` header)

## One-Liner Diagnostics

```bash
# Quick API health check
curl -sw "\n%{http_code}" -H "Authorization: Bearer $MIRO_ACCESS_TOKEN" https://api.miro.com/v2/boards?limit=1 | tail -1

# Current rate limit status
curl -sI -H "Authorization: Bearer $MIRO_ACCESS_TOKEN" https://api.miro.com/v2/boards?limit=1 2>/dev/null | grep -i ratelimit

# Token scopes
curl -s -H "Authorization: Bearer $MIRO_ACCESS_TOKEN" https://api.miro.com/v1/oauth-token | jq '.scopes'
```

## Error Handling

| Diagnostic | What It Reveals | If It Fails |
|-----------|----------------|-------------|
| DNS lookup | Network/firewall issues | Check DNS config, VPN |
| HTTPS check | TLS/proxy issues | Check corporate proxy settings |
| Auth test | Token validity | Refresh or re-authorize |
| Rate limit headers | Credit consumption | Implement backoff |
| Token introspection | Scope configuration | Re-check app settings |

## Resources

- [Miro Status Page](https://status.miro.com)
- [Miro Developer Support](https://developers.miro.com/docs/getting-help)
- [OAuth Token Endpoint](https://developers.miro.com/docs/getting-started-with-oauth)

## Next Steps

For rate limit issues specifically, see `miro-rate-limits`.