Metadata-Version: 2.4
Name: crm-cli
Version: 0.1.5
Summary: FXiaoke CRM CLI - Sync leads from JSON/CSV files
Requires-Python: >=3.10
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Description-Content-Type: text/markdown

# CRM CLI

A minimal CLI that reads leads from JSON/CSV files and syncs them to FXiaoke CRM (纷享销客).

## Installation

Requires [UV](https://docs.astral.sh/uv/) (fast Python package manager).

```bash
# Install UV (if not already installed)
brew install uv

# Clone and sync dependencies
git clone https://github.com/thaddeus-git/crm-cli.git
cd crm-cli
uv sync
```

## Quick Start

```bash
# Sync leads from JSON file
uv run crm sync leads.json

# Preview without creating (dry run)
uv run crm sync leads.csv --dry-run

# Assign to specific owner (FSUID format)
uv run crm sync leads.json --owner FSUID_xxx
uv run crm sync leads.json --assign FSUID_xxx  # --assign is an alias for --owner

# Override lead pool (skip automatic routing)
uv run crm sync leads.json --pool 643d87b17be47e0a000190a715

# Combine flags
uv run crm sync leads.json --assign FSUID_xxx --pool 643d87cda34e0a0001336093
```

## User Lookup

Lookup CRM users by mobile number or list all users to find FSUIDs for assignment:

```bash
# Lookup user by mobile number
uv run crm lookup --mobile 18102106041

# List all users (paginated)
uv run crm lookup --list-all

# List with custom page size
uv run crm lookup --list-all --page-size 500
```

### Example Output

```
✓ User found:

  Name: 王雨檬
  FSUID: FSUID_4CF6AD1011C941AE32545CCC409CFD50
  Mobile: 18102106041
  Email: wangyumeng3@orionstar.com
  Status: NORMAL
```

### Using the FSUID

Once you have the FSUID, use it with the `--assign` flag when syncing leads:

```bash
uv run crm sync leads.json --assign FSUID_4CF6AD1011C941AE32545CCC409CFD50
```

**Note**: Store the default assignee FSUID in your shell profile or environment for convenience:

```bash
export CRM_DEFAULT_ASSIGNEE_FSUID="FSUID_4CF6AD1011C941AE32545CCC409CFD50"
uv run crm sync leads.json --assign $CRM_DEFAULT_ASSIGNEE_FSUID
```

## Input Format

### JSON

```json
[
  {
    "company": "Acme Corp",
    "email": "contact@acme.com",
    "phone": "+44 123 456 7890",
    "country": "GB",
    "source_id": "optional-external-id"
  }
]
```

### CSV

```
company,email,phone,country,source_id
Acme Corp,contact@acme.com,+44 123 456 7890,GB,optional-external-id
```

### Fields

| Field | Required | Description |
|-------|----------|-------------|
| `company` | Yes | Company name |
| `email` | No | Email address |
| `phone` | No | Phone number (any format, cleaned automatically) |
| `country` | No | ISO 2-letter code (GB, DE, CN, etc.) for region/pool routing |
| `source_id` | No | External reference ID for logging |

## Configuration

Set environment variables:

```bash
export CRM_APP_ID="FSAID_xxx"
export CRM_APP_SECRET="xxx"
export CRM_PERMANENT_CODE="xxx"
export CRM_USER_MOBILE="19957895939"  # Optional, for user ID lookup
```

## Behavior

- **Duplicates**: Skip with warning, continue with remaining leads
- **Output**: Stdout only - progress and summary printed to terminal
- **Region routing**: Automatic based on country code
  - Europe (GB, DE, FR, etc.) → 欧洲线索公海池
  - Asia (CN, JP, KR, etc.) → 亚洲线索公海池

### Lead Pools

| Pool | ID | Countries |
|------|-----|-----------|
| 欧洲线索公海池 | `643d87b17be47e0a000190a715` | GB, DE, FR, IT, ES, NL, etc. |
| 亚洲线索公海池 | `643d87cda34e0a0001336093` | CN, JP, KR, TH, VN, etc. |
| 日本线索池 | `6464a6451a3c2c0001c12369` | JP (special routing) |

Use `--pool` to override automatic routing.

### Owner Assignment

The `--owner` or `--assign` flag accepts an FSUID (e.g., `FSUID_C3F0FA243B2B385385D570C8968C8AB3`).

**Note**: The API requires FSUID format. Employee IDs like `empid-1079` are not directly compatible - you need to find the corresponding FSUID from the CRM user management interface.

## Development

```bash
# Run tests
uv run python -m unittest discover tests/

# Run CLI
uv run crm sync --help
```

## License

MIT