outcrawl 0.1.0__tar.gz

outcrawl-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Build and cache artefacts for this package.
+#
+# This file exists for a second, non-obvious reason: hatchling FORCE-INCLUDES
+# the VCS exclusion file it used into the sdist, so that a rebuild from an
+# unpacked sdist applies the same exclusions. Without a `.gitignore` here it
+# walked up and shipped the MONOREPO's root one — `node_modules/`, the 126 GB
+# Chromium checkout path, our credential rules — at the root of a distribution
+# a customer unpacks. `exclude` in pyproject.toml cannot remove it, because
+# `force_include` runs after exclusions by design. A local file is the fix.
+dist/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.egg-info/
+.venv/
+
+# `uv run` writes this. Deliberately NOT tracked: this is a LIBRARY, so the
+# resolution a customer gets is decided by their own resolver against
+# `dependencies`, and a committed lock would pin only OUR dev environment while
+# generating churn on every `uv run`. An application in this repo would commit
+# one; a library published to PyPI should not.
+uv.lock

outcrawl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aeonmind LLC
+
+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.

outcrawl-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.5
+Name: outcrawl
+Version: 0.1.0
+Summary: The Python client for Outcrawl: scrape, crawl, search and run agent browser tasks on one credit balance.
+Project-URL: Homepage, https://outcrawl.ai
+Project-URL: Repository, https://github.com/aeonmindai/outcrawl-browser
+Project-URL: Issues, https://github.com/aeonmindai/outcrawl-browser/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,browser-automation,crawler,outcrawl,scraping,stealth,web-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# outcrawl
+
+The Python client for [Outcrawl](https://api.outcrawl.ai): scrape, crawl, search and run agent browser
+tasks, on one credit balance. Pure Python — one `py3-none-any` wheel for every operating system,
+and no compiler on any of them.
+
+```sh
+pip install outcrawl
+```
+
+Requires Python 3.10 or newer. One runtime dependency, [`httpx`](https://www.python-httpx.org/),
+which is pure Python, as is everything it pulls.
+
+## Usage
+
+```python
+import asyncio
+from outcrawl import Outcrawl
+
+async def main() -> None:
+    async with Outcrawl() as oc:                       # reads OUTCRAWL_API_KEY
+        doc = await oc.scrape("https://example.com", formats=["markdown"])
+        print(doc.markdown)                            # or doc["markdown"] — it is the wire object
+        print(doc.usage)                               # every call returns what it cost
+
+        job = oc.agent(
+            task="Report the title of the top story on Hacker News.",
+            caps={"budget": "2.00"},                   # the one ceiling a submit must carry
+        )
+        async for record in job:                       # the event cursor, while it runs
+            print(record["kind"], record.get("text"))
+        run = await job                                # and the settled run
+        print(run["status"], run["data"])
+
+asyncio.run(main())
+```
+
+`await` and `async for` on **one** job is one run and not two: they are separate requests against
+one durable row, so watching a run and having its answer is not a choice.
+
+## Configuration
+
+| Variable | Meaning | Default |
+| --- | --- | --- |
+| `OUTCRAWL_API_KEY` | your key | required |
+| `OUTCRAWL_API_URL` | base url | `https://api.outcrawl.ai` |
+
+The same two names `@outcrawl/sdk`, the `outcrawl` CLI and the Outcrawl MCP server read. Pass
+`Outcrawl(api_key=..., base_url=...)` to override them per client.
+
+## Surface
+
+Every one of the 34 capabilities in the registry is reachable, and `tests/test_registry.py` fails
+when one is not.
+
+- `oc.scrape(url, **options)` / `oc.crawl(url, **options)` / `oc.search(query, **options)` —
+  `crawl` is async-iterable and single-pass.
+- `oc.crawl.job(id)` — the same crawl by id, with `status()`, `results()`, `cancel()`, and
+  `oc.crawl.get(id)` / `.results(id)` / `.cancel(id)` for an id on its own. A streaming crawl
+  belongs to its connection, so hanging up cancels it: the row settles `cancelled` with every
+  page it had already delivered, and these routes are how you read the pages you paid for. The
+  id is on `handle.job["id"]` from the first progress frame — store it before you need it.
+- `oc.agent(task=..., caps=...)` — `caps` is required at runtime and `caps.budget` is required
+  inside it; `caps.steps` and `caps.duration` are optional and unset unless you name them, and
+  all three are hard stops when present. The job is awaitable, async-iterable, and carries
+  everything a handle does: `status()`, `results()`, `events()`, `cancel()`, `control()`,
+  `answer()`, `add_file()`. `oc.agent.get(id)` and friends reach a run by id — an id from a
+  webhook needs no submit. `schema` accepts a JSON Schema object and constrains `run["data"]` to
+  it, the same typed submit `@outcrawl/sdk` documents.
+- `oc.profiles` / `oc.secrets` / `oc.rules` / `oc.integrations` / `oc.sessions` / `oc.monitors`.
+  `oc.secrets` has deliberately **no `get`**: there is no route to widen. A run reaches a value
+  only by naming its HANDLE in the submit, and the substitution happens below the model.
+- `oc.usage(**query)` and `oc.credits()` — every credit figure is a decimal **string**; use
+  `decimal.Decimal`, never `float()`.
+- `CAPABILITY_AVAILABILITY` — whether anything is SERVED behind a declared route. A capability
+  nothing serves is refused in your own process, with what is missing, rather than as a 503.
+
+## Errors
+
+Identical to the TypeScript SDK's: same classes, same fields, same sentences. Branch on
+`error.code`, never on `str(error)`.
+
+```python
+from outcrawl import ProfileInUseError, QuotaExceededError
+
+try:
+    ...
+except ProfileInUseError as leased:
+    retry_at = leased.held_until          # a retry that knows when to retry
+except QuotaExceededError as over:
+    await asyncio.sleep(over.retry_after_seconds)
+```
+
+`tests/error_parity.json` is emitted from the TypeScript SDK's own error reconstruction and read by
+both test suites, so neither surface can drift from the other without turning its own suite red.
+
+## What is not here
+
+`oc.browser()`. The live browser needs a CDP connection driven in the caller's own process, which
+is why it is deliberately not a registry capability and why the TypeScript SDK is the one place it
+exists. The same page capabilities are reachable through `agent` and `scrape`, which run the loop
+on our side. That is a difference in kind, not an omission.
+
+The same reason takes `Session.take_control` with it: the TypeScript SDK's `takeControl()` opens a
+CDP connection to a running session's own page so a person can drive it directly, and that
+connection has to live in the caller's process for the same reason `oc.browser()` does. Everything
+else on a session — `get`, `list`, `export`, `live()` — is a row read or a held stream and is here.
+
+## Development
+
+```sh
+pip install -e '.[dev]'                  # pytest + pytest-asyncio, never runtime dependencies
+python3 scripts/gen_registry.py          # regenerate registry.py from packages/core/src/registry.ts
+python3 scripts/gen_registry.py --check  # or just fail if it is stale
+bun ../sdk-python/scripts/gen_error_parity.ts   # regenerate the shared error contract
+python3 -m pytest tests -q               # the drift, parity and ergonomics tests
+```
+
+From the repo root, `npm run test:python` runs the staleness check and the suite together on
+the SUPPORTED FLOOR — `uv run --extra dev --python 3.10 pytest` — so the gate exercises 3.10
+rather than whatever `python3` happens to be. Without `uv`: `pip install -e '.[dev]'` and
+`python3 -m pytest tests -q`.
+
+The two registry-versus-TypeScript tests skip when run from an unpacked sdist, which has no
+TypeScript to compare against, and run whenever the monorepo is present. The reachability test —
+the one that fails when a registry row has no method — has no such dependency and always runs.

outcrawl-0.1.0/README.md

@@ -0,0 +1,126 @@
+# outcrawl
+
+The Python client for [Outcrawl](https://api.outcrawl.ai): scrape, crawl, search and run agent browser
+tasks, on one credit balance. Pure Python — one `py3-none-any` wheel for every operating system,
+and no compiler on any of them.
+
+```sh
+pip install outcrawl
+```
+
+Requires Python 3.10 or newer. One runtime dependency, [`httpx`](https://www.python-httpx.org/),
+which is pure Python, as is everything it pulls.
+
+## Usage
+
+```python
+import asyncio
+from outcrawl import Outcrawl
+
+async def main() -> None:
+    async with Outcrawl() as oc:                       # reads OUTCRAWL_API_KEY
+        doc = await oc.scrape("https://example.com", formats=["markdown"])
+        print(doc.markdown)                            # or doc["markdown"] — it is the wire object
+        print(doc.usage)                               # every call returns what it cost
+
+        job = oc.agent(
+            task="Report the title of the top story on Hacker News.",
+            caps={"budget": "2.00"},                   # the one ceiling a submit must carry
+        )
+        async for record in job:                       # the event cursor, while it runs
+            print(record["kind"], record.get("text"))
+        run = await job                                # and the settled run
+        print(run["status"], run["data"])
+
+asyncio.run(main())
+```
+
+`await` and `async for` on **one** job is one run and not two: they are separate requests against
+one durable row, so watching a run and having its answer is not a choice.
+
+## Configuration
+
+| Variable | Meaning | Default |
+| --- | --- | --- |
+| `OUTCRAWL_API_KEY` | your key | required |
+| `OUTCRAWL_API_URL` | base url | `https://api.outcrawl.ai` |
+
+The same two names `@outcrawl/sdk`, the `outcrawl` CLI and the Outcrawl MCP server read. Pass
+`Outcrawl(api_key=..., base_url=...)` to override them per client.
+
+## Surface
+
+Every one of the 34 capabilities in the registry is reachable, and `tests/test_registry.py` fails
+when one is not.
+
+- `oc.scrape(url, **options)` / `oc.crawl(url, **options)` / `oc.search(query, **options)` —
+  `crawl` is async-iterable and single-pass.
+- `oc.crawl.job(id)` — the same crawl by id, with `status()`, `results()`, `cancel()`, and
+  `oc.crawl.get(id)` / `.results(id)` / `.cancel(id)` for an id on its own. A streaming crawl
+  belongs to its connection, so hanging up cancels it: the row settles `cancelled` with every
+  page it had already delivered, and these routes are how you read the pages you paid for. The
+  id is on `handle.job["id"]` from the first progress frame — store it before you need it.
+- `oc.agent(task=..., caps=...)` — `caps` is required at runtime and `caps.budget` is required
+  inside it; `caps.steps` and `caps.duration` are optional and unset unless you name them, and
+  all three are hard stops when present. The job is awaitable, async-iterable, and carries
+  everything a handle does: `status()`, `results()`, `events()`, `cancel()`, `control()`,
+  `answer()`, `add_file()`. `oc.agent.get(id)` and friends reach a run by id — an id from a
+  webhook needs no submit. `schema` accepts a JSON Schema object and constrains `run["data"]` to
+  it, the same typed submit `@outcrawl/sdk` documents.
+- `oc.profiles` / `oc.secrets` / `oc.rules` / `oc.integrations` / `oc.sessions` / `oc.monitors`.
+  `oc.secrets` has deliberately **no `get`**: there is no route to widen. A run reaches a value
+  only by naming its HANDLE in the submit, and the substitution happens below the model.
+- `oc.usage(**query)` and `oc.credits()` — every credit figure is a decimal **string**; use
+  `decimal.Decimal`, never `float()`.
+- `CAPABILITY_AVAILABILITY` — whether anything is SERVED behind a declared route. A capability
+  nothing serves is refused in your own process, with what is missing, rather than as a 503.
+
+## Errors
+
+Identical to the TypeScript SDK's: same classes, same fields, same sentences. Branch on
+`error.code`, never on `str(error)`.
+
+```python
+from outcrawl import ProfileInUseError, QuotaExceededError
+
+try:
+    ...
+except ProfileInUseError as leased:
+    retry_at = leased.held_until          # a retry that knows when to retry
+except QuotaExceededError as over:
+    await asyncio.sleep(over.retry_after_seconds)
+```
+
+`tests/error_parity.json` is emitted from the TypeScript SDK's own error reconstruction and read by
+both test suites, so neither surface can drift from the other without turning its own suite red.
+
+## What is not here
+
+`oc.browser()`. The live browser needs a CDP connection driven in the caller's own process, which
+is why it is deliberately not a registry capability and why the TypeScript SDK is the one place it
+exists. The same page capabilities are reachable through `agent` and `scrape`, which run the loop
+on our side. That is a difference in kind, not an omission.
+
+The same reason takes `Session.take_control` with it: the TypeScript SDK's `takeControl()` opens a
+CDP connection to a running session's own page so a person can drive it directly, and that
+connection has to live in the caller's process for the same reason `oc.browser()` does. Everything
+else on a session — `get`, `list`, `export`, `live()` — is a row read or a held stream and is here.
+
+## Development
+
+```sh
+pip install -e '.[dev]'                  # pytest + pytest-asyncio, never runtime dependencies
+python3 scripts/gen_registry.py          # regenerate registry.py from packages/core/src/registry.ts
+python3 scripts/gen_registry.py --check  # or just fail if it is stale
+bun ../sdk-python/scripts/gen_error_parity.ts   # regenerate the shared error contract
+python3 -m pytest tests -q               # the drift, parity and ergonomics tests
+```
+
+From the repo root, `npm run test:python` runs the staleness check and the suite together on
+the SUPPORTED FLOOR — `uv run --extra dev --python 3.10 pytest` — so the gate exercises 3.10
+rather than whatever `python3` happens to be. Without `uv`: `pip install -e '.[dev]'` and
+`python3 -m pytest tests -q`.
+
+The two registry-versus-TypeScript tests skip when run from an unpacked sdist, which has no
+TypeScript to compare against, and run whenever the monorepo is present. The reachability test —
+the one that fails when a registry row has no method — has no such dependency and always runs.

outcrawl-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "outcrawl"
+version = "0.1.0"
+description = "The Python client for Outcrawl: scrape, crawl, search and run agent browser tasks on one credit balance."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+keywords = [
+  "outcrawl",
+  "scraping",
+  "crawler",
+  "web-search",
+  "browser-automation",
+  "agent",
+  "stealth",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Topic :: Internet :: WWW/HTTP",
+  "Typing :: Typed",
+]
+
+# The one runtime dependency, and it is pure Python — as is everything it pulls
+# (httpcore, h11, certifi, idna, anyio, sniffio). That is what keeps this wheel
+# `py3-none-any` and makes "supports every OS" a fact about the artefact rather
+# than a hope about the user's compiler.
+dependencies = ["httpx>=0.27,<1"]
+
+[project.urls]
+Homepage = "https://outcrawl.ai"
+Repository = "https://github.com/aeonmindai/outcrawl-browser"
+Issues = "https://github.com/aeonmindai/outcrawl-browser/issues"
+
+[project.optional-dependencies]
+# Test-only. Never a runtime dependency: a customer installing this package must
+# not be handed a test runner.
+dev = ["pytest>=8", "pytest-asyncio>=0.24"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/outcrawl"]
+
+[tool.hatch.build.targets.sdist]
+# The sdist carries the tests and the generator, so `pytest` works from an
+# unpacked source distribution — including the registry drift test, which needs
+# the TypeScript registry and therefore reports honestly that it cannot run
+# rather than passing silently.
+include = ["src", "tests", "scripts", "README.md", "pyproject.toml", "LICENSE"]
+# Hatchling FORCE-INCLUDES the VCS exclusion file it used, so a rebuild from an
+# unpacked sdist applies the same exclusions — and `exclude` cannot remove a
+# force-included path. With no `.gitignore` in this directory it walked up and
+# shipped the MONOREPO's root one, whose contents are `node_modules/`, the
+# Chromium checkout path and our credential rules. `packages/sdk-python/.gitignore`
+# is what makes the shipped one this package's own; see the note in it.
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

outcrawl-0.1.0/scripts/gen_error_parity.ts

@@ -0,0 +1,95 @@
+/**
+ * Emit the cross-language error contract both SDKs are held to.
+ *
+ * THE PROBLEM. "Auth, base URL and error shapes identical across both" is a
+ * claim about two codebases in two languages, and the only way it stays true is
+ * if one artefact pins it and BOTH suites read that artefact. A Python mirror
+ * checked only by Python tests is a mirror that drifts the first time a
+ * TypeScript message is reworded, and the customer who notices is the one
+ * quoting one sentence to support while their logs contain the other.
+ *
+ * So this writes `tests/error_parity.json`: for every code in
+ * `OUTCRAWL_ERROR_CODES`, the wire body the platform sends and exactly what the
+ * TypeScript SDK's `errorFromWire` reconstructs from it — class, code, status,
+ * message, details.
+ *
+ *   - `packages/sdk-python/tests/test_errors.py` asserts Python rebuilds the
+ *     same thing from the same body.
+ *   - `packages/sdk/test/error-parity.test.ts` asserts TypeScript still does,
+ *     so a reworded message turns the TS suite red rather than silently
+ *     invalidating the fixture the Python suite trusts.
+ *
+ * The fixture lives in the Python package because it must ship inside the
+ * sdist: `pytest` from an unpacked source distribution has no TypeScript to
+ * read, and a parity test that skips when it cannot find the other language is
+ * a parity test that passes while the two disagree.
+ *
+ *   bun packages/sdk-python/scripts/gen_error_parity.ts
+ */
+
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { OUTCRAWL_ERROR_CODES, isOutcrawlError } from '../../core/src/errors';
+import { ERROR_SAMPLES } from '../../api/src/errors';
+import { errorFromWire } from '../../sdk/src/transport';
+
+interface Rebuilt {
+  readonly class: string;
+  readonly code: string | null;
+  readonly status: number | null;
+  readonly message: string;
+  readonly details: Record<string, unknown> | null;
+}
+
+interface ParityRow {
+  readonly capabilityCode: string;
+  readonly status: number;
+  readonly wire: { code: string; message: string; details: Record<string, unknown> };
+  readonly rebuilt: Rebuilt;
+}
+
+function describe(error: Error): Rebuilt {
+  if (!isOutcrawlError(error)) {
+    // Every declared code must reconstruct into a typed error; an
+    // `OutcrawlApiError` here is the drop this file exists to catch, and it is
+    // recorded rather than thrown on so the fixture shows the truth.
+    return {
+      class: error.constructor.name,
+      code: null,
+      status: null,
+      message: error.message,
+      details: null,
+    };
+  }
+  return {
+    class: error.constructor.name,
+    code: error.code,
+    status: error.status,
+    message: error.message,
+    details: { ...error.details },
+  };
+}
+
+const rows: ParityRow[] = OUTCRAWL_ERROR_CODES.map((code) => {
+  const sample = ERROR_SAMPLES[code];
+  const wire = sample.toJSON();
+  return {
+    capabilityCode: code,
+    status: sample.status,
+    wire,
+    rebuilt: describe(errorFromWire(sample.status, wire)),
+  };
+});
+
+const dropped = rows.filter((row) => row.rebuilt.code === null);
+if (dropped.length > 0) {
+  throw new Error(
+    `errorFromWire drops ${dropped.length} declared code(s) to an untyped error: ` +
+      `${dropped.map((row) => row.capabilityCode).join(', ')}. Map them before regenerating.`,
+  );
+}
+
+const target = join(import.meta.dir, '..', 'tests', 'error_parity.json');
+writeFileSync(target, `${JSON.stringify({ rows }, null, 2)}\n`, 'utf8');
+console.log(`wrote ${target} (${rows.length} codes)`);