scrapelyserp 0.1.0__tar.gz

scrapelyserp-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+.data/
+.env*
+!.env.example
+
+# tls-client shared libraries: only the Linux build ships (native/tls-client-linux-amd64.so).
+# Point TLS_CLIENT_LIB_PATH at a Windows/macOS build for local live testing.
+native/*.dll
+native/*.dylib
+.live/
+
+# ForgeDeck local artifacts (run prompts, captured transcripts)
+.forgedeck/
+.forgememory/transcripts/
+
+# SDK / CLI / MCP package builds (packages/)
+packages/*/dist/
+packages/*/node_modules/
+__pycache__/
+*.egg-info/

scrapelyserp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scrapely
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scrapelyserp-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.5
+Name: scrapelyserp
+Version: 0.1.0
+Summary: Official Python SDK for the Scrapely API: product, price and stock data, structured search results, and watchlists that alert on change.
+Project-URL: Homepage, https://scrapelyserp.com
+Project-URL: Documentation, https://scrapelyserp.com/docs
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,price monitoring,product data,scrapely,scrapelyserp,sdk
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Description-Content-Type: text/markdown
+
+# scrapelyserp
+
+The official Python SDK for the [Scrapely API](https://scrapelyserp.com/docs): product, price and stock data from
+the retailers you sell on, structured search results, and watchlists that alert you when something changes.
+
+- Every API operation, generated from the API's OpenAPI document, grouped by resource.
+- Sync (`Scrapely`) and asyncio (`AsyncScrapely`) clients over [httpx](https://www.python-httpx.org/), the only
+  dependency. Python 3.9+.
+- Typed: request and response bodies are `TypedDict`s (`scrapelyserp.types`), methods have typed signatures.
+- Retries with backoff on 429 and 5xx, honouring `Retry-After`; idempotency keys generated for you.
+- Typed errors carrying the API's error `code` and `param`.
+
+```sh
+pip install scrapelyserp
+```
+
+## Quick start
+
+```python
+from scrapelyserp import Scrapely
+
+client = Scrapely()  # reads SCRAPELY_API_KEY
+
+account = client.account.get()
+print(account["balance"], "credits")
+
+products = client.products.fetch(platform="amazon", ids=["B0009KNLV6"], tier="lite")
+for item in products["results"]:
+    print(item["id"], item["status"], item.get("price"))
+
+# Structured endpoints are grouped by platform.
+results = client.structured.amazon.search(query="wireless earbuds")
+posts = client.structured.reddit.posts(subreddit="deals")
+```
+
+Async:
+
+```python
+import asyncio
+from scrapelyserp import AsyncScrapely
+
+async def main() -> None:
+    async with AsyncScrapely() as client:
+        account = await client.account.get()
+        async for item in client.watchlists.list_items_iter("wl_…"):
+            print(item["id"])
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+client = Scrapely(
+    api_key="sk_live_…",                   # default: SCRAPELY_API_KEY
+    base_url="https://scrapelyserp.com",   # default: SCRAPELY_BASE_URL, then this
+    max_retries=2,                         # 429, 5xx (except 501) and network errors
+    timeout=360.0,                         # seconds per attempt
+    headers={"x-my-header": "1"},
+    http_client=httpx.Client(...),         # your own httpx client (proxies, transports, tests)
+)
+```
+
+Use it as a context manager (`with Scrapely() as client:`) or call `client.close()`.
+
+## Resources
+
+`client.products`, `client.offers`, `client.platforms`, `client.structured` (one sub-resource per platform:
+`client.structured.ebay.image_search(...)`), `client.watchlists`, `client.destinations`,
+`client.webhook_endpoints`, `client.s3_export`, `client.account`, `client.meta`.
+
+Path parameters are positional; query parameters are keyword arguments; a body is a dict, keyword arguments, or both
+(keywords win):
+
+```python
+wl = client.watchlists.create(name="Consoles", platform="target", ids=["83887639"], every="15m")
+client.watchlists.update(wl["id"], status="paused")
+page = client.watchlists.list_items(wl["id"], state="active", limit=100)
+client.destinations.set_for_watchlist(wl["id"], destinations=[])
+
+# Any operation by its OpenAPI operationId:
+client.request("getWatchlist", path={"id": wl["id"]})
+```
+
+Every method also takes `options={"headers": ..., "timeout": ..., "max_retries": ...}`.
+
+## Pagination
+
+List operations with a `starting_after` cursor have an `..._iter` twin that walks every page:
+
+```python
+for item in client.watchlists.list_items_iter("wl_…", changed_since="2026-11-01T00:00:00Z"):
+    print(item["id"], item.get("snapshot"))
+```
+
+## Errors
+
+Every error is a `ScrapelyError`. API answers are an `APIError` subclass with `status`, `code` (stable: branch on
+it), `message`, `param`, `docs` and `request_id`:
+
+```python
+from scrapelyserp import APIError, InsufficientCreditsError
+
+try:
+    client.products.fetch(platform="walmart", ids=["5689919121"])
+except InsufficientCreditsError:
+    print("Top up first")
+except APIError as e:
+    print(e.code, e.param, e.request_id)
+```
+
+`BadRequestError` (400), `AuthenticationError` (401), `InsufficientCreditsError` (402), `PermissionDeniedError`
+(403), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429), `InternalServerError` (5xx),
+`ComingSoonError` (501: announced, not live yet; nothing charged), `APIConnectionError` / `APITimeoutError`
+(no answer).
+
+## Retries and idempotency
+
+429 and 5xx answers (except 501) and network errors are retried `max_retries` times, waiting for `Retry-After` when
+the API sends it, else 0.5 s, 1 s, 2 s... Operations that accept an `Idempotency-Key` (creating a watchlist) get one
+generated per call and reused across its retries; pass `idempotency_key=` to choose your own.
+
+## Development
+
+`types.py`, `_routes.py` and `_resources.py` are generated from the API's OpenAPI document by
+`scripts/sdk/generate.ts` in the Scrapely repository; do not edit them by hand.
+
+```sh
+python -m unittest discover -s tests   # offline, against httpx.MockTransport
+python -m build                        # sdist + wheel
+```
+
+## License
+
+MIT

scrapelyserp-0.1.0/README.md

@@ -0,0 +1,135 @@
+# scrapelyserp
+
+The official Python SDK for the [Scrapely API](https://scrapelyserp.com/docs): product, price and stock data from
+the retailers you sell on, structured search results, and watchlists that alert you when something changes.
+
+- Every API operation, generated from the API's OpenAPI document, grouped by resource.
+- Sync (`Scrapely`) and asyncio (`AsyncScrapely`) clients over [httpx](https://www.python-httpx.org/), the only
+  dependency. Python 3.9+.
+- Typed: request and response bodies are `TypedDict`s (`scrapelyserp.types`), methods have typed signatures.
+- Retries with backoff on 429 and 5xx, honouring `Retry-After`; idempotency keys generated for you.
+- Typed errors carrying the API's error `code` and `param`.
+
+```sh
+pip install scrapelyserp
+```
+
+## Quick start
+
+```python
+from scrapelyserp import Scrapely
+
+client = Scrapely()  # reads SCRAPELY_API_KEY
+
+account = client.account.get()
+print(account["balance"], "credits")
+
+products = client.products.fetch(platform="amazon", ids=["B0009KNLV6"], tier="lite")
+for item in products["results"]:
+    print(item["id"], item["status"], item.get("price"))
+
+# Structured endpoints are grouped by platform.
+results = client.structured.amazon.search(query="wireless earbuds")
+posts = client.structured.reddit.posts(subreddit="deals")
+```
+
+Async:
+
+```python
+import asyncio
+from scrapelyserp import AsyncScrapely
+
+async def main() -> None:
+    async with AsyncScrapely() as client:
+        account = await client.account.get()
+        async for item in client.watchlists.list_items_iter("wl_…"):
+            print(item["id"])
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+client = Scrapely(
+    api_key="sk_live_…",                   # default: SCRAPELY_API_KEY
+    base_url="https://scrapelyserp.com",   # default: SCRAPELY_BASE_URL, then this
+    max_retries=2,                         # 429, 5xx (except 501) and network errors
+    timeout=360.0,                         # seconds per attempt
+    headers={"x-my-header": "1"},
+    http_client=httpx.Client(...),         # your own httpx client (proxies, transports, tests)
+)
+```
+
+Use it as a context manager (`with Scrapely() as client:`) or call `client.close()`.
+
+## Resources
+
+`client.products`, `client.offers`, `client.platforms`, `client.structured` (one sub-resource per platform:
+`client.structured.ebay.image_search(...)`), `client.watchlists`, `client.destinations`,
+`client.webhook_endpoints`, `client.s3_export`, `client.account`, `client.meta`.
+
+Path parameters are positional; query parameters are keyword arguments; a body is a dict, keyword arguments, or both
+(keywords win):
+
+```python
+wl = client.watchlists.create(name="Consoles", platform="target", ids=["83887639"], every="15m")
+client.watchlists.update(wl["id"], status="paused")
+page = client.watchlists.list_items(wl["id"], state="active", limit=100)
+client.destinations.set_for_watchlist(wl["id"], destinations=[])
+
+# Any operation by its OpenAPI operationId:
+client.request("getWatchlist", path={"id": wl["id"]})
+```
+
+Every method also takes `options={"headers": ..., "timeout": ..., "max_retries": ...}`.
+
+## Pagination
+
+List operations with a `starting_after` cursor have an `..._iter` twin that walks every page:
+
+```python
+for item in client.watchlists.list_items_iter("wl_…", changed_since="2026-11-01T00:00:00Z"):
+    print(item["id"], item.get("snapshot"))
+```
+
+## Errors
+
+Every error is a `ScrapelyError`. API answers are an `APIError` subclass with `status`, `code` (stable: branch on
+it), `message`, `param`, `docs` and `request_id`:
+
+```python
+from scrapelyserp import APIError, InsufficientCreditsError
+
+try:
+    client.products.fetch(platform="walmart", ids=["5689919121"])
+except InsufficientCreditsError:
+    print("Top up first")
+except APIError as e:
+    print(e.code, e.param, e.request_id)
+```
+
+`BadRequestError` (400), `AuthenticationError` (401), `InsufficientCreditsError` (402), `PermissionDeniedError`
+(403), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429), `InternalServerError` (5xx),
+`ComingSoonError` (501: announced, not live yet; nothing charged), `APIConnectionError` / `APITimeoutError`
+(no answer).
+
+## Retries and idempotency
+
+429 and 5xx answers (except 501) and network errors are retried `max_retries` times, waiting for `Retry-After` when
+the API sends it, else 0.5 s, 1 s, 2 s... Operations that accept an `Idempotency-Key` (creating a watchlist) get one
+generated per call and reused across its retries; pass `idempotency_key=` to choose your own.
+
+## Development
+
+`types.py`, `_routes.py` and `_resources.py` are generated from the API's OpenAPI document by
+`scripts/sdk/generate.ts` in the Scrapely repository; do not edit them by hand.
+
+```sh
+python -m unittest discover -s tests   # offline, against httpx.MockTransport
+python -m build                        # sdist + wheel
+```
+
+## License
+
+MIT

scrapelyserp-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "scrapelyserp"
+version = "0.1.0"
+description = "Official Python SDK for the Scrapely API: product, price and stock data, structured search results, and watchlists that alert on change."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.24,<1"]
+keywords = ["scrapely", "scrapelyserp", "api", "sdk", "price monitoring", "product data"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+  "Intended Audience :: Developers",
+]
+
+[project.urls]
+Homepage = "https://scrapelyserp.com"
+Documentation = "https://scrapelyserp.com/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/scrapelyserp"]

scrapelyserp-0.1.0/src/scrapelyserp/__init__.py

@@ -0,0 +1,50 @@
+"""Official Python SDK for the Scrapely API (https://scrapelyserp.com).
+
+    from scrapelyserp import Scrapely
+
+    client = Scrapely()  # reads SCRAPELY_API_KEY
+    print(client.account.get()["balance"])
+"""
+
+from . import types
+from ._base import DEFAULT_BASE_URL, RequestOptions, normalize_base_url
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ComingSoonError,
+    ConflictError,
+    InsufficientCreditsError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ScrapelyError,
+)
+from ._resources import AsyncScrapely, Scrapely
+from ._version import __version__
+
+__all__ = [
+    "Scrapely",
+    "AsyncScrapely",
+    "RequestOptions",
+    "DEFAULT_BASE_URL",
+    "normalize_base_url",
+    "types",
+    "ScrapelyError",
+    "APIError",
+    "BadRequestError",
+    "AuthenticationError",
+    "InsufficientCreditsError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "InternalServerError",
+    "ComingSoonError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "__version__",
+]