website-leads-database 0.1.0__py3-none-any.whl

website_leads_database/__init__.py

@@ -0,0 +1,6 @@
+"""Python SDK for the hosted Shopify & Ecommerce Store Finder Apify Actor."""
+from .client import WebsiteLeadsDatabaseClient
+from .exceptions import WebsiteLeadsDatabaseError, AuthenticationError, ActorRunError, ActorTimeoutError
+
+__version__ = "0.1.0"
+__all__ = ["WebsiteLeadsDatabaseClient", "WebsiteLeadsDatabaseError", "AuthenticationError", "ActorRunError", "ActorTimeoutError"]

website_leads_database/client.py

@@ -0,0 +1,112 @@
+"""Thin synchronous client for the Shopify & Ecommerce Store Finder Apify Actor."""
+from __future__ import annotations
+
+import os
+import time
+from typing import Any, Mapping
+
+import requests
+
+from .exceptions import ActorRunError, ActorTimeoutError, AuthenticationError, WebsiteLeadsDatabaseError
+
+ACTOR_ID = "apivault_labs~website-leads-database"
+APIFY_API_BASE = "https://api.apify.com/v2"
+TERMINAL_FAIL = {"FAILED", "TIMED-OUT", "ABORTED"}
+
+
+class WebsiteLeadsDatabaseClient:
+    """Run the hosted Actor and download its Dataset results."""
+
+    def __init__(self, api_token: str | None = None, timeout: int = 600,
+                 poll_interval: float = 3.0):
+        token = api_token or os.environ.get("APIFY_API_TOKEN")
+        if not token:
+            raise AuthenticationError(
+                "Pass api_token or set APIFY_API_TOKEN. Create a token at "
+                "https://console.apify.com/account/integrations"
+            )
+        self.timeout = int(timeout)
+        self.poll_interval = float(poll_interval)
+        self.base_url = APIFY_API_BASE
+        self.session = requests.Session()
+        self.session.headers.update({
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "User-Agent": "website-leads-database-python/0.1.0",
+        })
+
+    def run(self, actor_input: Mapping[str, Any], *, actor_timeout_secs: int = 300) -> list[dict[str, Any]]:
+        """Start one Actor run, wait for completion and return clean Dataset items."""
+        if not isinstance(actor_input, Mapping):
+            raise TypeError("actor_input must be a mapping")
+        run_id = self._start(dict(actor_input), actor_timeout_secs)
+        run = self._wait(run_id)
+        dataset_id = run.get("defaultDatasetId")
+        if not dataset_id:
+            raise ActorRunError("Successful run did not expose a Dataset ID")
+        return self._dataset(dataset_id)
+
+    def run_one(self, actor_input: Mapping[str, Any], **kwargs: Any) -> dict[str, Any]:
+        """Return the first Dataset row, raising when no result was produced."""
+        rows = self.run(actor_input, **kwargs)
+        if not rows:
+            raise ActorRunError("Actor completed but returned no Dataset rows")
+        return rows[0]
+
+    @staticmethod
+    def estimate_cost(result_count: int, price_per_1000: float = 8.0) -> float:
+        """Estimate result charges; actual tier pricing and platform usage may vary."""
+        if result_count < 0:
+            raise ValueError("result_count cannot be negative")
+        return round(result_count * price_per_1000 / 1000, 6)
+
+    def _start(self, payload: dict[str, Any], timeout_secs: int) -> str:
+        try:
+            response = self.session.post(
+                f"{self.base_url}/acts/{ACTOR_ID}/runs",
+                params={"timeout": int(timeout_secs)}, json=payload, timeout=30,
+            )
+        except requests.RequestException as exc:
+            raise WebsiteLeadsDatabaseError(f"Could not start Actor run: {exc}") from exc
+        if response.status_code == 401:
+            raise AuthenticationError("Apify rejected the API token")
+        if response.status_code >= 400:
+            raise ActorRunError(f"Run start failed with HTTP {response.status_code}: {response.text[:300]}")
+        run_id = (response.json().get("data") or {}).get("id")
+        if not run_id:
+            raise ActorRunError("Apify response did not contain a run ID")
+        return run_id
+
+    def _wait(self, run_id: str) -> dict[str, Any]:
+        deadline = time.monotonic() + self.timeout
+        while True:
+            try:
+                response = self.session.get(f"{self.base_url}/actor-runs/{run_id}", timeout=30)
+            except requests.RequestException as exc:
+                raise WebsiteLeadsDatabaseError(f"Could not poll Actor run: {exc}") from exc
+            if response.status_code >= 400:
+                raise ActorRunError(f"Run poll failed with HTTP {response.status_code}: {response.text[:300]}")
+            run = response.json().get("data") or {}
+            status = run.get("status")
+            if status == "SUCCEEDED":
+                return run
+            if status in TERMINAL_FAIL:
+                raise ActorRunError(f"Actor run ended with {status}: {run.get('statusMessage') or 'no details'}")
+            if time.monotonic() >= deadline:
+                raise ActorTimeoutError(f"Actor run {run_id} did not finish within {self.timeout} seconds")
+            time.sleep(self.poll_interval)
+
+    def _dataset(self, dataset_id: str) -> list[dict[str, Any]]:
+        try:
+            response = self.session.get(
+                f"{self.base_url}/datasets/{dataset_id}/items",
+                params={"clean": "true", "format": "json"}, timeout=120,
+            )
+        except requests.RequestException as exc:
+            raise WebsiteLeadsDatabaseError(f"Could not download Dataset: {exc}") from exc
+        if response.status_code >= 400:
+            raise ActorRunError(f"Dataset fetch failed with HTTP {response.status_code}: {response.text[:300]}")
+        data = response.json()
+        if not isinstance(data, list):
+            raise ActorRunError("Unexpected Dataset response type")
+        return data

website_leads_database/exceptions.py

@@ -0,0 +1,13 @@
+"""Public exception hierarchy for the Shopify & Ecommerce Store Finder SDK."""
+
+class WebsiteLeadsDatabaseError(Exception):
+    """Base SDK error."""
+
+class AuthenticationError(WebsiteLeadsDatabaseError):
+    """The Apify token is missing or rejected."""
+
+class ActorRunError(WebsiteLeadsDatabaseError):
+    """The Actor run or Dataset request failed."""
+
+class ActorTimeoutError(WebsiteLeadsDatabaseError):
+    """The client stopped waiting before the Actor completed."""

website_leads_database-0.1.0.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: website-leads-database
+Version: 0.1.0
+Summary: Python SDK for Shopify & Ecommerce Store Finder on Apify. Find ecommerce and business websites by public platform, country, contact and firmographic filters through the hosted Apify Actor.
+Author: ApiVault Labs
+License: MIT
+Project-URL: Homepage, https://github.com/apivault-labs/website-leads-database-python
+Project-URL: Documentation, https://github.com/apivault-labs/website-leads-database-python#readme
+Project-URL: Apify Actor, https://apify.com/apivault_labs/website-leads-database
+Project-URL: Bug Tracker, https://github.com/apivault-labs/website-leads-database-python/issues
+Keywords: website-leads,shopify-leads,ecommerce-leads,b2b-leads,technology-database,apify,python-sdk
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Dynamic: license-file
+
+# Shopify & Ecommerce Store Finder — Python SDK
+
+Python client for the [Shopify & Ecommerce Store Finder Apify Actor](https://apify.com/apivault_labs/website-leads-database). Send public Actor inputs, wait for the hosted run, and receive clean Dataset rows without maintaining scraping infrastructure.
+
+[![Apify Actor](https://img.shields.io/badge/Apify-Actor-blue)](https://apify.com/apivault_labs/website-leads-database)
+[![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+## Results
+
+- Platform and country targeting
+- Public emails, phones and social profiles
+- Firmographic and technology fields
+- Sorting, pagination and count-only queries
+
+The repository exposes only the Actor's public input and output contract. Dataset selection and processing remain inside the hosted Actor.
+
+## Install
+
+```bash
+pip install git+https://github.com/apivault-labs/website-leads-database-python.git
+```
+
+Create an Apify token at [Console → Integrations](https://console.apify.com/account/integrations), then:
+
+```python
+from website_leads_database import WebsiteLeadsDatabaseClient
+
+client = WebsiteLeadsDatabaseClient(api_token="apify_api_xxxxxx")
+rows = client.run({'platforms': ['shopify_sites', 'woocommerce_sites'],
+ 'country': ['US'],
+ 'hasEmail': True,
+ 'maxItems': 100})
+print(rows[0] if rows else "No results")
+```
+
+You can set `APIFY_API_TOKEN` instead of passing the token in code.
+
+## Public input options
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `platforms` | `array` | `["all"]` | Platform datasets to search, such as Shopify, WooCommerce, WordPress, Wix, Magento or all platforms. |
+| `columns` | `array` | `[]` | Exact public output-column names. Leave empty to return all available columns. |
+| `sortBy` | `string` | `` | Optional public column used to order rows before applying the limit. |
+| `country` | `array` | `[]` | ISO-2 country codes such as US, GB or DE. |
+| `keyword` | `string` | `` | Substring matched against the domain or company name. |
+| `phoneCode` | `string` | `` | Keep sites with at least one public phone beginning with this country code. |
+| `filters` | `array` | `[]` | Additional public column conditions using column, operator and value fields. |
+| `hasEmail` | `boolean` | `False` | Return only records with a public email. |
+| `hasPhone` | `boolean` | `False` | Return only records with a public phone. |
+| `sortDesc` | `boolean` | `True` | Return highest sort values first. |
+| `dedupeByDomain` | `boolean` | `False` | Remove repeated root domains within the selected window. |
+| `countOnly` | `boolean` | `False` | Return match counts instead of exporting website rows. |
+| `maxItems` | `integer` | `1000` | Maximum returned rows across selected platforms. |
+| `offset` | `integer` | `0` | Rows to skip for stable pagination across runs. |
+
+The complete, versioned schema is also available on the [Actor page](https://apify.com/apivault_labs/website-leads-database).
+
+## Pricing
+
+Pay per delivered result through Apify, starting around **$8/1,000 results** on paid tiers. Free-plan pricing and platform usage can differ; check the Actor page before large runs.
+
+## Examples
+
+- `examples/quickstart.py` — first run
+- `examples/bulk_analysis.py` — expand a target list
+- `examples/export_csv.py` — save flat result fields
+- `examples/save_json.py` — preserve nested output
+- `examples/cost_estimate.py` — estimate result-event charges
+- `examples/environment_token.py` — keep credentials out of code
+
+## Architecture and privacy
+
+This repository is intentionally a thin API client. Collection, retries, analysis and billing run inside the hosted Apify Actor. No private implementation, credentials, scoring weights or infrastructure configuration are included.
+
+## License
+
+MIT. The hosted Actor is a separate paid service governed by Apify terms.

website_leads_database-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+website_leads_database/__init__.py,sha256=XfuF8ibIXac7UjwLddLKM1rYnz9Sl_TxbvSAyfG9_C8,384
+website_leads_database/client.py,sha256=RBeB0yk_ntTWjYLalmzKXd4v30YTqI_IbPlsM1PGmVY,5235
+website_leads_database/exceptions.py,sha256=R2X6BNwXS39Hb5_qDDdbisNgnoC5QyBL-zSwmlg5dNY,473
+website_leads_database-0.1.0.dist-info/licenses/LICENSE,sha256=jNIGgy9DNODPurqUF05B8FchIVKrrh7q47guKrLa7Gk,441
+website_leads_database-0.1.0.dist-info/METADATA,sha256=QdUDY7f7RWCcXfpFgOZ8KomkUvhjjThCMDsn7GPxedc,4842
+website_leads_database-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+website_leads_database-0.1.0.dist-info/top_level.txt,sha256=qJx3Nr1i-sgXQUcBuniiFXC0Tj8hJum26NoxYtv7b9s,23
+website_leads_database-0.1.0.dist-info/RECORD,,

website_leads_database-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

website_leads_database-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+
+Copyright (c) 2026 ApiVault Labs
+
+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. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

website_leads_database-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+website_leads_database