apivault-substack-archive-scraper 0.1.0__tar.gz

apivault_substack_archive_scraper-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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, 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.

apivault_substack_archive_scraper-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: apivault-substack-archive-scraper
+Version: 0.1.0
+Summary: Python client for Substack Archive Scraper on Apify. Run, resume and download results with diagnostics.
+Author: ApiVault Labs
+License-Expression: MIT
+Project-URL: Homepage, https://apify.com/apivault_labs/substack-archive-scraper
+Project-URL: Source, https://github.com/apivault-labs/apivault-labs/tree/main/packages/apivault-substack-archive-scraper
+Project-URL: Documentation, https://github.com/apivault-labs/apivault-labs/tree/main/packages/apivault-substack-archive-scraper#readme
+Keywords: apify,python-sdk,substack,archive,scraper
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Substack Archive Scraper - Python client
+
+Collect public Substack archive posts, dates, URLs and optional public article text.
+
+This client starts the hosted [Apify Actor](https://apify.com/apivault_labs/substack-archive-scraper), waits for completion and downloads Dataset records. It also reads SUMMARY and ERRORS when available. Source coverage and result fields depend on the Actor.
+
+## Install
+
+```bash
+pip install apivault-substack-archive-scraper
+```
+
+## Run
+
+Set `APIFY_TOKEN` in your environment. Replace the example values with your own valid inputs from the [Actor input form](https://apify.com/apivault_labs/substack-archive-scraper/input).
+
+```python
+from apivault_substack_archive_scraper import Client, WaitTimeout
+
+client = Client()
+actor_input = {
+    "urls": [
+        "https://www.experimental-history.com"
+    ],
+    "maxItems": 5
+}
+result = client.run(actor_input, max_total_charge_usd=0.05, max_rows=100)
+print(result.run_id, len(result.rows), result.truncated)
+print(result.summary)
+```
+
+An Apify account and token are required. The package has no subscription of its own; hosted runs are billed by Apify under the Actor pricing. The event charge cap may not include platform usage. Review the [current price](https://apify.com/apivault_labs/substack-archive-scraper/pricing) before changing it. `max_rows` limits the download, not the Actor collection or its charges; configure an Actor result limit too.
+
+## Resume and diagnostics
+
+`client.start(input)` returns a run ID; `client.wait(run_id)` and `client.result(run_id)` resume an existing run. A `WaitTimeout` exposes `run_id`. Starting a run is never automatically retried. Use an existing run ID after a connection or waiting failure to avoid duplicate paid runs. Failed and aborted runs raise `ActorError`. No-match and partial results require inspecting `summary` and `errors`; diagnostic rows must not be mistaken for useful results.
+
+Rows can be serialized as JSON or used in your own CSV/Excel pipeline. Native Dataset exports are available in Apify. Optional integrations and credentials depend on the Actor.
+
+[Hosted Actor](https://apify.com/apivault_labs/substack-archive-scraper) | [Source](https://github.com/apivault-labs/apivault-labs/tree/main/packages/apivault-substack-archive-scraper) | [PyPI](https://pypi.org/project/apivault-substack-archive-scraper/)
+
+
+## Related integration
+
+[Python client](https://github.com/apivault-labs/apivault-labs/tree/main/packages/apivault-substack-archive-scraper) · [PyPI](https://pypi.org/project/apivault-substack-archive-scraper/) · [n8n source and workflow](https://github.com/apivault-labs/apivault-labs/tree/main/community-nodes/n8n-nodes-apivault-substack-archive-scraper) · [npm](https://www.npmjs.com/package/n8n-nodes-apivault-substack-archive-scraper)
+
+
+## Source coverage and limits
+
+Public archives and explicit post URLs only. Paid posts provide metadata and a short preview; no subscriber content, login or paywall bypass. Inspect source diagnostics and continuation limits. Reading a saved run does not continue the archive; copy continuation inputs into a new separately billed run.
+
+
+## Collection and spend limits
+
+The small example sets `maxItems` to bound paid collection. `max_rows` / Maximum Rows to Read limits only the dataset download. The event charge cap does not cap infrastructure or proxy usage. The clients do not start an automatic paid retry after a start request fails. Save the run ID and inspect that run before starting another. For source failures, inspect SUMMARY and ERRORS in Apify Console; Client.result only returns successful runs.
+
+The hosted Actor also charges an Actor Start event at USD 0.00005 per GB of configured memory, minimum one event, in addition to delivered-result events and infrastructure usage. Empty or failed runs can still incur start and resource costs.

apivault_substack_archive_scraper-0.1.0/README.md

@@ -0,0 +1,57 @@
+# Substack Archive Scraper - Python client
+
+Collect public Substack archive posts, dates, URLs and optional public article text.
+
+This client starts the hosted [Apify Actor](https://apify.com/apivault_labs/substack-archive-scraper), waits for completion and downloads Dataset records. It also reads SUMMARY and ERRORS when available. Source coverage and result fields depend on the Actor.
+
+## Install
+
+```bash
+pip install apivault-substack-archive-scraper
+```
+
+## Run
+
+Set `APIFY_TOKEN` in your environment. Replace the example values with your own valid inputs from the [Actor input form](https://apify.com/apivault_labs/substack-archive-scraper/input).
+
+```python
+from apivault_substack_archive_scraper import Client, WaitTimeout
+
+client = Client()
+actor_input = {
+    "urls": [
+        "https://www.experimental-history.com"
+    ],
+    "maxItems": 5
+}
+result = client.run(actor_input, max_total_charge_usd=0.05, max_rows=100)
+print(result.run_id, len(result.rows), result.truncated)
+print(result.summary)
+```
+
+An Apify account and token are required. The package has no subscription of its own; hosted runs are billed by Apify under the Actor pricing. The event charge cap may not include platform usage. Review the [current price](https://apify.com/apivault_labs/substack-archive-scraper/pricing) before changing it. `max_rows` limits the download, not the Actor collection or its charges; configure an Actor result limit too.
+
+## Resume and diagnostics
+
+`client.start(input)` returns a run ID; `client.wait(run_id)` and `client.result(run_id)` resume an existing run. A `WaitTimeout` exposes `run_id`. Starting a run is never automatically retried. Use an existing run ID after a connection or waiting failure to avoid duplicate paid runs. Failed and aborted runs raise `ActorError`. No-match and partial results require inspecting `summary` and `errors`; diagnostic rows must not be mistaken for useful results.
+
+Rows can be serialized as JSON or used in your own CSV/Excel pipeline. Native Dataset exports are available in Apify. Optional integrations and credentials depend on the Actor.
+
+[Hosted Actor](https://apify.com/apivault_labs/substack-archive-scraper) | [Source](https://github.com/apivault-labs/apivault-labs/tree/main/packages/apivault-substack-archive-scraper) | [PyPI](https://pypi.org/project/apivault-substack-archive-scraper/)
+
+
+## Related integration
+
+[Python client](https://github.com/apivault-labs/apivault-labs/tree/main/packages/apivault-substack-archive-scraper) · [PyPI](https://pypi.org/project/apivault-substack-archive-scraper/) · [n8n source and workflow](https://github.com/apivault-labs/apivault-labs/tree/main/community-nodes/n8n-nodes-apivault-substack-archive-scraper) · [npm](https://www.npmjs.com/package/n8n-nodes-apivault-substack-archive-scraper)
+
+
+## Source coverage and limits
+
+Public archives and explicit post URLs only. Paid posts provide metadata and a short preview; no subscriber content, login or paywall bypass. Inspect source diagnostics and continuation limits. Reading a saved run does not continue the archive; copy continuation inputs into a new separately billed run.
+
+
+## Collection and spend limits
+
+The small example sets `maxItems` to bound paid collection. `max_rows` / Maximum Rows to Read limits only the dataset download. The event charge cap does not cap infrastructure or proxy usage. The clients do not start an automatic paid retry after a start request fails. Save the run ID and inspect that run before starting another. For source failures, inspect SUMMARY and ERRORS in Apify Console; Client.result only returns successful runs.
+
+The hosted Actor also charges an Actor Start event at USD 0.00005 per GB of configured memory, minimum one event, in addition to delivered-result events and infrastructure usage. Empty or failed runs can still incur start and resource costs.

apivault_substack_archive_scraper-0.1.0/apivault_substack_archive_scraper/__init__.py

@@ -0,0 +1,4 @@
+from .client import Client, RunResult, ActorError, WaitTimeout
+
+__all__ = ["Client", "RunResult", "ActorError", "WaitTimeout"]
+__version__ = "0.1.0"

apivault_substack_archive_scraper-0.1.0/apivault_substack_archive_scraper/client.py

@@ -0,0 +1,113 @@
+"""Thin client for the hosted substack-archive-scraper Apify Actor."""
+from __future__ import annotations
+from dataclasses import dataclass
+import json, os, re, time, urllib.error, urllib.parse, urllib.request
+from typing import Any, Mapping
+
+ACTOR_ID = "nJFN711cBZgSpDITt"
+API = "https://api.apify.com/v2"
+
+class ActorError(RuntimeError):
+    """The API rejected a request or the run did not succeed."""
+
+class WaitTimeout(ActorError):
+    """Waiting ended; resume this run instead of starting a duplicate."""
+    def __init__(self, run_id: str):
+        self.run_id = run_id
+        super().__init__(f"Waiting timed out; resume run {run_id}")
+
+@dataclass
+class RunResult:
+    run_id: str
+    dataset_id: str
+    status: str
+    rows: list[dict[str, Any]]
+    summary: Any
+    errors: Any
+    truncated: bool
+
+class Client:
+    """Start one hosted run, wait safely, and read rows plus diagnostics."""
+    def __init__(self, token: str | None = None):
+        self._token = (token or os.environ.get("APIFY_TOKEN") or os.environ.get("APIFY_API_TOKEN") or "").strip()
+        if not self._token:
+            raise ValueError("Provide an Apify token or set APIFY_TOKEN")
+
+    @staticmethod
+    def _id(value: str) -> str:
+        if not isinstance(value, str) or not re.fullmatch(r"[A-Za-z0-9_-]{1,100}", value):
+            raise ValueError("Invalid Apify identifier")
+        return value
+
+    def _request(self, method: str, path: str, body: Any = None, params: dict | None = None, optional: bool = False) -> Any:
+        url = API + path + ("?" + urllib.parse.urlencode(params) if params else "")
+        request = urllib.request.Request(url, method=method,
+            data=json.dumps(body).encode("utf-8") if body is not None else None,
+            headers={"Authorization": "Bearer " + self._token, "Content-Type": "application/json", "User-Agent": "apivault-substack-archive-scraper/0.1.0"})
+        try:
+            with urllib.request.urlopen(request, timeout=30) as response:
+                raw = response.read()
+                return json.loads(raw) if raw else None
+        except urllib.error.HTTPError as error:
+            if optional and error.code == 404:
+                return None
+            raise ActorError(f"Apify request failed with HTTP {error.code}") from None
+        except (urllib.error.URLError, TimeoutError):
+            raise ActorError("Apify request could not complete; check an existing run before retrying") from None
+
+    def start(self, actor_input: Mapping[str, Any], *, max_total_charge_usd: float = 0.05, actor_timeout_secs: int = 300) -> dict[str, Any]:
+        if not isinstance(actor_input, Mapping):
+            raise TypeError("actor_input must be a mapping")
+        if not 0 < max_total_charge_usd <= 1000 or not 1 <= actor_timeout_secs <= 3600:
+            raise ValueError("Use a positive charge cap and timeout of 1–3600 seconds")
+        # POST is never automatically retried: a retry could start a paid duplicate.
+        response = self._request("POST", f"/acts/{ACTOR_ID}/runs", dict(actor_input),
+            {"maxTotalChargeUsd": max_total_charge_usd, "timeout": actor_timeout_secs, "build": "latest"})
+        run = response.get("data", {}) if isinstance(response, dict) else {}
+        if not run.get("id"):
+            raise ActorError("Apify did not return a run ID; check Console before retrying")
+        return run
+
+    def wait(self, run_id: str, *, wait_secs: float = 600, poll_interval: float = 3) -> dict[str, Any]:
+        run_id = self._id(run_id)
+        if wait_secs <= 0 or poll_interval <= 0:
+            raise ValueError("wait_secs and poll_interval must be positive")
+        deadline = time.monotonic() + wait_secs
+        while time.monotonic() < deadline:
+            run = self._request("GET", f"/actor-runs/{run_id}")["data"]
+            if run["status"] == "SUCCEEDED":
+                return run
+            if run["status"] in {"FAILED", "ABORTED", "TIMED-OUT"}:
+                raise ActorError(f"Run {run_id} ended with status {run['status']}")
+            time.sleep(min(poll_interval, max(0, deadline-time.monotonic())))
+        raise WaitTimeout(run_id)
+
+    def result(self, run_id: str, *, max_rows: int = 1000) -> RunResult:
+        run_id = self._id(run_id)
+        if not isinstance(max_rows, int) or not 1 <= max_rows <= 100000:
+            raise ValueError("max_rows must be an integer from 1 to 100000")
+        run = self._request("GET", f"/actor-runs/{run_id}")["data"]
+        if run["status"] != "SUCCEEDED":
+            raise ActorError(f"Run {run_id} is {run['status']}; wait before reading results")
+        dataset = self._id(run["defaultDatasetId"])
+        metadata = self._request("GET", f"/datasets/{dataset}")["data"]
+        rows: list[dict[str, Any]] = []
+        while len(rows) < max_rows:
+            limit = min(1000, max_rows-len(rows))
+            page = self._request("GET", f"/datasets/{dataset}/items", params={"clean": "true", "limit": limit, "offset": len(rows)})
+            if not isinstance(page, list):
+                raise ActorError("Apify returned an unexpected Dataset response")
+            if len(page) > limit:
+                raise ActorError("Dataset response exceeded the requested page limit")
+            rows.extend(page)
+            if len(page) < limit:
+                break
+        store = self._id(run["defaultKeyValueStoreId"])
+        summary = self._request("GET", f"/key-value-stores/{store}/records/SUMMARY", optional=True)
+        errors = self._request("GET", f"/key-value-stores/{store}/records/ERRORS", optional=True)
+        return RunResult(run_id, dataset, run["status"], rows, summary, errors, metadata.get("itemCount", len(rows)) > len(rows))
+
+    def run(self, actor_input: Mapping[str, Any], *, max_total_charge_usd: float = 0.05, actor_timeout_secs: int = 300, wait_secs: float = 600, max_rows: int = 1000) -> RunResult:
+        run = self.start(actor_input, max_total_charge_usd=max_total_charge_usd, actor_timeout_secs=actor_timeout_secs)
+        self.wait(run["id"], wait_secs=wait_secs)
+        return self.result(run["id"], max_rows=max_rows)

apivault_substack_archive_scraper-0.1.0/apivault_substack_archive_scraper.egg-info/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: apivault-substack-archive-scraper
+Version: 0.1.0
+Summary: Python client for Substack Archive Scraper on Apify. Run, resume and download results with diagnostics.
+Author: ApiVault Labs
+License-Expression: MIT
+Project-URL: Homepage, https://apify.com/apivault_labs/substack-archive-scraper
+Project-URL: Source, https://github.com/apivault-labs/apivault-labs/tree/main/packages/apivault-substack-archive-scraper
+Project-URL: Documentation, https://github.com/apivault-labs/apivault-labs/tree/main/packages/apivault-substack-archive-scraper#readme
+Keywords: apify,python-sdk,substack,archive,scraper
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Substack Archive Scraper - Python client
+
+Collect public Substack archive posts, dates, URLs and optional public article text.
+
+This client starts the hosted [Apify Actor](https://apify.com/apivault_labs/substack-archive-scraper), waits for completion and downloads Dataset records. It also reads SUMMARY and ERRORS when available. Source coverage and result fields depend on the Actor.
+
+## Install
+
+```bash
+pip install apivault-substack-archive-scraper
+```
+
+## Run
+
+Set `APIFY_TOKEN` in your environment. Replace the example values with your own valid inputs from the [Actor input form](https://apify.com/apivault_labs/substack-archive-scraper/input).
+
+```python
+from apivault_substack_archive_scraper import Client, WaitTimeout
+
+client = Client()
+actor_input = {
+    "urls": [
+        "https://www.experimental-history.com"
+    ],
+    "maxItems": 5
+}
+result = client.run(actor_input, max_total_charge_usd=0.05, max_rows=100)
+print(result.run_id, len(result.rows), result.truncated)
+print(result.summary)
+```
+
+An Apify account and token are required. The package has no subscription of its own; hosted runs are billed by Apify under the Actor pricing. The event charge cap may not include platform usage. Review the [current price](https://apify.com/apivault_labs/substack-archive-scraper/pricing) before changing it. `max_rows` limits the download, not the Actor collection or its charges; configure an Actor result limit too.
+
+## Resume and diagnostics
+
+`client.start(input)` returns a run ID; `client.wait(run_id)` and `client.result(run_id)` resume an existing run. A `WaitTimeout` exposes `run_id`. Starting a run is never automatically retried. Use an existing run ID after a connection or waiting failure to avoid duplicate paid runs. Failed and aborted runs raise `ActorError`. No-match and partial results require inspecting `summary` and `errors`; diagnostic rows must not be mistaken for useful results.
+
+Rows can be serialized as JSON or used in your own CSV/Excel pipeline. Native Dataset exports are available in Apify. Optional integrations and credentials depend on the Actor.
+
+[Hosted Actor](https://apify.com/apivault_labs/substack-archive-scraper) | [Source](https://github.com/apivault-labs/apivault-labs/tree/main/packages/apivault-substack-archive-scraper) | [PyPI](https://pypi.org/project/apivault-substack-archive-scraper/)
+
+
+## Related integration
+
+[Python client](https://github.com/apivault-labs/apivault-labs/tree/main/packages/apivault-substack-archive-scraper) · [PyPI](https://pypi.org/project/apivault-substack-archive-scraper/) · [n8n source and workflow](https://github.com/apivault-labs/apivault-labs/tree/main/community-nodes/n8n-nodes-apivault-substack-archive-scraper) · [npm](https://www.npmjs.com/package/n8n-nodes-apivault-substack-archive-scraper)
+
+
+## Source coverage and limits
+
+Public archives and explicit post URLs only. Paid posts provide metadata and a short preview; no subscriber content, login or paywall bypass. Inspect source diagnostics and continuation limits. Reading a saved run does not continue the archive; copy continuation inputs into a new separately billed run.
+
+
+## Collection and spend limits
+
+The small example sets `maxItems` to bound paid collection. `max_rows` / Maximum Rows to Read limits only the dataset download. The event charge cap does not cap infrastructure or proxy usage. The clients do not start an automatic paid retry after a start request fails. Save the run ID and inspect that run before starting another. For source failures, inspect SUMMARY and ERRORS in Apify Console; Client.result only returns successful runs.
+
+The hosted Actor also charges an Actor Start event at USD 0.00005 per GB of configured memory, minimum one event, in addition to delivered-result events and infrastructure usage. Empty or failed runs can still incur start and resource costs.

apivault_substack_archive_scraper-0.1.0/apivault_substack_archive_scraper.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+apivault_substack_archive_scraper/__init__.py
+apivault_substack_archive_scraper/client.py
+apivault_substack_archive_scraper.egg-info/PKG-INFO
+apivault_substack_archive_scraper.egg-info/SOURCES.txt
+apivault_substack_archive_scraper.egg-info/dependency_links.txt
+apivault_substack_archive_scraper.egg-info/top_level.txt

apivault_substack_archive_scraper-0.1.0/apivault_substack_archive_scraper.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

apivault_substack_archive_scraper-0.1.0/apivault_substack_archive_scraper.egg-info/top_level.txt

@@ -0,0 +1 @@
+apivault_substack_archive_scraper

apivault_substack_archive_scraper-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "apivault-substack-archive-scraper"
+version = "0.1.0"
+description = "Python client for Substack Archive Scraper on Apify. Run, resume and download results with diagnostics."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name="ApiVault Labs"}]
+keywords = ["apify", "python-sdk", "substack", "archive", "scraper"]
+
+[project.urls]
+Homepage = "https://apify.com/apivault_labs/substack-archive-scraper"
+Source = "https://github.com/apivault-labs/apivault-labs/tree/main/packages/apivault-substack-archive-scraper"
+Documentation = "https://github.com/apivault-labs/apivault-labs/tree/main/packages/apivault-substack-archive-scraper#readme"
+
+[tool.setuptools.packages.find]
+include = ["apivault_substack_archive_scraper*"]

apivault_substack_archive_scraper-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+