scrapebadger-cli 0.14.0__tar.gz → 0.16.0__tar.gz

{scrapebadger_cli-0.14.0 → scrapebadger_cli-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scrapebadger-cli
-Version: 0.14.0
+Version: 0.16.0
 Summary: ScrapeBadger CLI — Twitter, Vinted, Google, and Web Scraping from the command line
 Author: ScrapeBadger Team
 License: MIT
@@ -58,3 +58,16 @@ scrapebadger vinted search "nike" --sizes 206 --materials 43
 The catalog lists 76 public read operations with parameter types and examples.
 Each mobile read costs 1 credit; discovery is free. Sold comparables are a
 Vinted-selected sample, not a complete sales history or guaranteed final sale prices.
+
+### Vinted image search
+
+```bash
+scrapebadger vinted search-by-image --image photo.jpg --market nl --price-to 50
+scrapebadger vinted search-by-image --image-url https://example.com/photo.webp --brand-ids 53
+```
+
+Provide exactly one of `--image`, `--image-url` or `--image-base64`. JPEG, PNG and
+WebP up to 5 MiB are supported. Returns active listings in visual ranking order;
+10 credits per successful request. Filter with `--catalog-ids`, `--brand-ids`,
+`--status-ids`, `--color-ids`, `--size-ids`, `--material-ids` and price bounds.
+Resend the same image and `--time` from pagination when requesting `--page 2`.

{scrapebadger_cli-0.14.0 → scrapebadger_cli-0.16.0}/README.md

@@ -36,3 +36,16 @@ scrapebadger vinted search "nike" --sizes 206 --materials 43
 The catalog lists 76 public read operations with parameter types and examples.
 Each mobile read costs 1 credit; discovery is free. Sold comparables are a
 Vinted-selected sample, not a complete sales history or guaranteed final sale prices.
+
+### Vinted image search
+
+```bash
+scrapebadger vinted search-by-image --image photo.jpg --market nl --price-to 50
+scrapebadger vinted search-by-image --image-url https://example.com/photo.webp --brand-ids 53
+```
+
+Provide exactly one of `--image`, `--image-url` or `--image-base64`. JPEG, PNG and
+WebP up to 5 MiB are supported. Returns active listings in visual ranking order;
+10 credits per successful request. Filter with `--catalog-ids`, `--brand-ids`,
+`--status-ids`, `--color-ids`, `--size-ids`, `--material-ids` and price bounds.
+Resend the same image and `--time` from pagination when requesting `--page 2`.

{scrapebadger_cli-0.14.0 → scrapebadger_cli-0.16.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "scrapebadger-cli"
-version = "0.14.0"
+version = "0.16.0"
 description = "ScrapeBadger CLI — Twitter, Vinted, Google, and Web Scraping from the command line"
 requires-python = ">=3.10"
 license = {text = "MIT"}

{scrapebadger_cli-0.14.0 → scrapebadger_cli-0.16.0}/src/scrapebadger_cli/commands/depop.py

@@ -32,7 +32,7 @@ def search(
     sort: str | None = typer.Option(
         None,
         "--sort",
-        help="relevance, newest, priceAscending, priceDescending, popularity",
+        help="relevance, priceAscending, priceDescending",
     ),
     fmt: str = FMT,
     fields: str | None = FIELDS,

{scrapebadger_cli-0.14.0 → scrapebadger_cli-0.16.0}/src/scrapebadger_cli/commands/google.py

@@ -881,7 +881,7 @@ def finance(
     fmt: str = FMT,
     fields: str | None = FIELDS,
 ) -> None:
-    """Google Finance quote — via mKsvE RPC."""
+    """Google Finance quote."""
     data = api_get("/v1/google/finance/quote", {"q": q, "hl": hl, "gl": gl})
     render(data, fmt, fields)
 

{scrapebadger_cli-0.14.0 → scrapebadger_cli-0.16.0}/src/scrapebadger_cli/commands/tiktok.py

@@ -31,10 +31,16 @@ def user_videos(
     count: int = COUNT,
     fmt: str = FMT,
     fields: str | None = FIELDS,
+    cursor: str | None = typer.Option(
+        None, "--cursor", help="Continuation cursor from the previous page"
+    ),
 ) -> None:
     """Get a user's posted videos."""
     render(
-        api_get(f"/v1/tiktok/users/{username}/videos", {"region": region, "count": count}),
+        api_get(
+            f"/v1/tiktok/users/{username}/videos",
+            {**({"cursor": cursor} if cursor else {}), "region": region, "count": count},
+        ),
         fmt,
         fields,
     )
@@ -47,10 +53,16 @@ def followers(
     count: int = COUNT,
     fmt: str = FMT,
     fields: str | None = FIELDS,
+    cursor: str | None = typer.Option(
+        None, "--cursor", help="Continuation cursor from the previous page"
+    ),
 ) -> None:
     """Get a user's followers (best-effort)."""
     render(
-        api_get(f"/v1/tiktok/users/{username}/followers", {"region": region, "count": count}),
+        api_get(
+            f"/v1/tiktok/users/{username}/followers",
+            {**({"cursor": cursor} if cursor else {}), "region": region, "count": count},
+        ),
         fmt,
         fields,
     )
@@ -63,10 +75,16 @@ def following(
     count: int = COUNT,
     fmt: str = FMT,
     fields: str | None = FIELDS,
+    cursor: str | None = typer.Option(
+        None, "--cursor", help="Continuation cursor from the previous page"
+    ),
 ) -> None:
     """Get accounts a user follows (best-effort)."""
     render(
-        api_get(f"/v1/tiktok/users/{username}/following", {"region": region, "count": count}),
+        api_get(
+            f"/v1/tiktok/users/{username}/following",
+            {**({"cursor": cursor} if cursor else {}), "region": region, "count": count},
+        ),
         fmt,
         fields,
     )
@@ -98,12 +116,20 @@ def comments(
     username: str | None = typer.Option(None, "--username", "-u"),
     fmt: str = FMT,
     fields: str | None = FIELDS,
+    cursor: str | None = typer.Option(
+        None, "--cursor", help="Continuation cursor from the previous page"
+    ),
 ) -> None:
     """Get top-level comments on a video."""
     render(
         api_get(
             f"/v1/tiktok/videos/{video_id}/comments",
-            {"region": region, "count": count, "username": username},
+            {
+                **({"cursor": cursor} if cursor else {}),
+                "region": region,
+                "count": count,
+                "username": username,
+            },
         ),
         fmt,
         fields,
@@ -118,12 +144,20 @@ def related(
     username: str | None = typer.Option(None, "--username", "-u"),
     fmt: str = FMT,
     fields: str | None = FIELDS,
+    cursor: str | None = typer.Option(
+        None, "--cursor", help="Continuation cursor from the previous page"
+    ),
 ) -> None:
     """Get related videos for a video."""
     render(
         api_get(
             f"/v1/tiktok/videos/{video_id}/related",
-            {"region": region, "count": count, "username": username},
+            {
+                **({"cursor": cursor} if cursor else {}),
+                "region": region,
+                "count": count,
+                "username": username,
+            },
         ),
         fmt,
         fields,
@@ -177,10 +211,16 @@ def hashtag_videos(
     count: int = COUNT,
     fmt: str = FMT,
     fields: str | None = FIELDS,
+    cursor: str | None = typer.Option(
+        None, "--cursor", help="Continuation cursor from the previous page"
+    ),
 ) -> None:
     """Get videos tagged with a hashtag."""
     render(
-        api_get(f"/v1/tiktok/hashtags/{name}/videos", {"region": region, "count": count}),
+        api_get(
+            f"/v1/tiktok/hashtags/{name}/videos",
+            {**({"cursor": cursor} if cursor else {}), "region": region, "count": count},
+        ),
         fmt,
         fields,
     )
@@ -204,10 +244,16 @@ def music_videos(
     count: int = COUNT,
     fmt: str = FMT,
     fields: str | None = FIELDS,
+    cursor: str | None = typer.Option(
+        None, "--cursor", help="Continuation cursor from the previous page"
+    ),
 ) -> None:
     """Get videos using a sound."""
     render(
-        api_get(f"/v1/tiktok/music/{music_id}/videos", {"region": region, "count": count}),
+        api_get(
+            f"/v1/tiktok/music/{music_id}/videos",
+            {**({"cursor": cursor} if cursor else {}), "region": region, "count": count},
+        ),
         fmt,
         fields,
     )
@@ -221,24 +267,41 @@ def search(
     count: int = typer.Option(20, "--count", "-c"),
     fmt: str = FMT,
     fields: str | None = FIELDS,
+    cursor: str | None = typer.Option(
+        None, "--cursor", help="Continuation cursor from the previous page"
+    ),
 ) -> None:
     """Search TikTok (general/users/videos/hashtags)."""
     path = "/v1/tiktok/search" if kind == "general" else f"/v1/tiktok/search/{kind}"
-    render(api_get(path, {"query": query, "region": region, "count": count}), fmt, fields)
+    render(
+        api_get(
+            path,
+            {
+                "query": query,
+                "region": region,
+                "count": count,
+                **({"cursor": cursor} if cursor else {}),
+            },
+        ),
+        fmt,
+        fields,
+    )
 
 
 @app.command()
 def trending(
     kind: str = typer.Option("videos", "--kind", "-k", help="videos | hashtags | songs"),
     region: str = REGION,
-    period: int = typer.Option(7, "--period", help="Trend window in days (7/30/120)"),
+    period: int | None = typer.Option(
+        None, "--period", help="Historical windows unavailable; omit"
+    ),
     count: int = typer.Option(20, "--count", "-c"),
     fmt: str = FMT,
     fields: str | None = FIELDS,
 ) -> None:
     """Get trending data (videos/hashtags/songs)."""
     params = {"region": region, "count": count}
-    if kind in ("hashtags", "songs"):
+    if kind in ("hashtags", "songs") and period is not None:
         params["period"] = period
     render(api_get(f"/v1/tiktok/trending/{kind}", params), fmt, fields)
 
@@ -305,7 +368,12 @@ def ad(
     render(api_get(f"/v1/tiktok/ads/{ad_id}", {"region": region}), fmt, fields)
 
 
-SHOP_REGION = typer.Option("US", "--region", "-r", help="Market: US, GB, ID")
+SHOP_REGION = typer.Option(
+    "US",
+    "--region",
+    "-r",
+    help="Market: US, GB, ID, JP, MX, SG, MY, PH, TH, VN (coverage varies by endpoint)",
+)
 
 
 @app.command(name="shop-categories")
@@ -324,17 +392,103 @@ def shop_categories(
     render(api_get(path, {"region": region}), fmt, fields)
 
 
+@app.command(name="shop-category-products")
+def shop_category_products(
+    category_id: str = typer.Argument(..., help="Numeric category id"),
+    region: str = SHOP_REGION,
+    count: int = typer.Option(20, "--count", "-c", min=1, max=40),
+    exclude_product_ids: list[str] = typer.Option(
+        [], "--exclude-product-id", help="Repeat for every next_exclude_product_ids value"
+    ),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Page through a category's product recommendations."""
+    render(
+        api_get(
+            f"/v1/tiktok/shop/categories/{category_id}/products",
+            {
+                "region": region,
+                "count": count,
+                "exclude_product_ids": exclude_product_ids,
+            },
+        ),
+        fmt,
+        fields,
+    )
+
+
+@app.command(name="shop-ranking")
+def shop_ranking(
+    rank_id: str = typer.Argument(..., help="Native category/theme ranking id"),
+    region: str = SHOP_REGION,
+    rank_type: int = typer.Option(1, "--rank-type", min=1, max=3),
+    cursor: int = typer.Option(0, "--cursor", min=0),
+    count: int = typer.Option(20, "--count", "-c", min=1, max=20),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Native Shop ranking; ID/PH/TH/VN require regional guest appliance profiles."""
+    render(
+        api_get(
+            f"/v1/tiktok/shop/rankings/{rank_id}",
+            {
+                "region": region,
+                "rank_type": rank_type,
+                "cursor": cursor,
+                "count": count,
+            },
+        ),
+        fmt,
+        fields,
+    )
+
+
+@app.command(name="shop-bestsellers")
+def shop_bestsellers(
+    region: str = SHOP_REGION,
+    category_id: str | None = typer.Option(None, "--category-id", help="Limit to one category"),
+    pages: int = typer.Option(2, "--pages", min=1, max=4),
+    limit: int = typer.Option(20, "--limit", "-l", min=1, max=100),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Sales-ranked best-selling products; works for every market (incl. SG/MY/JP)."""
+    render(
+        api_get(
+            "/v1/tiktok/shop/bestsellers",
+            {
+                "region": region,
+                "category_id": category_id,
+                "pages": pages,
+                "limit": limit,
+            },
+        ),
+        fmt,
+        fields,
+    )
+
+
 @app.command(name="shop-search")
 def shop_search(
     query: str = typer.Argument(..., help="Keyword, e.g. 'wireless earbuds'"),
     region: str = SHOP_REGION,
+    page_token: str | None = typer.Option(None, "--page-token", help="Native ID/JP continuation"),
     offset: int = typer.Option(0, "--offset", help="Pass back pagination.next_offset (US)"),
     fmt: str = FMT,
     fields: str | None = FIELDS,
 ) -> None:
     """Search TikTok Shop products by keyword (30 per page, offset pagination in the US)."""
     render(
-        api_get("/v1/tiktok/shop/search", {"q": query, "region": region, "offset": offset}),
+        api_get(
+            "/v1/tiktok/shop/search",
+            {
+                "q": query,
+                "region": region,
+                "offset": offset,
+                "page_token": page_token,
+            },
+        ),
         fmt,
         fields,
     )
@@ -384,7 +538,7 @@ def shop_reviews(
     fmt: str = FMT,
     fields: str | None = FIELDS,
 ) -> None:
-    """Paginated TikTok Shop product reviews with the rating breakdown (US)."""
+    """Paginated product reviews (US; Tokopedia source for ID)."""
     params: dict = {
         "region": region,
         "page": page,
@@ -405,3 +559,100 @@ def regions(
 ) -> None:
     """List supported TikTok content regions."""
     render(api_get("/v1/tiktok/regions"), fmt, fields)
+
+
+@app.command(name="shop-mall")
+def shop_mall(
+    region: str = SHOP_REGION,
+    tab_id: int = typer.Option(0, "--tab-id", min=0),
+    page_token: str | None = typer.Option(None, "--page-token"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Regional mall navigation and feed; pass back the 15-minute page token."""
+    render(
+        api_get(
+            "/v1/tiktok/shop/mall",
+            {
+                "region": region,
+                "tab_id": tab_id,
+                "page_token": page_token,
+            },
+        ),
+        fmt,
+        fields,
+    )
+
+
+@app.command()
+def liked(
+    username: str = typer.Argument(..., help="TikTok handle"),
+    region: str = REGION,
+    count: int = COUNT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+    cursor: str | None = typer.Option(
+        None, "--cursor", help="Continuation cursor from the previous page"
+    ),
+) -> None:
+    """Get accounts a user follows (best-effort)."""
+    render(
+        api_get(
+            f"/v1/tiktok/users/{username}/liked",
+            {**({"cursor": cursor} if cursor else {}), "region": region, "count": count},
+        ),
+        fmt,
+        fields,
+    )
+
+
+@app.command()
+def reposts(
+    username: str = typer.Argument(..., help="TikTok handle"),
+    region: str = REGION,
+    count: int = COUNT,
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+    cursor: str | None = typer.Option(
+        None, "--cursor", help="Continuation cursor from the previous page"
+    ),
+) -> None:
+    """Get accounts a user follows (best-effort)."""
+    render(
+        api_get(
+            f"/v1/tiktok/users/{username}/reposts",
+            {**({"cursor": cursor} if cursor else {}), "region": region, "count": count},
+        ),
+        fmt,
+        fields,
+    )
+
+
+@app.command()
+def replies(
+    comment_id: str = typer.Argument(..., help="Comment id"),
+    video_id: str = typer.Argument(..., help="Numeric video id"),
+    region: str = REGION,
+    count: int = typer.Option(20, "--count", "-c"),
+    username: str | None = typer.Option(None, "--username", "-u"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+    cursor: str | None = typer.Option(
+        None, "--cursor", help="Continuation cursor from the previous page"
+    ),
+) -> None:
+    """Get replies to a public comment."""
+    render(
+        api_get(
+            f"/v1/tiktok/comments/{comment_id}/replies",
+            {
+                **({"cursor": cursor} if cursor else {}),
+                "region": region,
+                "video_id": video_id,
+                "count": count,
+                "username": username,
+            },
+        ),
+        fmt,
+        fields,
+    )

{scrapebadger_cli-0.14.0 → scrapebadger_cli-0.16.0}/src/scrapebadger_cli/commands/vinted.py

@@ -1,7 +1,9 @@
 """Vinted marketplace commands."""
 
+import base64
 import json
 import re
+from pathlib import Path
 
 import typer
 
@@ -157,3 +159,66 @@ def mobile_read(
         fmt,
         fields,
     )
+
+
+@app.command(name="search-by-image")
+def search_by_image(
+    image: Path | None = typer.Option(
+        None,
+        "--image",
+        "-i",
+        exists=True,
+        dir_okay=False,
+        help="Local JPEG, PNG or WebP, at most 5 MiB",
+    ),
+    image_url: str | None = typer.Option(None, "--image-url", help="Public image URL"),
+    image_base64: str | None = typer.Option(
+        None, "--image-base64", help="Base64 image or data URL"
+    ),
+    market: str = MARKET,
+    page: int = typer.Option(1, "--page"),
+    per_page: int = typer.Option(20, "--per-page"),
+    price_from: float | None = typer.Option(None, "--price-from"),
+    price_to: float | None = typer.Option(None, "--price-to"),
+    brand_ids: str | None = typer.Option(None, "--brand-ids"),
+    catalog_ids: str | None = typer.Option(None, "--catalog-ids"),
+    color_ids: str | None = typer.Option(None, "--color-ids"),
+    size_ids: str | None = typer.Option(None, "--size-ids"),
+    material_ids: str | None = typer.Option(None, "--material-ids"),
+    status_ids: str | None = typer.Option(None, "--status-ids"),
+    time: int | None = typer.Option(None, "--time"),
+    search_session_id: str | None = typer.Option(None, "--search-session-id"),
+    fmt: str = FMT,
+    fields: str | None = FIELDS,
+) -> None:
+    """Find active Vinted listings from a photo. 10 credits per successful search."""
+    if sum(bool(x) for x in (image, image_url, image_base64)) != 1:
+        raise typer.BadParameter("Pass exactly one of --image, --image-url or --image-base64")
+    if image:
+        with image.open("rb") as file:
+            raw = file.read(5 * 1024 * 1024 + 1)
+        if not raw or len(raw) > 5 * 1024 * 1024:
+            raise typer.BadParameter("Image must be nonempty and at most 5 MiB")
+        image_base64 = base64.b64encode(raw).decode("ascii")
+    body = {
+        "image_url": image_url,
+        "image_base64": image_base64,
+        "market": market,
+        "page": page,
+        "per_page": per_page,
+        "price_from": price_from,
+        "price_to": price_to,
+        "brand_ids": brand_ids,
+        "catalog_ids": catalog_ids,
+        "color_ids": color_ids,
+        "size_ids": size_ids,
+        "material_ids": material_ids,
+        "status_ids": status_ids,
+        "time": time,
+        "search_session_id": search_session_id,
+    }
+    render(
+        api_post("/v1/vinted/search_by_image", {k: v for k, v in body.items() if v is not None}),
+        fmt,
+        fields,
+    )

scrapebadger_cli-0.16.0/tests/test_tiktok_pagination.py

@@ -0,0 +1,36 @@
+from unittest.mock import patch
+
+import pytest
+
+CliRunner = pytest.importorskip("typer.testing").CliRunner
+app = pytest.importorskip(
+    "scrapebadger_cli.commands.tiktok", reason="CLI is tested with its own installed package"
+).app
+
+
+@pytest.mark.parametrize(
+    "args,path",
+    [
+        (["followers", "tiktok"], "/users/tiktok/followers"),
+        (["following", "tiktok"], "/users/tiktok/following"),
+        (["liked", "tiktok"], "/users/tiktok/liked"),
+        (["reposts", "tiktok"], "/users/tiktok/reposts"),
+        (["replies", "123", "456"], "/comments/123/replies"),
+        (["search", "news", "--kind", "users"], "/search/users"),
+    ],
+)
+def test_continuations_are_forwarded(args, path):
+    with patch("scrapebadger_cli.commands.tiktok.api_get", return_value={}) as call:
+        result = CliRunner().invoke(app, args + ["--cursor", "tw1_test"])
+        assert result.exit_code == 0, result.output
+        assert call.call_args.args[0] == "/v1/tiktok" + path
+        assert call.call_args.args[1]["cursor"] == "tw1_test"
+        if args[0] == "replies":
+            assert call.call_args.args[1]["video_id"] == "456"
+
+
+def test_trends_do_not_invent_a_historical_window():
+    with patch("scrapebadger_cli.commands.tiktok.api_get", return_value={}) as call:
+        result = CliRunner().invoke(app, ["trending", "--kind", "songs"])
+        assert result.exit_code == 0, result.output
+        assert "period" not in call.call_args.args[1]

scrapebadger_cli-0.16.0/tests/test_vinted_image_search.py

@@ -0,0 +1,27 @@
+import base64
+from unittest.mock import patch
+
+import pytest
+
+CliRunner = pytest.importorskip("typer.testing").CliRunner
+app = pytest.importorskip("scrapebadger_cli.commands.vinted").app
+
+
+def test_local_image_is_encoded_and_filters_forwarded(tmp_path):
+    image = tmp_path / "shoe.jpg"
+    image.write_bytes(b"\xff\xd8\xfftest")
+    with patch("scrapebadger_cli.commands.vinted.api_post", return_value={"items": []}) as call:
+        result = CliRunner().invoke(
+            app, ["search-by-image", "--image", str(image), "--market", "nl", "--brand-ids", "53"]
+        )
+        assert result.exit_code == 0, result.output
+        path, body = call.call_args.args
+        assert path == "/v1/vinted/search_by_image"
+        assert base64.b64decode(body["image_base64"]) == image.read_bytes()
+        assert body["market"] == "nl" and body["brand_ids"] == "53"
+        result = CliRunner().invoke(
+            app,
+            ["search-by-image", "--image", str(image), "--image-url", "https://example.com/a.jpg"],
+        )
+        assert result.exit_code != 0
+        assert call.call_count == 1

{scrapebadger_cli-0.14.0 → scrapebadger_cli-0.16.0}/uv.lock

@@ -228,7 +228,7 @@ wheels = [
 
 [[package]]
 name = "scrapebadger-cli"
-version = "0.14.0"
+version = "0.15.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },