# mrktplaats CLI — Skill Guide for AI Agents

## What You Can Do

You have a `mrktplaats` CLI tool to interact with marktplaats.nl (Belgian marketplace). Use it to:
- **Search** for items (phones, RAM, electronics, etc.)
- **Get details** on listings (price, condition, seller info)
- **Check seller ratings** before buying
- **Contact sellers** via marktplaats messaging
- **Check your messages** and conversations
- **Bid** on auction items
- **Post listings** to sell items

## When to Use This Tool

**Use it when the user asks:**
- "Are there any messages?" → Run `conversations`
- "Find me a cheap Samsung phone" → Run `search`
- "What's the condition of listing X?" → Run `listing --urn X`
- "Is seller Y trustworthy?" → Run `reviews --seller Y`
- "Message the seller about X" → Run `send` or `reply`
- "Send those links to Discord" → Use curl to webhook

**Don't use it for:**
- General web searches (use websearch)
- Code questions
- Anything unrelated to marktplaats.nl

## Quick Reference

```bash
# Search (most common)
./mrktplaats search --query "TERMS" --size 50 --sort PRICE_ASC

# Get details
./mrktplaats listing --urn URN

# Check seller
./mrktplaats reviews --seller ID

# Messages
./mrktplaats conversations --limit 10
./mrktplaats messages --conv CONV_ID --limit 10

# Contact seller (NEW listing)
./mrktplaats send --urn URN --text "MESSAGE"

# Contact seller (EXISTING conversation)
./mrktplaats reply --conv CONV_ID --text "MESSAGE"

# Discord webhook
curl -X POST WEBHOOK_URL -H "Content-Type: application/json" -d '{"content": "..."}'
```

## Writing Messages (IMPORTANT)

When contacting sellers, follow these rules:

**Language:** Casual Dutch (Flemish)
**Tone:** Friendly, brief, direct — like texting
**NO:** emojis, em-dashes (—), IDs/URNs, bullet points

**Structure:**
1. Greeting: "Hoi", "Hallo", "Beste [Naam]"
2. Body: 1-2 short sentences
3. Sign-off: "Groeten, Jonathan"

**Good examples:**
- "Hoi, is die Samsung S22 nog beschikbaar? Groeten, Jonathan"
- "Hoi, kan ik hem morgen ophalen? Groeten, Jonathan"

**Never do:**
- "Hi — I'm interested in your listing (URN: m123456). Please respond."
- Include profile IDs, prices in subject, or formal language

## Finding Deals

User's benchmarks:
- DDR4 RAM: ~€2-3/GB is good
- Used phones: depends on model/condition
- Always check: price, condition (in description), seller reviews

**Workflow:**
1. Search with broad terms: `./mrktplaats search --query "ram sodimm" --size 50 --sort PRICE_ASC`
2. Analyze top results
3. Get details: `./mrktplaats listing --urn URN`
4. Check seller: `./mrktplaats reviews --seller ID`
5. Present findings with links

**Links format:** `https://link.marktplaats.nl/{URN}`

## Discord Integration

**Webhook URL:**
```
https://discord.com/api/webhooks/1478131681033588859/xjPSaVsePMWrmXI1jGtvnvAaQ2L4jeBVZt9KzXY2LAH3KmHATsLIkqsgjzcMa31oYcnY
```

**Send message:**
```bash
curl -X POST WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -d '{"content": "Your message here"}'
```

## Errors & Solutions

| Error | Meaning | Solution |
|-------|---------|----------|
| `401 Unauthorized` | Token expired | Ask user to login |
| `403 VERIFICATION_NOT_FOUND` | 2FA blocked | Wait hours, then retry login |
| `dial tcp: lookup app.marktplaats.nl` | Network error | Retry later |
| No results returned | Bad search terms | Try different query |

## Login Flow

1. Ask user for email/password (or token)
2. Run: `./mrktplaats login --email EMAIL --password PASS`
3. If 2FA required → ask for SMS code
4. Re-run with code: `./mrktplaats login --email EMAIL --password PASS --code CODE`

## Complete Workflow Examples

### Example 1: User wants to find cheap DDR4 RAM
```
You: ./mrktplaats search --query "DDR4 sodimm" --size 50 --sort PRICE_ASC
→ Results: [...]

You: Analyze and calculate €/GB for top items

You: Present table with best deals
```

### Example 2: User wants to contact a seller
```
You: ./mrktplaats send --urn m1234567890 --text "Hoi, is die nog beschikbaar? Groeten, Jonathan"
→ {"status": "sent", ...}
```

### Example 3: User wants to check messages
```
You: ./mrktplaats conversations --limit 10
→ Shows conversations with unread count

You: ./mrktplaats messages --conv CONV_ID --limit 5
→ Shows message history
```

### Example 4: User wants to send deal links to Discord
```
You: curl -X POST WEBHOOK_URL -H "Content-Type: application/json" \
  -d '{"content": "DDR4 RAM deals:\n- 16GB - €50: https://link.marktplaats.nl/m123"}'
```