@vibelyster/depop-cli 0.1.0

package/README.md

@@ -0,0 +1,161 @@
+# @vibelyster/depop-cli
+
+Proof-of-concept CLI for Depop's internal API. Uses [`impit`](https://github.com/apify/impit) to mimic Chrome TLS fingerprints and bypass Cloudflare bot detection.
+
+Reverse-engineered from browser DevTools network traffic and verified against live API (2026-03-27). See [marketplace API research](../../docs/marketplace-api-research.md) for full technical details.
+
+---
+
+## Quick Start
+
+```bash
+# No install needed — run directly
+node tools/depop/cli.js --help
+
+# Or link globally
+cd tools/depop && npm link
+depop --help
+```
+
+---
+
+## Authentication
+
+Only the **bearer token** is required. User ID is auto-resolved from the API.
+
+```bash
+# Option 1: interactive login (saves to ~/.vibelyster/depop.json)
+depop login
+
+# Option 2: env var
+export DEPOP_ACCESS_TOKEN="your-access-token"
+
+# Option 3: per-command flag
+depop auth --access-token "..."
+```
+
+**To get your access token:**
+1. Log into depop.com in your browser
+2. Open DevTools → Application → Cookies → depop.com
+3. Copy the `access_token` cookie value
+
+> **Note:** Depop uses Cloudflare TLS fingerprinting (JA3/JA4) to block non-browser clients. This CLI uses `impit` (Rust-based Chrome TLS mimic) to bypass this — no real browser required.
+
+---
+
+## Commands
+
+```bash
+depop login                           # Save your access token
+depop auth                            # Check login status
+depop logout                          # Remove saved credentials
+depop listings                        # List your products
+depop listing <slug>                  # Get product details
+depop addresses                       # List shipping addresses
+depop upload <image-path>             # Upload a square image → {id, url}
+depop create <json-file>              # Create a draft listing
+depop drafts                          # List draft listings
+depop draft-update <id> <json-file>   # Update a draft
+depop draft-delete <id>               # Delete a draft
+depop edit <product-id> <json-file>   # Edit a live product in-place
+depop delete <product-id>             # Delete a live product
+```
+
+---
+
+## Listing Lifecycle
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                                                                  │
+│   1. Upload images       depop upload ./photo.jpg                │
+│      └─ Two-step: POST JSON → presigned S3 URL → PUT image      │
+│      └─ Returns {id, url}                                        │
+│      └─ Images MUST be square (Depop rejects non-square)         │
+│                                                                  │
+│   2. Create draft        depop create draft.json                 │
+│      └─ POST /api/v2/drafts/ (direct POST to products fails)    │
+│      └─ Returns {id} (UUID)                                      │
+│                                                                  │
+│   3. Manage drafts       depop drafts / draft-update / draft-del │
+│      └─ GET/PUT /api/v2/drafts/  DELETE /api/v1/drafts/         │
+│                                                                  │
+│   4. Publish             Open draft in browser and click Post    │
+│      └─ depop.com/sellinghub/drafts/edit/<draft-id>/             │
+│      └─ No API-only publish endpoint found yet                   │
+│                                                                  │
+│   5. Edit live listing   depop edit <id> updates.json            │
+│      └─ PUT /api/v2/products/<id>/                               │
+│                                                                  │
+│   6. Delete listing      depop delete <id>                       │
+│      └─ DELETE /api/v1/products/<id>/ (v1, not v2)               │
+│                                                                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Cloudflare TLS Bypass
+
+Depop's API (`webapi.depop.com`) is behind Cloudflare which fingerprints the TLS handshake (JA3/JA4) to distinguish browsers from automated clients. Standard Node.js `fetch()` and `curl` are blocked with 403 regardless of headers or cookies.
+
+**Solution:** [`impit`](https://github.com/apify/impit) — a Rust-based (`reqwest` + `napi-rs`) drop-in `fetch()` replacement that uses Chrome's cipher suites and TLS configuration. Zero npm dependencies, prebuilt native binaries, Apache-2.0 license.
+
+```
+Node.js fetch()  →  JA3: Node.js fingerprint  →  Cloudflare 403
+impit.fetch()    →  JA3: Chrome fingerprint    →  Cloudflare 200
+```
+
+---
+
+## Architecture
+
+```
+tools/depop/
+├── cli.js              CLI entry point (args, routing, output formatting)
+├── depop-api.js        API client (impit fetch, all endpoints)
+├── README.md           This file
+├── package.json        @vibelyster/depop-cli
+└── examples/           Payload templates (TODO)
+```
+
+### API Auth Flow
+
+```
+access_token cookie from browser
+        ↓
+  Authorization: Bearer <token>
+        ↓
+  webapi.depop.com/api/* (via impit for TLS fingerprint)
+        ↓
+  userId auto-resolved from /api/v1/addresses/
+```
+
+### API Endpoints
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/api/v1/sellerOnboarding/sellerStatus/` | Auth check + seller status |
+| GET | `/api/v1/addresses/` | Shipping addresses (also returns userId) |
+| GET | `/api/v3/shop/{userId}/products/` | User's listings |
+| GET | `/api/v1/product/by-slug/{slug}/user/` | Product detail by slug |
+| POST | `/api/v2/pictures/` | Presigned S3 URL for image upload |
+| POST | `/api/v2/drafts/` | Create draft listing |
+| GET | `/api/v2/drafts/` | List drafts |
+| PUT | `/api/v2/drafts/{id}/` | Update draft |
+| DELETE | `/api/v1/drafts/{id}/` | Delete draft (v1, not v2) |
+| PUT | `/api/v2/products/{id}/` | Edit live product |
+| DELETE | `/api/v1/products/{id}/` | Delete live product (v1, not v2) |
+
+---
+
+## Gotchas & Pitfalls
+
+| Gotcha | Detail |
+|--------|--------|
+| **Images must be square** | Depop rejects non-square images. Crop before uploading. |
+| **Product lookup uses slugs, not IDs** | `/api/v2/products/{slug}/` — get slugs from `depop listings` |
+| **Cloudflare blocks Node.js fetch** | Must use `impit` or equivalent Chrome TLS fingerprint tool |
+| **`depop-UserId` header is optional** | Bearer token alone identifies the user |
+| **userId needed in listings URL** | `/api/v3/shop/{userId}/products/` — auto-resolved and cached |
+| **esbuild can't bundle impit** | `impit` uses native binaries (napi-rs) — must be marked as external for bundling |

package/dist/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import{Impit as L}from"impit";var c="https://webapi.depop.com",v=new L({browser:"chrome"});function l(e){return{Accept:"*/*","Content-Type":"application/json",Authorization:`Bearer ${e}`,Origin:"https://www.depop.com",Referer:"https://www.depop.com/"}}async function d(e,t={}){let r=await v.fetch(e,t);if(!r.ok){let o=await r.text(),s;try{s=JSON.parse(o)}catch{s=o}throw new Error(`Depop API error ${r.status}: ${JSON.stringify(s)}`)}return r.status===204?null:r.json()}async function h(e){try{return{loggedIn:!0,user:await d(`${c}/api/v1/sellerOnboarding/sellerStatus/`,{headers:l(e)})}}catch(t){return{loggedIn:!1,error:t.message}}}async function y(e){let t=await d(`${c}/api/v1/addresses/`,{headers:l(e)});if(t?.length>0)return String(t[0].userId);throw new Error("Could not resolve userId \u2014 no addresses found on account")}async function $(e,t){let{readFile:r}=await import("node:fs/promises"),{extname:o}=await import("node:path"),s=o(e).slice(1).toLowerCase()||"jpg",n=s==="png"?"image/png":"image/jpeg",a=await d(`${c}/api/v2/pictures/`,{method:"POST",headers:l(t),body:JSON.stringify({type:"PRODUCT",extension:s})}),i=await r(e),u=await v.fetch(a.url,{method:"PUT",headers:{"Content-Type":n},body:i});if(!u.ok){let g=await u.text();throw new Error(`S3 upload failed ${u.status}: ${g}`)}return{id:a.id,url:a.url.split("?")[0]}}async function b(e,t){return d(`${c}/api/v2/drafts/`,{method:"POST",headers:l(t),body:JSON.stringify(e)})}async function I(e,t,r){return d(`${c}/api/v2/drafts/${e}/`,{method:"PUT",headers:l(r),body:JSON.stringify({id:e,...t})})}async function D(e){return d(`${c}/api/v2/drafts/`,{headers:l(e)})}async function S(e,t){return d(`${c}/api/v1/drafts/${e}/`,{method:"DELETE",headers:l(t)})}async function x(e,t,r){return d(`${c}/api/v2/products/${e}/`,{method:"PUT",headers:{...l(r),Referer:`https://www.depop.com/products/edit/${e}/`},body:JSON.stringify(t)})}async function T(e,t){return d(`${c}/api/v1/products/${e}/`,{method:"DELETE",headers:l(t)})}async function O(e,t){return d(`${c}/api/v1/product/by-slug/${e}/user/?camel_case=true`,{headers:l(t)})}async function C(e,t){return d(`${c}/api/v3/shop/${t}/products/?limit=200&force_fee_calculation=false`,{headers:l(e)})}async function E(e){return d(`${c}/api/v1/addresses/`,{headers:l(e)})}import{readFile as m,writeFile as _,mkdir as F,unlink as J}from"node:fs/promises";import{createInterface as R}from"node:readline";import{homedir as q}from"node:os";import{join as U}from"node:path";var w="https://www.depop.com",N=U(q(),".vibelyster"),f=U(N,"depop.json");function B(e){let t=R({input:process.stdin,output:process.stdout});return new Promise(r=>{t.question(e,o=>{t.close(),r(o.trim())})})}async function k(){try{let e=JSON.parse(await m(f,"utf-8"));if(e.accessToken)return e}catch{}return null}async function A(e){await F(N,{recursive:!0}),await _(f,JSON.stringify(e,null,2))}async function G(){try{await J(f)}catch{}}async function p(e){let t=K(e,"--access-token")||process.env.DEPOP_ACCESS_TOKEN;if(t)return t;let r=await k();if(r)return r.accessToken;console.error("Error: Not logged in. Run `depop login` or set DEPOP_ACCESS_TOKEN env var."),process.exit(1)}async function P(e){let t=await k();if(t?.userId)return t.userId;let r=await p(e),o=await y(r);return t&&(t.userId=o,await A(t)),o}function K(e,t){let r=e.indexOf(t);return r!==-1&&r+1<e.length?e[r+1]:null}function V(e){let t=[],r=["--access-token","--status"],o=0;for(;o<e.length;)r.includes(e[o])?o+=2:(t.push(e[o]),o++);return t}async function z(){let e=process.argv.slice(2),t=V(e),r=t[0];if(!r||r==="--help"||r==="-h"){console.log(`Depop CLI \u2014 VibeLyster
+
+Commands:
+  login                           Save your access token
+  auth                            Check login status
+  logout                          Remove saved credentials
+  listings                        List your products
+  listing <slug>                  Get product details
+  addresses                       List shipping addresses
+  upload <image-path>             Upload a square image, returns {id, url}
+  create <json-file>              Create a draft listing
+  drafts                          List draft listings
+  draft-update <id> <json-file>   Update a draft
+  draft-delete <id>               Delete a draft
+  edit <product-id> <json-file>   Edit a live product in-place
+  delete <product-id>             Delete a live product
+
+Auth:
+  Run "depop login" and paste your access_token from browser cookies.
+  Token saved to ~/.vibelyster/depop.json. userId auto-resolved.
+  Or set DEPOP_ACCESS_TOKEN env var.
+
+Note: Images must be square. Crop before uploading.
+`);return}try{switch(r){case"login":{console.log(`Depop Login
+`),console.log("To get your access token:"),console.log("  1. Log in to depop.com in your browser"),console.log("  2. Open DevTools \u2192 Application \u2192 Cookies \u2192 depop.com"),console.log(`  3. Copy the 'access_token' cookie value
+`);let o=await B("access_token: ");o||(console.error("access_token is required."),process.exit(1)),console.log(`
+Verifying...`);let s=await h(o);s.loggedIn||(console.error("Login failed:",s.error),process.exit(1)),console.log("Resolving user ID...");let n=await y(o);await A({accessToken:o,userId:n,savedAt:new Date().toISOString()}),console.log(`
+Logged in! canSell: ${s.user.canSell}`),console.log(`User ID: ${n}`),console.log(`Credentials saved to ${f}`);break}case"auth":{let o=await p(e),s=await h(o);if(s.loggedIn){let n=await P(e);console.log("Logged in. User ID:",n),console.log("canSell:",s.user.canSell),console.log("stripe:",s.user.stripe?.isConnected?"connected":"not connected");let a=await k();a?(console.log(`Credentials: ${f}`),a.savedAt&&console.log("Saved at:",a.savedAt)):console.log("Credentials: environment variables")}else console.error("Not logged in:",s.error),process.exit(1);break}case"logout":{await G(),console.log("Logged out. Credentials removed from",f);break}case"listings":{let o=await p(e),s=await P(e),n=await C(o,s),a=n.products||n.objects||[];if(!a.length){console.log("No listings found.");break}for(let i of a){let u=(i.description||"(no title)").split(`
+`)[0].slice(0,60),g=i.slug||i.id;console.log(`[${g}] ${u} \u2014 ${i.status}`),console.log(`  ${w}/products/${g}/`)}console.log(`
+Total: ${a.length} listings`);break}case"listing":{let o=t[1];o||(console.error("Usage: depop listing <slug>"),process.exit(1));let s=await p(e),n=await O(o,s);console.log(JSON.stringify(n,null,2));break}case"addresses":{let o=await p(e),s=await E(o);console.log(JSON.stringify(s,null,2));break}case"upload":{let o=t[1];o||(console.error("Usage: depop upload <image-path>"),console.error(`
+Image must be square. Depop will reject non-square images.`),process.exit(1));let s=await p(e),n=await $(o,s);console.log("Uploaded:"),console.log("  ID:",n.id),console.log("  URL:",n.url||n.imageUrl||JSON.stringify(n));break}case"create":{let o=t[1];o||(console.error("Usage: depop create <json-file>"),console.error(`
+See examples/draft.json for the payload format.`),process.exit(1));let s=await p(e),n=JSON.parse(await m(o,"utf-8"));console.log("Creating draft...");let a=await b(n,s);console.log("Draft created:",a.id),console.log(`
+To publish, open the draft in your browser:`),console.log(`  ${w}/sellinghub/drafts/edit/${a.id}/`),console.log(`
+Or update it via: depop draft-update <draft-id> <json-file>`);break}case"drafts":{let o=await p(e),n=(await D(o)).drafts||[];if(!n.length){console.log("No drafts found.");break}for(let a of n){let i=(a.description||"(no description)").split(`
+`)[0].slice(0,60),u=a.priceAmount?`$${a.priceAmount}`:"?",g=a.missingFields?.length?` [missing: ${a.missingFields.join(", ")}]`:" [ready]";console.log(`[${a.id}] ${i} \u2014 ${u}${g}`)}console.log(`
+Total: ${n.length} drafts`);break}case"draft-update":{let o=t[1],s=t[2];(!o||!s)&&(console.error("Usage: depop draft-update <draft-id> <json-file>"),process.exit(1));let n=await p(e),a=JSON.parse(await m(s,"utf-8"));await I(o,a,n),console.log("Draft updated:",o),console.log(`  ${w}/sellinghub/drafts/edit/${o}/`);break}case"draft-delete":{let o=t[1];o||(console.error("Usage: depop draft-delete <draft-id>"),process.exit(1));let s=await p(e);await S(o,s),console.log("Draft deleted:",o);break}case"edit":{let o=t[1],s=t[2];(!o||!s)&&(console.error("Usage: depop edit <product-id> <json-file>"),process.exit(1));let n=await p(e),a=JSON.parse(await m(s,"utf-8")),i=await x(o,a,n);console.log("Updated listing:"),console.log("  ID:",i.id),console.log("  URL:",`${w}/products/${i.slug||i.id}/`);break}case"delete":{let o=t[1];o||(console.error("Usage: depop delete <product-id>"),process.exit(1));let s=await p(e);await T(o,s),console.log(`Deleted product ${o}`);break}default:console.error(`Unknown command: ${r}`),console.error('Run "depop --help" for usage.'),process.exit(1)}}catch(o){console.error("Error:",o.message),process.exit(1)}}z();

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@vibelyster/depop-cli",
+  "version": "0.1.0",
+  "description": "CLI for Depop's internal API — list, create, edit, and manage product listings",
+  "type": "module",
+  "bin": {
+    "depop": "./dist/cli.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "esbuild cli.js --bundle --platform=node --format=esm --minify --external:impit --outfile=dist/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0"
+  },
+  "keywords": [
+    "depop",
+    "reselling",
+    "cli",
+    "listing"
+  ],
+  "license": "MIT",
+  "private": false,
+  "dependencies": {
+    "impit": "^0.13.0"
+  }
+}