# airbridge-link-migrator-command

Command-line tool for batch migration to Airbridge Tracking Links from various sources.

## Installation

```bash
# Install globally
npm install -g airbridge-link-migrator-command

# Or use with npx
npx airbridge-link-migrator-command
```

## Usage

After installation, the tool is available as `abmig` (short alias) or `airbridge-link-migrator-command`:

```bash
abmig --source firebase \
      --appName "YourAirbridgeApp" \
      --apiToken "your-airbridge-api-token" \
      --scheme "scheme://" \
      --inputPath "input.csv" \
      --outputPath "output.csv" \
      --batchSize 100 \
      --index 0
```

## Options

### Required

- `--source <type>` - Source platform type (currently supports: "firebase")
- `--appName <name>` - Airbirdge app name
- `--apiToken <token>` - Airbridge API token
- `--scheme <scheme>` - App URL scheme (e.g., "scheme://")
- `--inputPath <path>` - Input CSV file path containing source links
- `--outputPath <path>` - Output CSV file path for Airbridge Tracking Links

### Optional

- `--batchSize <size>` - Number of links to process in parallel (default: 100)
- `--index <index>` - Starting index for processing, useful for resuming (default: auto-detect from output file or 0)

## CSV Format

### Firebase Dynamic Links

When using `--source firebase`, the tool processes Firebase Dynamic Links and converts them to Airbridge Tracking Links.

#### Input

The input CSV should have the following columns:
- `short_link` - Firebase short link URL
- `utm_source` - Traffic source (required, maps to channel)
- `utm_campaign` - Campaign name
- `utm_medium` - Marketing medium
- `utm_term` - Keywords
- `utm_content` - Ad content
- `link` - Deep link URL
- `afl` - Android fallback URL
- `ifl` - iOS fallback URL
- `ofl` - Desktop fallback URL
- `st` - Social title
- `sd` - Social description
- `si` - Social image URL

#### Output

The output CSV will contain:
- `firebase_short_link` - Original Firebase short link (for reference)
- `success` - true/false indicating migration success

When successful, the following Airbridge tracking parameters are included:
- `airbridge_long_url` - Airbridge long URL
- `airbridge_short_url` - Airbridge short URL
- `channel` - Marketing channel (from utm_source, required)
- `campaign` - Campaign name (from utm_campaign)
- `sub_publisher` - Sub-publisher/medium (from utm_medium)
- `keyword` - Search keywords (from utm_term)
- `content` - Ad content identifier (from utm_content)
- `deeplink` - App deep link URL (converted from link parameter)
- `android_fallback_path` - Android fallback URL (from afl)
- `ios_fallback_path` - iOS fallback URL (from ifl)
- `desktop_fallback_path` - Desktop fallback URL (from ofl)
- `title` - Social sharing title (from st)
- `description` - Social sharing description (from sd)
- `image_url` - Social sharing image URL (from si)

When failed, the following error message parameter is included:
- `error` - Error message (if failed)

## Features

### Auto-Resume
The tool automatically detects the progress from the output file and resumes from where it left off if interrupted.

### Rate Limiting
Automatically handles Airbridge API rate limits (40 requests per second).

**⚠️ Important: Do NOT run multiple CLI instances simultaneously!**
- Each CLI instance already maximizes the API rate limit (40 requests/second)
- Running multiple instances will cause API rate limit errors
- Multiple instances will NOT speed up migration, they will actually slow it down due to rate limit conflicts
- If you need to process multiple files, run them sequentially, not in parallel

### Progress Display
Shows real-time progress including:
- Current batch being processed
- Success/failure counts
- Processing speed
- Estimated time remaining

### Error Handling
- Continues processing even if individual links fail
- Failed items are included in output CSV with error messages
- Summary report at the end shows total successes and failures
- Common errors:
  - Missing utm_source (channel is required)
  - Invalid channel format (must be lowercase with only letters, numbers, underscore, hyphen, or dot)
  - API rate limit exceeded (automatically handled with retry)

## Examples

### Basic Migration (Firebase)
```bash
abmig --source firebase \
      --appName "MyApp" \
      --apiToken "abc123" \
      --scheme "myapp://" \
      --inputPath "firebase-links.csv" \
      --outputPath "airbridge-links.csv"
```

### Resume from Specific Index
```bash
abmig --source firebase \
      --appName "MyApp" \
      --apiToken "abc123" \
      --scheme "myapp://" \
      --inputPath "input.csv" \
      --outputPath "output.csv" \
      --index 5000
```

### Custom Batch Size
```bash
abmig --source firebase \
      --appName "MyApp" \
      --apiToken "abc123" \
      --scheme "myapp://" \
      --inputPath "input.csv" \
      --outputPath "output.csv" \
      --batchSize 50
```

## License

MIT