Initial Marktplaats CLI scaffold
Create mrktplaats-cli from twdehands-cli, updating module/import names, command branding, and token paths while preserving command behavior and payload formats.
This commit is contained in:
291
TOOLS.md
Normal file
291
TOOLS.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user