bytekit-sdk 0.3.0__py3-none-any.whl

bytekit/models/webhook_delivery_response.py

@@ -0,0 +1,270 @@
+import datetime
+from collections.abc import Mapping
+from typing import (
+    Any,
+    TypeVar,
+    Union,
+    cast,
+)
+
+from attrs import define as _attrs_define
+from attrs import field as _attrs_field
+from dateutil.parser import isoparse
+
+from ..models.webhook_delivery_response_event_type import (
+    WebhookDeliveryResponseEventType,
+)
+from ..models.webhook_delivery_response_status import WebhookDeliveryResponseStatus
+
+T = TypeVar("T", bound="WebhookDeliveryResponse")
+
+
+@_attrs_define
+class WebhookDeliveryResponse:
+    """
+    Attributes:
+        id (str):  Example: wh_01j9abc123.
+        event_type (WebhookDeliveryResponseEventType): Machine-readable event discriminator. This value is also sent as
+            the `X-ByteKit-Event` request header on every outbound webhook delivery, allowing receivers to dispatch on the
+            header without parsing the body shape.
+             Example: bulk.completed.
+        target_url (str):
+        status (WebhookDeliveryResponseStatus):
+        attempts (int):
+        max_attempts (int):
+        next_attempt_at (Union[None, datetime.datetime]):
+        response_status (Union[None, int]):
+        response_ms (Union[None, int]):
+        created_at (datetime.datetime):
+        delivered_at (Union[None, datetime.datetime]):
+        screenshot_id (Union[None, str]):
+        recording_id (Union[None, str]):
+        bulk_id (Union[None, str]):
+        monitor_id (Union[None, str]):
+        scrape_id (Union[None, str]):
+    """
+
+    id: str
+    event_type: WebhookDeliveryResponseEventType
+    target_url: str
+    status: WebhookDeliveryResponseStatus
+    attempts: int
+    max_attempts: int
+    next_attempt_at: Union[None, datetime.datetime]
+    response_status: Union[None, int]
+    response_ms: Union[None, int]
+    created_at: datetime.datetime
+    delivered_at: Union[None, datetime.datetime]
+    screenshot_id: Union[None, str]
+    recording_id: Union[None, str]
+    bulk_id: Union[None, str]
+    monitor_id: Union[None, str]
+    scrape_id: Union[None, str]
+    additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        id = self.id
+
+        event_type = self.event_type.value
+
+        target_url = self.target_url
+
+        status = self.status.value
+
+        attempts = self.attempts
+
+        max_attempts = self.max_attempts
+
+        next_attempt_at: Union[None, str]
+        if isinstance(self.next_attempt_at, datetime.datetime):
+            next_attempt_at = self.next_attempt_at.isoformat()
+        else:
+            next_attempt_at = self.next_attempt_at
+
+        response_status: Union[None, int]
+        response_status = self.response_status
+
+        response_ms: Union[None, int]
+        response_ms = self.response_ms
+
+        created_at = self.created_at.isoformat()
+
+        delivered_at: Union[None, str]
+        if isinstance(self.delivered_at, datetime.datetime):
+            delivered_at = self.delivered_at.isoformat()
+        else:
+            delivered_at = self.delivered_at
+
+        screenshot_id: Union[None, str]
+        screenshot_id = self.screenshot_id
+
+        recording_id: Union[None, str]
+        recording_id = self.recording_id
+
+        bulk_id: Union[None, str]
+        bulk_id = self.bulk_id
+
+        monitor_id: Union[None, str]
+        monitor_id = self.monitor_id
+
+        scrape_id: Union[None, str]
+        scrape_id = self.scrape_id
+
+        field_dict: dict[str, Any] = {}
+        field_dict.update(self.additional_properties)
+        field_dict.update(
+            {
+                "id": id,
+                "event_type": event_type,
+                "target_url": target_url,
+                "status": status,
+                "attempts": attempts,
+                "max_attempts": max_attempts,
+                "next_attempt_at": next_attempt_at,
+                "response_status": response_status,
+                "response_ms": response_ms,
+                "created_at": created_at,
+                "delivered_at": delivered_at,
+                "screenshot_id": screenshot_id,
+                "recording_id": recording_id,
+                "bulk_id": bulk_id,
+                "monitor_id": monitor_id,
+                "scrape_id": scrape_id,
+            }
+        )
+
+        return field_dict
+
+    @classmethod
+    def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
+        d = dict(src_dict)
+        id = d.pop("id")
+
+        event_type = WebhookDeliveryResponseEventType(d.pop("event_type"))
+
+        target_url = d.pop("target_url")
+
+        status = WebhookDeliveryResponseStatus(d.pop("status"))
+
+        attempts = d.pop("attempts")
+
+        max_attempts = d.pop("max_attempts")
+
+        def _parse_next_attempt_at(data: object) -> Union[None, datetime.datetime]:
+            if data is None:
+                return data
+            try:
+                if not isinstance(data, str):
+                    raise TypeError()
+                next_attempt_at_type_0 = isoparse(data)
+
+                return next_attempt_at_type_0
+            except:  # noqa: E722
+                pass
+            return cast(Union[None, datetime.datetime], data)
+
+        next_attempt_at = _parse_next_attempt_at(d.pop("next_attempt_at"))
+
+        def _parse_response_status(data: object) -> Union[None, int]:
+            if data is None:
+                return data
+            return cast(Union[None, int], data)
+
+        response_status = _parse_response_status(d.pop("response_status"))
+
+        def _parse_response_ms(data: object) -> Union[None, int]:
+            if data is None:
+                return data
+            return cast(Union[None, int], data)
+
+        response_ms = _parse_response_ms(d.pop("response_ms"))
+
+        created_at = isoparse(d.pop("created_at"))
+
+        def _parse_delivered_at(data: object) -> Union[None, datetime.datetime]:
+            if data is None:
+                return data
+            try:
+                if not isinstance(data, str):
+                    raise TypeError()
+                delivered_at_type_0 = isoparse(data)
+
+                return delivered_at_type_0
+            except:  # noqa: E722
+                pass
+            return cast(Union[None, datetime.datetime], data)
+
+        delivered_at = _parse_delivered_at(d.pop("delivered_at"))
+
+        def _parse_screenshot_id(data: object) -> Union[None, str]:
+            if data is None:
+                return data
+            return cast(Union[None, str], data)
+
+        screenshot_id = _parse_screenshot_id(d.pop("screenshot_id"))
+
+        def _parse_recording_id(data: object) -> Union[None, str]:
+            if data is None:
+                return data
+            return cast(Union[None, str], data)
+
+        recording_id = _parse_recording_id(d.pop("recording_id"))
+
+        def _parse_bulk_id(data: object) -> Union[None, str]:
+            if data is None:
+                return data
+            return cast(Union[None, str], data)
+
+        bulk_id = _parse_bulk_id(d.pop("bulk_id"))
+
+        def _parse_monitor_id(data: object) -> Union[None, str]:
+            if data is None:
+                return data
+            return cast(Union[None, str], data)
+
+        monitor_id = _parse_monitor_id(d.pop("monitor_id"))
+
+        def _parse_scrape_id(data: object) -> Union[None, str]:
+            if data is None:
+                return data
+            return cast(Union[None, str], data)
+
+        scrape_id = _parse_scrape_id(d.pop("scrape_id"))
+
+        webhook_delivery_response = cls(
+            id=id,
+            event_type=event_type,
+            target_url=target_url,
+            status=status,
+            attempts=attempts,
+            max_attempts=max_attempts,
+            next_attempt_at=next_attempt_at,
+            response_status=response_status,
+            response_ms=response_ms,
+            created_at=created_at,
+            delivered_at=delivered_at,
+            screenshot_id=screenshot_id,
+            recording_id=recording_id,
+            bulk_id=bulk_id,
+            monitor_id=monitor_id,
+            scrape_id=scrape_id,
+        )
+
+        webhook_delivery_response.additional_properties = d
+        return webhook_delivery_response
+
+    @property
+    def additional_keys(self) -> list[str]:
+        return list(self.additional_properties.keys())
+
+    def __getitem__(self, key: str) -> Any:
+        return self.additional_properties[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.additional_properties[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        del self.additional_properties[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.additional_properties

bytekit/models/webhook_delivery_response_event_type.py

@@ -0,0 +1,14 @@
+from enum import Enum
+
+
+class WebhookDeliveryResponseEventType(str, Enum):
+    BULK_COMPLETED = "bulk.completed"
+    MONITOR_CAPTURED = "monitor.captured"
+    MONITOR_CHANGE_DETECTED = "monitor.change_detected"
+    SCRAPE_COMPLETED = "scrape.completed"
+    SCRAPE_FAILED = "scrape.failed"
+    SITEMAP_COMPLETED = "sitemap.completed"
+    SITEMAP_FAILED = "sitemap.failed"
+
+    def __str__(self) -> str:
+        return str(self.value)

bytekit/models/webhook_delivery_response_status.py

@@ -0,0 +1,11 @@
+from enum import Enum
+
+
+class WebhookDeliveryResponseStatus(str, Enum):
+    DELIVERED = "delivered"
+    EXHAUSTED = "exhausted"
+    FAILED = "failed"
+    PENDING = "pending"
+
+    def __str__(self) -> str:
+        return str(self.value)

bytekit/types.py

@@ -0,0 +1,54 @@
+"""Contains some shared types for properties"""
+
+from collections.abc import Mapping, MutableMapping
+from http import HTTPStatus
+from typing import IO, BinaryIO, Generic, Literal, Optional, TypeVar, Union
+
+from attrs import define
+
+
+class Unset:
+    def __bool__(self) -> Literal[False]:
+        return False
+
+
+UNSET: Unset = Unset()
+
+# The types that `httpx.Client(files=)` can accept, copied from that library.
+FileContent = Union[IO[bytes], bytes, str]
+FileTypes = Union[
+    # (filename, file (or bytes), content_type)
+    tuple[Optional[str], FileContent, Optional[str]],
+    # (filename, file (or bytes), content_type, headers)
+    tuple[Optional[str], FileContent, Optional[str], Mapping[str, str]],
+]
+RequestFiles = list[tuple[str, FileTypes]]
+
+
+@define
+class File:
+    """Contains information for file uploads"""
+
+    payload: BinaryIO
+    file_name: Optional[str] = None
+    mime_type: Optional[str] = None
+
+    def to_tuple(self) -> FileTypes:
+        """Return a tuple representation that httpx will accept for multipart/form-data"""
+        return self.file_name, self.payload, self.mime_type
+
+
+T = TypeVar("T")
+
+
+@define
+class Response(Generic[T]):
+    """A response from an endpoint"""
+
+    status_code: HTTPStatus
+    content: bytes
+    headers: MutableMapping[str, str]
+    parsed: Optional[T]
+
+
+__all__ = ["UNSET", "File", "FileTypes", "RequestFiles", "Response", "Unset"]

bytekit_sdk-0.3.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: bytekit-sdk
+Version: 0.3.0
+Summary: Official Python SDK for the ByteKit API
+Project-URL: Homepage, https://bytekit.com
+Project-URL: Repository, https://github.com/Hunt-Labs-Inc/ByteKit
+Project-URL: Documentation, https://bytekit.com/docs
+License-Expression: MIT
+Keywords: api,bytekit,crawler,llm,markdown,scraping,screenshots,sdk,web-scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: attrs>=23.1.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: python-dateutil>=2.8.0
+Description-Content-Type: text/markdown
+
+# bytekit-sdk
+
+Official Python SDK for the [ByteKit API](https://bytekit.com).
+
+The PyPI **distribution** is `bytekit-sdk`; the **import** name is `bytekit`.
+
+Generated from the OpenAPI spec using [openapi-python-client](https://github.com/openapi-generators/openapi-python-client), filtered to the stable v0.1 operations.
+
+## Installation
+
+```bash
+pip install bytekit-sdk
+```
+
+## Quick start
+
+```python
+from bytekit import AuthenticatedClient
+from bytekit.api.scrape import create_scrape
+from bytekit.errors import UnexpectedStatus
+from bytekit.models.scrape_request import ScrapeRequest
+
+# base_url defaults to https://api.bytekit.com, so only the token is required.
+client = AuthenticatedClient(token="sk_live_your_api_key_here")
+
+body = ScrapeRequest(url="https://example.com")
+
+try:
+    response = create_scrape.sync(client=client, body=body)
+    # response.formats.markdown is str | Unset — only present when "markdown" was requested
+    print(response.formats.markdown)
+except UnexpectedStatus as err:
+    # Errors now raise loudly by default instead of returning None.
+    print(f"request failed with status {err.status_code}: {err.code} {err.message}")
+```
+
+### Defaults
+
+The client ships with production-ready defaults so `AuthenticatedClient(token=...)` works out of the box:
+
+| Setting                      | Default                         | Notes                                                                                                                                                           |
+| ---------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `base_url`                   | `https://api.bytekit.com`       | Pass `base_url=` to target staging or a proxy.                                                                                                                  |
+| `timeout`                    | `120s` (`httpx.Timeout(120.0)`) | Finite by default — requests no longer hang indefinitely. Pass `timeout=` to override.                                                                          |
+| `raise_on_unexpected_status` | `True`                          | Undocumented statuses raise `errors.UnexpectedStatus` instead of silently returning `None`. Pass `raise_on_unexpected_status=False` to restore the old opt-out. |
+
+Explicit constructor arguments always win over these defaults (explicit arg > default).
+
+## Async usage
+
+```python
+import asyncio
+from bytekit import AuthenticatedClient
+from bytekit.api.screenshots import create_screenshot
+from bytekit.models.screenshot_request import ScreenshotRequest
+
+async def main():
+    client = AuthenticatedClient(token="sk_live_your_api_key_here")
+    body = ScreenshotRequest(url="https://example.com")
+    response = await create_screenshot.asyncio(client=client, body=body)
+    print(response)
+
+asyncio.run(main())
+```
+
+## Available operations
+
+| Module            | Method                                                                                                        | Description                                |
+| ----------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| `api.scrape`      | `create_scrape`, `get_scrape`                                                                                 | Web content extraction                     |
+| `api.screenshots` | `create_screenshot`, `get_screenshot`                                                                         | Page screenshots                           |
+| `api.bulk`        | `create_bulk`, `get_bulk`, `delete_bulk`, `list_bulk_screenshots`                                             | Bulk screenshot jobs                       |
+| `api.scrape_bulk` | `create_scrape_bulk`, `get_scrape_bulk`                                                                       | Bulk scrape jobs                           |
+| `api.fetch`       | `get_fetch`, `post_fetch`                                                                                     | Raw HTTP fetch                             |
+| `api.fetch_bulk`  | `create_fetch_bulk`, `get_fetch_bulk`                                                                         | Bulk fetch jobs                            |
+| `api.monitors`    | `create_monitor`, `list_monitors`, `get_monitor`, `update_monitor`, `delete_monitor`, `list_monitor_captures` | Page-change monitors (screenshot + scrape) |
+| `api.sitemap`     | `create_sitemap`, `get_sitemap`                                                                               | Sitemap crawl                              |
+| `api.search`      | `create_search` (or the `AuthenticatedClient.search(...)` convenience method)                                 | Web search                                 |
+| `api.usage`       | `get_usage`, `get_usage_daily`, `get_usage_by_endpoint`                                                       | Account usage & billing                    |
+| `api.webhooks`    | `list_webhook_deliveries`, `retry_webhook_delivery`                                                           | Webhook delivery log & retry               |
+| `api.account`     | `get_account`                                                                                                 | Account details                            |
+
+## Regenerating
+
+To regenerate the client after API changes:
+
+```bash
+pnpm --filter @bytekit/sdk-python generate
+```
+
+This runs `scripts/filter-spec.ts` to produce `filtered-openapi.yaml` (filtered to v0.1 operations), runs `scripts/prune-stale-api.py` to delete any `src/bytekit/api/<tag>/` directory the filtered spec no longer produces (`generate --overwrite` itself already rebuilds `api/` from scratch on every run, so this step is defense-in-depth for a standalone run of the prune script or a future generator version — the path that actually needs the guard is `pnpm generate:docs`, which enumerates `api/` on disk independent of `generate` and can otherwise resurrect a tag whose tracked files were `git rm`-ed but whose untracked `__pycache__/` survives; see `scripts/prune-stale-api.py`'s module docstring and `has_operations()` in `scripts/generate-docs.py`), invokes `openapi-python-client generate` to update `src/bytekit/`, then runs `scripts/inject-handwritten.py` to re-append hand-written fragments (e.g. the `AuthenticatedClient.search()` convenience method) from `scripts/hand_written/` and re-patch the generated `client.py`/`errors.py` with the runtime defaults and error enrichment described above — because `--overwrite` overwrites every file it emits, both the hand-written code and these patches are wiped on every regen and must be re-applied afterward.
+
+## Development
+
+```bash
+# Run tests
+cd packages/sdk-python
+python3 -m pytest tests/ -v
+```
+
+## Publishing
+
+PyPI publish is handled in [#2226](https://github.com/Hunt-Labs-Inc/ByteKit/issues/2226) —
+`.woodpecker/publish.yaml`'s `publish-pypi` step, version-gated the same way as the npm
+siblings (publishes only when the local `pyproject.toml` version differs from what's live on
+PyPI).
+
+**`bytekit-sdk` has never been published.** Before the commit that arms
+`packages/sdk-python/pyproject.toml` in `publish.yaml`'s workflow-level `when.path.include` is
+promoted from `staging` to `main`, an operator MUST publish `0.3.0` to PyPI manually and under
+supervision. Reason: bytekit-sdk 404s on PyPI today, so the automatic version-compare gate's
+`|| echo "0.0.0"` fallback always fires — the first time that arming reaches `main`, it would
+trigger a real, irreversible first `twine upload` with no manual confirmation step in between.
+Once the manual first release exists, PUBLISHED == CURRENT and every later automatic run at an
+unchanged version is a no-op, same as the npm packages. See the comment at the armed
+`when.path.include` entry in `.woodpecker/publish.yaml` for the mechanism.