mrktplaats-cli/TOOLS.md

# mrktplaats CLI — Technical Reference

## Installation & Setup

The CLI is in `/home/joren/dev/marktplaatsApi/mrktplaats-cli/`. Run commands from there or add to PATH.

## Authentication

```bash
# Login (starts 2FA flow)
./mrktplaats login --email EMAIL --password PASS

# If 2FA triggered, re-run with code
./mrktplaats login --email EMAIL --password PASS --code 123456

# Token location: ~/.config/mrktplaats/token
# Or set env var: MRKTPLAATS_TOKEN=...
```

## Commands

### Search Listings

```bash
./mrktplaats search --query "SEARCH_TERMS" [--category ID] [--size N] [--sort SORT]
```

| Flag | Values | Description |
|------|--------|-------------|
| `--query` | string | Search terms (required) |
| `--category` | ID | Category ID (optional) |
| `--size` | 1-100 | Number of results (default 20) |
| `--sort` | PRICE_ASC, PRICE_DESC, DATE_DESC | Sort order |

**Example:**
```bash
./mrktplaats search --query "Samsung Galaxy S22" --size 30 --sort PRICE_ASC
```

**Output:**
```json
{
  "listings": [
    {
      "urn": "m2375361894",
      "title": "Samsung Galaxy s22, 128g, 8g ram",
      "price_cents": 16000,
      "price_label": "€ 160,00",
      "price_type": "FIXED",
      "city": "Halle",
      "seller_name": "Tom"
    }
  ],
  "page": 1,
  "size": 30,
  "total": 403
}
```

---

### Get Listing Details

```bash
./mrktplaats listing --urn URN
```

**Output:**
```json
{
  "adCore": {
    "urn": "m2375361894",
    "title": "Samsung Galaxy s22, 128g, 8g ram",
    "description": "Is ongeveer een tweetal jaar gebruikt...",
    "price": {"priceAmount": 16000, "priceType": "FIXED"},
    "pictures": [...],
    "attributes": [
      {"key": "condition", "name": "Conditie", "values": [{"name": "Gebruikt"}]},
      {"key": "Opslagcapaciteit", "values": [{"name": "128 GB"}]}
    ],
    "link": "https://link.marktplaats.nl/m2375361894"
  },
  "sellerInformation": {
    "id": 34593982,
    "name": "Tom",
    "type": "CONSUMER",
    "activeSince": {"label": "8½ jaar"},
    "kycState": {"twoFactorVerificationState": "VERIFIED"}
  }
}
```

---

### Seller Reviews

```bash
./mrktplaats reviews --seller ID
# or from a listing
./mrktplaats reviews --urn URN
```

**Output:**
```json
{
  "reviews": [
    {
      "id": 125540237,
      "score": 5,
      "reviewer_name": "Kakoje",
      "subject": "Monitoren",
      "direction": "S2B",
      "date": "2024-06-26",
      "details": [{"category": "general", "score": 5, "traits": ["+Reageert snel", "+Vriendelijk"]}]
    }
  ],
  "seller_id": 34593982,
  "summary": {"average_score": 4.5, "count": 14}
}
```

---

### Conversations

```bash
./mrktplaats conversations --limit N
```

**Output:**
```json
{
  "conversations": [
    {
      "id": "5b6x:2p0q1r6:2p16t6r09",
      "item_urn": "m2366146019",
      "title": "Ebike FIETSBATRERIJ",
      "other_party": "linde.de",
      "other_party_id": 32557926,
      "unread": 1,
      "latest_message": "Wilrijk"
    }
  ],
  "total": 3,
  "unread": 1
}
```

---

### Messages

```bash
./mrktplaats messages --conv CONV_ID --limit N
```

**Output:**
```json
{
  "messages": [
    {
      "id": "7ae205d4-18c6-11f1-977b-25f14ffc6a81",
      "sender_id": 32557926,
      "text": "Wilrijk",
      "date": "2026-03-05T19:06:56.942Z",
      "type": "chat"
    }
  ],
  "total": 6
}
```

---

### Send Message (New Conversation)

```bash
./mrktplaats send --urn URN --text "MESSAGE"
```

**Output:**
```json
{
  "item_urn": "m2372861012",
  "seller_id": "57506580",
  "seller_name": "Mattia",
  "status": "sent"
}
```

---

### Reply to Conversation

```bash
./mrktplaats reply --conv CONV_ID --text "MESSAGE"
```

**Output:**
```json
{
  "conversation_id": "1cgx:5qgvx3h:2p1gxt95d",
  "message_id": "448b34fe-1806-11f1-9484-e9655a940eaf",
  "status": "sent"
}
```

---

### Place Bid

```bash
./mrktplaats bid --urn URN --amount EUROS [--message TEXT]
```

---

### Other Commands

```bash
# Seller's other listings
./mrktplaats seller-listings --seller ID

# Similar listings
./mrktplaats similar --urn URN

# Search autocomplete
./mrktplaats suggest --prefix TEXT

# Favorites
./mrktplaats favorites
./mrktplaats add-favorite --urn URN
./mrktplaats remove-favorite --urn URN

# User info
./mrktplaats me
./mrktplaats notifications
./mrktplaats my-ads

# Sell item
./mrktplaats recognize --file PATH
./mrktplaats price-suggestion --category ID --title TEXT
./mrktplaats create-ad --category ID --title T --description D --price EUROS
```

## Error Messages

| Error | Cause | Fix |
|-------|-------|-----|
| `401 Unauthorized` | Token expired/missing | Run login |
| `403 VERIFICATION_NOT_FOUND` | Too many wrong 2FA codes | Wait hours |
| `403 VERIFICATION_REQUESTS_BLOCKED` | 2FA blocked | Wait hours |
| `dial tcp: lookup app.marktplaats.nl: server misbehaving` | DNS/network | Retry later |
| `No results found` | Search terms not matching | Try broader terms |

## Common Patterns

### Finding Deals
1. Search: `./mrktplaats search --query "DDR4 sodimm" --size 50 --sort PRICE_ASC`
2. Parse results (max 100)
3. Fetch details for promising URNs: `./mrktplaats listing --urn URN`
4. Calculate price-per-GB for memory
5. Check seller reviews

### Checking Messages
1. `./mrktplaats conversations --limit 10` → shows unread count
2. If unread > 0, fetch: `./mrktplaats messages --conv CONV_ID --limit 10`

### Contacting Seller
1. Use `./mrktplaats send --urn URN --text "..."` for new listings
2. Use `./mrktplaats reply --conv CONV_ID --text "..."` for existing threads

### Sending to Discord
```bash
curl -X POST "https://discord.com/api/webhooks/1478131681033588859/xjPSaVsePMWrmXI1jGtvnvAaQ2L4jeBVZt9KzXY2LAH3KmHATsLIkqsgjzcMa31oYcnY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Samsung S22 - €160: https://link.marktplaats.nl/m2375361894"}'
```

## IDENTITY.md Reminder

When writing messages to sellers:
- Use casual Dutch (Flemish)
- Keep it short (1-2 sentences)
- NO emojis, NO em-dashes, NO IDs/URNs
- Sign off with "Groeten, Jonathan"

**Example:**
```
Hoi, is die Samsung S22 nog beschikbaar? Groeten, Jonathan
```