robovue-sdk 0.2.0__py3-none-any.whl

robovue_sdk/__init__.py

@@ -0,0 +1,13 @@
+from .client import RobovueClient
+from .exceptions import RobovueApiException
+from .models import FailureCategory, RunReport, RunReportOutcome, RunReportResult, RunStatus
+
+__all__ = [
+    "RobovueClient",
+    "RunReport",
+    "RunReportResult",
+    "RunReportOutcome",
+    "RunStatus",
+    "FailureCategory",
+    "RobovueApiException",
+]

robovue_sdk/_signature.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+
+RUN_PURPOSE = "run"
+ATTACHMENT_PURPOSE = "attachment"
+
+
+def compute_v1(secret: str, timestamp: str, purpose: str, subject: str, raw_body: bytes) -> str:
+    """The v1 request signature (ADR 0161).
+
+    HMAC-SHA256, keyed with the UTF-8-encoded secret, of ``{timestamp}\\n{purpose}\\n{subject}\\n``
+    (ASCII) followed by the raw body bytes, hex-encoded in lowercase and prefixed with "v1=". The
+    purpose is "run" or "attachment"; the subject is the delivery id for a run report and the run id
+    (lowercase, hyphenated) for an attachment.
+
+    An independent reimplementation of the server's WebhookSignature.ComputeV1 and Robovue.Sdk's
+    SignatureCalculator.ComputeV1 — all three are tested against sdks/contract/signature-vectors.json.
+    """
+    message = f"{timestamp}\n{purpose}\n{subject}\n".encode("ascii") + raw_body
+    digest = hmac.new(secret.encode("utf-8"), message, hashlib.sha256).hexdigest()
+    return f"v1={digest}"

robovue_sdk/_transport.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import time
+import urllib.error
+import urllib.request
+import email.utils
+from typing import Any, Callable, Dict, Mapping, Optional, Tuple, Union
+
+# (url, headers, body) -> (status_code, response_body_bytes[, response_headers]).
+# Raises OSError (or a subclass, e.g. urllib.error.URLError/socket.timeout)
+# for a network-level failure — never for a real HTTP response, even a 4xx/5xx one.
+# The third element is optional so existing custom transports keep working; without it a 429's
+# Retry-After can't be read and the normal backoff applies instead.
+Transport = Callable[[str, Dict[str, str], bytes], Tuple[Any, ...]]
+
+#: The longest Retry-After worth waiting for inside a bot's run. A server asking for longer is
+#: answered with the 429 itself, so the caller decides - a bot blocked for minutes on its
+#: monitoring is worse than a report that arrives late or not at all.
+MAX_RETRY_AFTER_SECONDS = 60.0
+
+
+def retry_after_seconds(headers: Optional[Mapping[str, str]], now: Optional[float] = None) -> Optional[float]:
+    """How long a 429 asks to wait: Retry-After as seconds or as an HTTP date, or None."""
+    if not headers:
+        return None
+    value = next((v for k, v in headers.items() if k.lower() == "retry-after"), None)
+    if value is None:
+        return None
+    value = value.strip()
+    if value.isdigit():
+        return float(value)
+    try:
+        when = email.utils.parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if when is None:
+        return None
+    current = time.time() if now is None else now
+    return max(0.0, when.timestamp() - current)
+
+
+def urllib_transport(url: str, headers: Dict[str, str], body: bytes) -> Tuple[int, bytes]:
+    request = urllib.request.Request(url, data=body, headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            return response.status, response.read(), dict(response.headers.items())
+    except urllib.error.HTTPError as error:
+        # urlopen raises for any non-2xx status; treat it as a normal response
+        # so the retry loop can apply the same status-code policy either way.
+        return error.code, error.read(), dict(error.headers.items()) if error.headers else {}
+
+
+def send_with_retry(
+    transport: Transport,
+    url: str,
+    headers: Union[Dict[str, str], Callable[[], Dict[str, str]]],
+    body: bytes,
+    max_attempts: int,
+    base_delay: float,
+    sleep: Callable[[float], None] = time.sleep,
+) -> Tuple[int, bytes]:
+    """Mirrors Robovue.Sdk's RetryingRequestSender exactly.
+
+    Most 4xx responses never retry. A 429 retries after its Retry-After (seconds or an HTTP date),
+    unless that's longer than MAX_RETRY_AFTER_SECONDS. 5xx responses retry until attempts are
+    exhausted. A network-level failure retries the same way, and — unlike a
+    5xx — is re-raised as-is (not wrapped) once attempts are exhausted.
+
+    ``headers`` may be a callable, called once per attempt: signed requests (ADR 0161) carry a
+    timestamp the server rejects after five minutes, so each attempt is signed afresh.
+    """
+    for attempt in range(1, max_attempts + 1):
+        attempt_headers = headers() if callable(headers) else headers
+        try:
+            result = transport(url, attempt_headers, body)
+        except OSError:
+            if attempt < max_attempts:
+                sleep(base_delay * (2 ** (attempt - 1)))
+                continue
+            raise
+        status, response_body = result[0], result[1]
+        response_headers = result[2] if len(result) > 2 else None
+        if attempt == max_attempts:
+            return status, response_body, response_headers
+        if status == 429:
+            wait = retry_after_seconds(response_headers)
+            if wait is None:
+                wait = base_delay * (2 ** (attempt - 1))
+            if wait > MAX_RETRY_AFTER_SECONDS:
+                return status, response_body, response_headers
+            sleep(wait)
+            continue
+        if status < 500:
+            return status, response_body, response_headers
+        sleep(base_delay * (2 ** (attempt - 1)))
+
+    raise AssertionError("unreachable")  # pragma: no cover

robovue_sdk/_version.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("robovue-sdk")
+except PackageNotFoundError:  # running from a source checkout, not an installed package
+    __version__ = "0.0.0+local"
+
+# Sent on every request. Robovue's edge (Cloudflare) blocks urllib's default
+# "Python-urllib/x.y" User-Agent outright with a 403 before the request ever reaches the
+# API, so this is not cosmetic - without it the SDK cannot talk to production at all, and
+# because a 403 is a 4xx it would never be retried.
+USER_AGENT = f"robovue-sdk-python/{__version__}"

robovue_sdk/client.py

@@ -0,0 +1,308 @@
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Optional
+
+from . import _signature
+from ._transport import Transport, send_with_retry, urllib_transport
+from ._version import USER_AGENT
+from .exceptions import RobovueApiException
+from .models import FailureCategory, RunReport, RunReportOutcome, RunReportResult, RunStatus
+
+# The server's limits (the Connect page's contract reference, ADR 0160), checked here so a mistake
+# fails locally with a clear message instead of costing a round trip and a 400.
+_MAX_BOT_ID_LENGTH = 200
+_MAX_PLATFORM_LENGTH = 50
+_MAX_DELIVERY_ID_LENGTH = 200
+_MAX_REPORT_BYTES = 64 * 1024
+_EARLIEST = datetime(2000, 1, 1, tzinfo=timezone.utc)
+
+
+def _format_datetime(value: datetime) -> str:
+    # This app has no per-user timezone preference anywhere (server-side
+    # timestamps are UTC throughout) — a naive datetime is treated as
+    # already being UTC rather than rejected, matching that same convention.
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _serialize(report: RunReport) -> bytes:
+    status_value = report.status.value if isinstance(report.status, RunStatus) else report.status
+    obj: dict[str, Any] = {
+        "botId": report.bot_id,
+        "platform": report.platform,
+        "status": status_value,
+        "startedAt": _format_datetime(report.started_at),
+    }
+    # Omitted entirely rather than sent as null when the run is in flight (ADR 0072), which makes a
+    # start ping a strict subset of the terminal shape and satisfies the server's "completedAt must
+    # be omitted when status is Running" rule by construction. Same treatment payload and
+    # failure_category already get below.
+    if report.completed_at is not None:
+        obj["completedAt"] = _format_datetime(report.completed_at)
+    if report.payload is not None:
+        obj["payload"] = report.payload
+    if report.failure_category is not None:
+        category_value = (
+            report.failure_category.value
+            if isinstance(report.failure_category, FailureCategory)
+            else report.failure_category
+        )
+        obj["failureCategory"] = category_value
+    # Compact, no whitespace - the exact bytes produced here are what gets
+    # signed, so any serializer choice is self-consistent as long as it's
+    # applied before signing and never re-applied afterward.
+    # allow_nan=False: NaN and Infinity aren't JSON, and the server rejects the whole body for them.
+    try:
+        encoded = json.dumps(obj, separators=(",", ":"), allow_nan=False).encode("utf-8")
+    except ValueError as exc:
+        raise ValueError("payload can't contain NaN or Infinity - they aren't valid JSON") from exc
+    if len(encoded) > _MAX_REPORT_BYTES:
+        raise ValueError(f"the report is {len(encoded)} bytes; the limit is {_MAX_REPORT_BYTES} - make payload smaller")
+    return encoded
+
+
+def _as_utc(value: datetime) -> datetime:
+    # The same rule _format_datetime applies: a naive datetime is UTC. Comparing through this avoids
+    # Python's TypeError on a naive/aware mix.
+    return value.replace(tzinfo=timezone.utc) if value.tzinfo is None else value
+
+
+def _validate_name(value: Any, name: str, max_length: int) -> None:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{name} is required")
+    if len(value) > max_length:
+        raise ValueError(f"{name} must be {max_length} characters or fewer")
+    if value != value.strip():
+        raise ValueError(f"{name} must not start or end with whitespace")
+    if any(ord(c) < 32 or 127 <= ord(c) < 160 for c in value):
+        raise ValueError(f"{name} must not contain control characters")
+
+
+def _validate(report: RunReport) -> None:
+    if report is None:
+        raise ValueError("report is required")
+    _validate_name(report.bot_id, "bot_id", _MAX_BOT_ID_LENGTH)
+    # A bot id is part of the Management API's URLs, so it can't hold a path separator (server ADR 0166).
+    if "/" in report.bot_id or "\\" in report.bot_id:
+        raise ValueError("bot_id must not contain / or \\")
+    if report.bot_id in (".", ".."):
+        raise ValueError('bot_id must not be "." or ".."')
+    _validate_name(report.platform, "platform", _MAX_PLATFORM_LENGTH)
+
+    status = report.status.value if isinstance(report.status, RunStatus) else report.status
+    if status not in {s.value for s in RunStatus}:
+        raise ValueError(f"status must be one of: {', '.join(s.value for s in RunStatus)}")
+
+    if not isinstance(report.started_at, datetime):
+        raise ValueError("started_at is required")
+    started = _as_utc(report.started_at)
+    if started < _EARLIEST:
+        raise ValueError("started_at can't be before 2000-01-01")
+
+    if report.failure_category is not None:
+        category = report.failure_category.value if isinstance(report.failure_category, FailureCategory) else report.failure_category
+        if category not in {c.value for c in FailureCategory}:
+            raise ValueError(f"failure_category must be one of: {', '.join(c.value for c in FailureCategory)}")
+        if status != RunStatus.FAILURE.value:
+            raise ValueError("failure_category can only be set when status is FAILURE")
+
+    if report.payload is not None and not isinstance(report.payload, dict):
+        raise ValueError("payload must be a dict (a JSON object)")
+
+    if status == RunStatus.RUNNING.value:
+        if report.completed_at is not None:
+            raise ValueError("completed_at must be None when status is RUNNING")
+        return
+
+    if report.completed_at is None:
+        raise ValueError("completed_at is required unless status is RUNNING")
+    if _as_utc(report.completed_at) < started:
+        raise ValueError("completed_at must be >= started_at")
+
+
+def _error_from(status: int, response_body: bytes, response_headers: Optional[Dict[str, str]]) -> RobovueApiException:
+    parsed: Dict[str, Any] = {}
+    try:
+        decoded = json.loads(response_body)
+        if isinstance(decoded, dict):
+            parsed = decoded
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        pass  # Not the error envelope - e.g. a proxy's HTML page.
+    request_id = parsed.get("requestId")
+    if request_id is None and response_headers:
+        request_id = next((v for k, v in response_headers.items() if k.lower() == "x-request-id"), None)
+    return RobovueApiException(status, parsed.get("error"), parsed.get("code"), parsed.get("field"), request_id)
+
+
+class RobovueClient:
+    """Client for Robovue's generic ingestion webhook (POST /ingest/{tenantId}/runs)."""
+
+    def __init__(
+        self,
+        base_url: str,
+        tenant_id: str,
+        webhook_secret: str,
+        *,
+        max_retry_attempts: int = 3,
+        retry_base_delay: float = 0.2,
+        transport: Transport = urllib_transport,
+        clock: Callable[[], float] = time.time,
+        dry_run: bool = False,
+    ) -> None:
+        """``dry_run=True`` sends every request as a dry run (``X-Robovue-Dry-Run: true``): Robovue
+        authenticates and validates it exactly as normal but stores nothing, and a report's result
+        says what ``would_be``. A request that would fail still raises the real error. For checking
+        a new integration - leave it off in production, or no runs are recorded."""
+        if not base_url:
+            raise ValueError("base_url is required")
+        if not tenant_id:
+            raise ValueError("tenant_id is required")
+        if not webhook_secret:
+            raise ValueError("webhook_secret is required")
+        if max_retry_attempts < 1:
+            raise ValueError("max_retry_attempts must be >= 1")
+
+        self._ingest_base_url = f"{str(base_url).rstrip('/')}/ingest/{tenant_id}"
+        self._url = f"{self._ingest_base_url}/runs"
+        self._webhook_secret = webhook_secret
+        self._max_retry_attempts = max_retry_attempts
+        self._retry_base_delay = retry_base_delay
+        self._transport = transport
+        # Seconds since the epoch; replaceable so tests can pin a signature and prove retries re-sign.
+        self._clock = clock
+        self._dry_run = dry_run
+
+    def _signed_headers(self, base: Dict[str, str], purpose: str, subject: str, body: bytes) -> Callable[[], Dict[str, str]]:
+        """Headers for one attempt, signed with the current time (ADR 0161)."""
+
+        def build() -> Dict[str, str]:
+            timestamp = str(int(self._clock()))
+            headers = dict(base)
+            headers["X-Robovue-Timestamp"] = timestamp
+            headers["X-Robovue-Signature"] = _signature.compute_v1(self._webhook_secret, timestamp, purpose, subject, body)
+            if self._dry_run:
+                headers["X-Robovue-Dry-Run"] = "true"
+            return headers
+
+        return build
+
+    def report_run(self, report: RunReport, delivery_id: Optional[str] = None) -> RunReportResult:
+        _validate(report)
+
+        body = _serialize(report)
+        effective_delivery_id = (
+            delivery_id if delivery_id and delivery_id.strip() else str(uuid.uuid4())
+        )
+        # Checked here rather than left to the server: a proxy or the server trims header whitespace,
+        # so an id with a space at either end would be signed one way and verified another.
+        if any(not ("!" <= c <= "~") for c in effective_delivery_id):
+            raise ValueError("delivery_id may only contain printable ASCII characters, with no spaces")
+        if len(effective_delivery_id) > _MAX_DELIVERY_ID_LENGTH:
+            raise ValueError(f"delivery_id must be {_MAX_DELIVERY_ID_LENGTH} characters or fewer")
+
+        headers = self._signed_headers(
+            {
+                "Content-Type": "application/json",
+                "User-Agent": USER_AGENT,
+                "X-Robovue-Delivery-Id": effective_delivery_id,
+            },
+            _signature.RUN_PURPOSE,
+            effective_delivery_id,
+            body,
+        )
+
+        status, response_body, response_headers = send_with_retry(
+            self._transport,
+            self._url,
+            headers,
+            body,
+            self._max_retry_attempts,
+            self._retry_base_delay,
+        )
+
+        if status in (200, 201):
+            try:
+                parsed = json.loads(response_body)
+                if parsed.get("dryRun") is True:
+                    would_be = parsed.get("wouldBe")
+                    return RunReportResult(
+                        run_id="",
+                        duplicate=would_be == "duplicate",
+                        delivery_id=effective_delivery_id,
+                        dry_run=True,
+                        would_be=would_be,
+                    )
+                return RunReportResult(
+                    run_id=str(parsed["runId"]),
+                    duplicate=bool(parsed["duplicate"]),
+                    delivery_id=effective_delivery_id,
+                )
+            except (json.JSONDecodeError, KeyError, TypeError, UnicodeDecodeError) as exc:
+                raise RobovueApiException(status, "response body could not be parsed") from exc
+
+        raise _error_from(status, response_body, response_headers)
+
+    def try_report_run(self, report: RunReport, delivery_id: Optional[str] = None) -> RunReportOutcome:
+        """Reports a run without ever raising - for bots where monitoring must not become a new way
+        to fail. Any problem (an invalid report, a rejection, a network failure) comes back in the
+        outcome's ``error``; log it."""
+        try:
+            return RunReportOutcome(result=self.report_run(report, delivery_id))
+        except Exception as exc:  # noqa: BLE001 - deliberately broad: the promise is that reporting can't break the bot
+            return RunReportOutcome(error=exc)
+
+    # 5MB (ADR 0045) — matches the server's own cap exactly; checked here before any HTTP call so
+    # an oversized upload fails fast with a clear local exception instead of a round trip.
+    _MAX_ATTACHMENT_BYTES = 5 * 1024 * 1024
+
+    def upload_attachment(self, run_id: str, content: bytes, content_type: str) -> None:
+        """Attaches a screenshot or log excerpt to a failed run.
+
+        Only accepted for a run whose status is Failure, on a bot with attachments turned on
+        (Manage bots, then Screenshots, in the dashboard) — off by default, since a
+        screenshot can capture on-screen credentials or other sensitive data. content_type
+        must be one of "image/png", "image/jpeg", "text/plain"; content must be 5MB or
+        smaller (checked here before any HTTP call, and again server-side). Retries network
+        errors and 5xx responses automatically; raises RobovueApiException for any other
+        non-success response.
+        """
+        if not content:
+            raise ValueError("content is required")
+        if len(content) > self._MAX_ATTACHMENT_BYTES:
+            raise ValueError(f"content must be {self._MAX_ATTACHMENT_BYTES} bytes or fewer")
+        if not content_type or not content_type.strip():
+            raise ValueError("content_type is required")
+
+        # Canonicalised once and used for both the URL and the signature: the server parses the id
+        # from the URL and signs its lowercase hyphenated form, so a braced or unhyphenated id sent
+        # as-is would be signed differently from how it's verified.
+        try:
+            canonical_run_id = str(uuid.UUID(str(run_id)))
+        except ValueError as exc:
+            raise ValueError("run_id must be a run id (a UUID) returned by report_run") from exc
+        url = f"{self._ingest_base_url}/runs/{canonical_run_id}/attachment"
+        headers = self._signed_headers(
+            {"Content-Type": content_type, "User-Agent": USER_AGENT},
+            _signature.ATTACHMENT_PURPOSE,
+            canonical_run_id,
+            content,
+        )
+
+        status, response_body, response_headers = send_with_retry(
+            self._transport,
+            url,
+            headers,
+            content,
+            self._max_retry_attempts,
+            self._retry_base_delay,
+        )
+
+        if 200 <= status < 300:
+            return
+
+        raise _error_from(status, response_body, response_headers)

robovue_sdk/exceptions.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class RobovueApiException(Exception):
+    """Raised for any non-2xx (or unparseable-2xx) response from the ingestion endpoint.
+
+    Branch on ``code``, which is stable, rather than on the message, which is for people. The full
+    list of codes, with what to do about each, is on the Connect page and in the README.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        server_error_message: Optional[str] = None,
+        code: Optional[str] = None,
+        field: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        self.status_code = status_code
+        self.server_error_message = server_error_message
+        #: The stable error code, e.g. "invalid_field" or "timestamp_out_of_range".
+        self.code = code
+        #: The request field the error is about, when there is exactly one.
+        self.field = field
+        #: The request's id - quote it if you contact support.
+        self.request_id = request_id
+
+        message = f"Robovue ingestion endpoint returned {status_code}"
+        if code:
+            message += f" ({code})"
+        if server_error_message:
+            message += f": {server_error_message}"
+        if request_id:
+            message += f" [request {request_id}]"
+        super().__init__(message + ".")

robovue_sdk/models.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Any, Optional
+
+
+class RunStatus(str, Enum):
+    """Serializes to the literal wire value Robovue expects — not camelCased."""
+
+    SUCCESS = "Success"
+    FAILURE = "Failure"
+
+    #: The run has started and has not finished. Report it with ``completed_at`` left as None,
+    #: then report the same run again with its real outcome and completion time, reusing the SAME
+    #: delivery id - that is what tells Robovue the two calls are one run rather than two.
+    RUNNING = "Running"
+
+
+class FailureCategory(str, Enum):
+    """Why a run failed, if known — optional, only meaningful when status is FAILURE. Robovue
+    defaults to UNCATEGORIZED when omitted; a run can always be reclassified later from its
+    detail page."""
+
+    UNCATEGORIZED = "Uncategorized"
+    BUSINESS_EXCEPTION = "BusinessException"
+    APPLICATION_EXCEPTION = "ApplicationException"
+    TIMEOUT = "Timeout"
+    AUTHENTICATION_ERROR = "AuthenticationError"
+    CANCELLED = "Cancelled"
+
+
+@dataclass
+class RunReport:
+    bot_id: str
+    platform: str
+    status: RunStatus
+    started_at: datetime
+
+    #: None while the run is in flight, i.e. status RUNNING (ADR 0072). Gaining a default does not
+    #: move it: the two fields below it already had defaults, so positional construction of every
+    #: existing call site is unchanged.
+    completed_at: Optional[datetime] = None
+    payload: Optional[Any] = None
+    failure_category: Optional[FailureCategory] = None
+
+
+@dataclass(frozen=True)
+class RunReportResult:
+    run_id: str
+    duplicate: bool
+
+    #: The delivery id the report was sent with - the one you passed, or the one generated for you.
+    #: Pass it to the call that completes a RUNNING run: reusing it is what makes the two calls one run.
+    delivery_id: str = ""
+
+    #: True when the report was sent as a dry run (``dry_run=True`` on the client) and nothing was
+    #: stored. ``run_id`` is then empty.
+    dry_run: bool = False
+
+    #: For a dry run, what the report would have done: "created", "completed" (it completes a
+    #: RUNNING run) or "duplicate". None otherwise.
+    would_be: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class RunReportOutcome:
+    """What ``try_report_run`` returns: the result, or why the report failed - never an exception,
+    so a monitoring problem can't break the bot it's monitoring."""
+
+    result: Optional[RunReportResult] = None
+
+    #: A ValueError for an invalid report, a RobovueApiException for a rejection, or a network
+    #: error (OSError). Log it.
+    error: Optional[BaseException] = None
+
+    @property
+    def succeeded(self) -> bool:
+        return self.result is not None

robovue_sdk-0.2.0.dist-info/METADATA

@@ -0,0 +1,429 @@
+Metadata-Version: 2.5
+Name: robovue-sdk
+Version: 0.2.0
+Summary: Report RPA and scripted bot runs to Robovue: signed requests, retries, checks before sending and dry runs.
+Project-URL: Homepage, https://robovue.co.uk
+Project-URL: Documentation, https://robovue.co.uk/api
+Author: Robovue
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automation,bots,monitoring,robovue,rpa,webhook
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# robovue-sdk
+
+Report your bots' runs to [Robovue](https://robovue.co.uk), which watches every bot in one place and
+tells you when one fails or doesn't run. This package signs each report, retries when the network
+or Robovue has a problem, checks a report against Robovue's rules before sending it, and can send
+dry runs while you set it up. It uses only Python's standard library.
+
+## Install
+
+```shell
+pip install robovue-sdk
+```
+
+## Requirements
+
+- Python 3.9 or later, on any operating system. No other packages.
+- A Robovue workspace. Signing up is free.
+
+Can't install a package where your bot runs, such as Power Automate Desktop's built-in Python?
+Connections → HTTP API in Robovue gives you the same request as plain Python, C# and shell code to
+paste in, and the [wire contract](#the-wire-contract-any-language) below describes it for any
+language.
+
+## Quickstart
+
+1. **Sign up** at [robovue.co.uk](https://robovue.co.uk).
+2. **Copy your credentials** from **Settings → Connections → HTTP API**: the webhook secret, and
+   your tenant ID, which is the long id in the address shown there
+   (`https://app.robovue.co.uk/ingest/<tenant ID>/runs`).
+3. **Keep them out of your code.** Set them as environment variables on the machine that runs the
+   bot, `ROBOVUE_TENANT_ID` and `ROBOVUE_WEBHOOK_SECRET`, or in your platform's credential store,
+   and create one client:
+
+<!-- sample:begin imports create-client -->
+```python
+import os
+import uuid
+from datetime import datetime, timezone
+
+from robovue_sdk import FailureCategory, RobovueApiException, RobovueClient, RunReport, RunStatus
+
+# One client for the whole process: it's safe to share between threads.
+robovue = RobovueClient(
+    base_url="https://app.robovue.co.uk",
+    tenant_id=os.environ["ROBOVUE_TENANT_ID"],
+    webhook_secret=os.environ["ROBOVUE_WEBHOOK_SECRET"],
+)
+```
+<!-- sample:end -->
+
+4. **Wrap your bot's job.** Report the run as `RUNNING` when it starts, then as `SUCCESS` or
+   `FAILURE` when it ends, with the same delivery id so Robovue knows it's one run:
+
+<!-- sample:begin quickstart -->
+```python
+delivery_id = str(uuid.uuid4())  # one per run: it ties the run's reports together
+started_at = datetime.now(timezone.utc)
+
+robovue.try_report_run(
+    RunReport(
+        bot_id="invoice-bot-01",
+        platform="python",
+        status=RunStatus.RUNNING,
+        started_at=started_at,
+    ),
+    delivery_id=delivery_id,
+)
+
+try:
+    process_invoices()  # your bot's work
+except Exception as exc:
+    robovue.try_report_run(
+        RunReport(
+            bot_id="invoice-bot-01",
+            platform="python",
+            status=RunStatus.FAILURE,
+            started_at=started_at,
+            completed_at=datetime.now(timezone.utc),
+            failure_category=FailureCategory.APPLICATION_EXCEPTION,
+            payload={"error": str(exc)},
+        ),
+        delivery_id=delivery_id,
+    )
+    raise
+
+robovue.try_report_run(
+    RunReport(
+        bot_id="invoice-bot-01",
+        platform="python",
+        status=RunStatus.SUCCESS,
+        started_at=started_at,
+        completed_at=datetime.now(timezone.utc),
+    ),
+    delivery_id=delivery_id,
+)
+```
+<!-- sample:end -->
+
+   `try_report_run` never raises, so a problem reaching Robovue can't break your bot. The job's own
+   exception is reported, then raised again, so the bot still fails the way it always did.
+
+5. **Check it arrives.** Run the bot once with [`dry_run`](#checking-a-new-integration-with-a-dry-run)
+   on, then for real, and watch the report land in the Verify step on Connections → HTTP API, in the
+   request log, and on Fleet.
+
+## Make missed runs alert
+
+A failure alerts as soon as it's reported. A run that never happens can only be noticed if Robovue
+knows when to expect it, so in **Manage bots**, register the bot (its id is `bot_id`) and give it a
+schedule. Until a bot is registered, its runs appear under **Unregistered ids**, and each new id
+counts toward your plan's bot limit.
+
+## Reporting in more detail
+
+### Failure categories
+
+On a `FAILURE`, set `failure_category` to say why it failed. It's shown on the run, filterable on
+Runs, and named in the alert. Leave it out if you don't know: Robovue records `Uncategorized`, and a
+run can be reclassified later from its page.
+
+<!-- sample:begin failure-category -->
+```python
+result = robovue.report_run(
+    RunReport(
+        bot_id="invoice-bot-01",
+        platform="python",
+        status=RunStatus.FAILURE,
+        started_at=started_at,
+        completed_at=datetime.now(timezone.utc),
+        failure_category=FailureCategory.BUSINESS_EXCEPTION,
+    )
+)
+```
+<!-- sample:end -->
+
+| Category | Use it for |
+|---|---|
+| `BUSINESS_EXCEPTION` | A business rule stopped the run: bad input data, a missing record, a rejected transaction. |
+| `APPLICATION_EXCEPTION` | Something broke in the bot or the application it drives. |
+| `TIMEOUT` | The run, or a step in it, took too long. |
+| `AUTHENTICATION_ERROR` | The bot couldn't sign in to something it needs. |
+| `CANCELLED` | A person or a scheduler stopped the run. |
+| `UNCATEGORIZED` | You don't know. The default. |
+
+### Attaching context with `payload`
+
+`payload` takes any JSON-serialisable value and is stored as sent, shown in full on the run's page.
+Use it for whatever would help you debug the run later: an invoice number, the step that failed, a
+stack trace. If it has an `error`, `errorMessage` or `message` key, the alert uses that text to say
+what went wrong.
+
+<!-- sample:begin payload -->
+```python
+result = robovue.report_run(
+    RunReport(
+        bot_id="invoice-bot-01",
+        platform="python",
+        status=RunStatus.FAILURE,
+        started_at=started_at,
+        completed_at=datetime.now(timezone.utc),
+        failure_category=FailureCategory.TIMEOUT,
+        payload={
+            "invoiceId": "INV-2291",
+            "error": "Timed out waiting for the vendor portal",
+        },
+    )
+)
+```
+<!-- sample:end -->
+
+The whole report, payload included, must be under 64 KB.
+
+### Attaching a screenshot or log to a failed run
+
+On the Team plan and above, you can attach one screenshot or log excerpt to a `FAILURE` run once
+it's reported. Screenshots are off for each bot until someone turns them on (**Manage bots →
+Screenshots**), because a screenshot can capture credentials or other sensitive data on screen.
+
+<!-- sample:begin attachment -->
+```python
+robovue.upload_attachment(result.run_id, screenshot_bytes, "image/png")
+```
+<!-- sample:end -->
+
+`content_type` is `"image/png"`, `"image/jpeg"` or `"text/plain"`, up to 5 MB, one per run. Robovue
+deletes attachments after 30 days, or 7 or 14 if an Admin chose that. An upload for a bot with
+screenshots off, or on a plan without them, gets the same 404 as an unknown run, so catch it if a
+missing screenshot shouldn't fail your bot.
+
+### Reporting without ever raising
+
+Monitoring shouldn't become a new way for a bot to fail. `try_report_run` never raises for a failed
+report: an invalid report, a rejection or a network problem comes back in the outcome for you to log.
+
+<!-- sample:begin try-report -->
+```python
+outcome = robovue.try_report_run(report)
+if not outcome.succeeded:
+    print(f"Couldn't report the run to Robovue: {outcome.error}", file=sys.stderr)
+```
+<!-- sample:end -->
+
+### When a report is rejected
+
+`report_run` raises `RobovueApiException`. Branch on `code`, which is stable; the message is for
+people. `field` names the field at fault when there is one, and `request_id` is worth quoting if you
+contact support.
+
+<!-- sample:begin rejected -->
+```python
+try:
+    robovue.report_run(report)
+except RobovueApiException as exc:
+    if exc.code != "timestamp_out_of_range":
+        raise
+    # This machine's clock is more than 5 minutes out. The message gives Robovue's time.
+    print(exc, file=sys.stderr)
+```
+<!-- sample:end -->
+
+Network errors and 5xx responses are retried automatically (3 attempts by default), and so is a
+`429` after its `Retry-After`, unless that's more than a minute, when the 429 is raised instead of
+blocking your bot. A report is checked against the server's own rules before anything is sent, so
+most mistakes fail at once with a `ValueError`. A `datetime` with no time zone is treated as UTC.
+Every code is in the [responses table](#responses) below, with whether a retry can help.
+
+### Checking a new integration with a dry run
+
+With `dry_run=True`, every request is checked exactly as a real one would be (signature, fields,
+plan limits, delivery id) but nothing is stored. The result says what would have happened, and a
+request that would fail raises the real error.
+
+<!-- sample:begin dry-run -->
+```python
+robovue = RobovueClient(
+    base_url="https://app.robovue.co.uk",
+    tenant_id=tenant_id,
+    webhook_secret=webhook_secret,
+    dry_run=True,  # checked in full, stored nowhere
+)
+
+result = robovue.report_run(report)
+print(result.dry_run, result.would_be)  # True created
+```
+<!-- sample:end -->
+
+Dry runs show in the request log, which warns you if any arrived in the last day, so a bot left in
+dry-run mode doesn't go unnoticed. Turn it off before going live.
+
+### Runs that take a while
+
+The quickstart reports `RUNNING` first. That's optional, but it means a bot that starts a job and
+then hangs shows as Running straight away, rather than only when its next run fails to turn up.
+Reusing the delivery id is the whole mechanism: a fresh id on the second report makes two runs,
+one stuck Running and one that looks like nobody started it. A run left Running silences nothing:
+if it never completes, the bot still goes Late and then Overdue on its schedule.
+
+## Using it in your bot
+
+**One client per process.** `RobovueClient` holds no state between calls, so share one instance
+across threads.
+
+**Timeouts, proxies and TLS.** Each attempt times out after 30 seconds. Requests go through
+Python's `urllib`, so they use the proxy in `HTTPS_PROXY` (or, on Windows, the system's proxy
+settings) and the operating system's trusted certificates; set `SSL_CERT_FILE` to a certificate
+bundle if your network inspects TLS with its own certificate. For anything else, pass
+`transport=`: a function that takes the URL, a dict of headers and the body bytes, sends the POST,
+and returns `(status, response_body, response_headers)`.
+
+## Options
+
+| `RobovueClient(...)` | Default | What it does |
+|---|---|---|
+| `base_url` | required | `https://app.robovue.co.uk` |
+| `tenant_id` | required | Your workspace's tenant ID. |
+| `webhook_secret` | required | Signs every request. Never put it in source code. |
+| `max_retry_attempts` | `3` | Attempts per call, the first included. |
+| `retry_base_delay` | `0.2` | Seconds before the first retry; each later wait doubles. |
+| `dry_run` | `False` | Check every request in full and store nothing. |
+| `transport` | `urllib` | How requests are sent (see above). |
+
+## Troubleshooting
+
+| What you see | What to do |
+|---|---|
+| `invalid_signature` | The secret is wrong or was rotated. Copy the current one from Connections → HTTP API. |
+| `timestamp_out_of_range` | The machine's clock is more than 5 minutes out. Sync it (on Windows, `w32tm /resync`). |
+| `unknown_tenant` | The tenant ID is wrong. Copy it from the address on Connections → HTTP API. |
+| `bot_cap_reached` | A new bot id would go over your plan's bot limit. Delete a bot you no longer use, or change plan. |
+| `payload_too_large` | The report is over 64 KB. Send less in `payload`, and attach a log file instead. |
+| A 403 with no code | Something between your bot and Robovue blocked the request, such as a proxy rewriting it. Check with whoever runs your network, or send us the time it happened. |
+| An `OSError` or `URLError` | The machine can't reach `app.robovue.co.uk`. Check its proxy and firewall. |
+| `CERTIFICATE_VERIFY_FAILED` | Your network inspects TLS. Point `SSL_CERT_FILE` at a bundle that includes its certificate. |
+| The report succeeds but nothing shows on Fleet | `dry_run` is still on, the bot is archived (see **Manage bots → Archived bots**), or the credentials belong to another workspace. |
+| A bot stopped running and nobody was told | It has no schedule. See [Make missed runs alert](#make-missed-runs-alert). |
+
+The request log, in Connections, shows every request from the last 7 days and the exact reason any
+was turned away.
+
+## The wire contract (any language)
+
+This is exactly what `RobovueClient` sends. From a language with no Robovue SDK, send the same
+request yourself. The tables below are generated from the server's own contract, so they list every
+field, header, response and limit, including the optional ones.
+
+<!-- contract:begin — generated from IngestionContract by ContractDocsTests; don't edit by hand -->
+### `POST /ingest/{tenantId}/runs`
+
+The endpoint both SDKs call, and the one to use from any other language. A JSON object with the fields below.
+
+#### Headers
+
+| Header | Value | Description |
+|---|---|---|
+| `Content-Type` | application/json | The body is JSON. A charset parameter is fine. |
+| `X-Robovue-Delivery-Id` | 1–200 printable ASCII characters, no spaces | Unique to this run. Sending it again — a retry, or the Success/Failure that ends a Running run — updates or confirms the same run instead of creating a second one. A GUID, or your bot's own run id, both work. |
+| `X-Robovue-Timestamp` | Unix time in whole seconds | When you signed the request. It must be within 5 minutes of Robovue's clock either way, so a captured request stops working within minutes. Sign each attempt, retries included, just before sending it. |
+| `X-Robovue-Signature` | v1=&lt;lowercase hex&gt; | HMAC-SHA256, keyed with your webhook secret, of the timestamp, the word run, the delivery id — each followed by a line break — then the exact request body; hex-encoded in lowercase and prefixed with v1=. Sign the exact bytes you send: re-serialising the JSON after signing changes them. Several comma-separated v1= values are accepted, and any one matching is enough. |
+| `X-Robovue-Dry-Run` | true | Checks the request exactly as a real one — authentication, every field, the delivery id, your plan's bot limit — and stores nothing. The response says what would have happened. Use it to test an integration without creating runs. Any other value, or no header, is an ordinary request. |
+
+#### Body fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `botId` | string, ≤ 200 chars | Yes | Your name for the bot. Every run with the same botId is the same bot on your dashboard. Spaces and punctuation are fine; not / or \, no spaces at either end, and no tabs or line breaks. The same id registers and manages the bot through the Management API. |
+| `platform` | string, ≤ 50 chars | Yes | What runs the bot, shown beside it on the dashboard — any short label, such as dotnet, python, go or blue-prism. Same whitespace rules as botId. |
+| `status` | one of `Success`, `Failure`, `Running` | Yes | How the run went. Running reports a run that has started and not finished yet; send the same delivery id again with Success or Failure when it ends. Values are case-sensitive. |
+| `startedAt` | timestamp | Yes | When the run started, as an RFC 3339 timestamp with a time zone offset — Z for UTC or ±hh:mm, e.g. 2026-07-17T09:00:00Z. Not before 2000, and not more than an hour ahead of Robovue's clock. Unix times aren't accepted. |
+| `completedAt` | timestamp | Required when status is Success or Failure; leave it out when status is Running | When the run finished. Same format and limits as startedAt, and not before it. |
+| `failureCategory` | one of `Uncategorized`, `BusinessException`, `ApplicationException`, `Timeout`, `AuthenticationError`, `Cancelled` | No — only with status Failure | Why the run failed, if your bot can tell. Leave it out if not — it becomes Uncategorized and can be changed later on the run's page. Values are case-sensitive. |
+| `payload` | object | No | Anything that will help you debug the run later — an invoice number, the step that failed, a stack trace. Must be a JSON object; it's stored as sent and shown on the run's page. A top-level error, errorMessage or message string becomes the summary in the failure alert. Counts toward the 64 KB request limit. |
+
+#### Responses
+
+Every error body is `{"error": "…", "code": "…", "field": "…", "requestId": "…"}` — `field` only when the error is about one field — and every response carries an `X-Request-Id` header.
+
+| Status | Code | Meaning | Retry? |
+|---|---|---|---|
+| 201 | — | A new run was recorded. Body: {"runId": "…", "duplicate": false} | No need — nothing more to send |
+| 200 | — | The run was already known. duplicate is false when this completed a run reported as Running, and true when it repeated a report already recorded — a retry, which is safe. | No need — nothing more to send |
+| 200 | — | A dry run passed every check. Body: {"dryRun": true, "wouldBe": "created"} — or "completed" or "duplicate". Nothing was stored. | No need — nothing more to send |
+| 400 | `invalid_body` | The body isn't a single valid JSON object. The message gives the line and position. | No — fix the request first |
+| 400 | `duplicate_field` | A field appears twice. | No — fix the request first |
+| 400 | `unknown_field` | A field isn't one of the documented names. Names are case-sensitive; put your own data inside payload. | No — fix the request first |
+| 400 | `missing_field` | A required field is missing, blank or null. field names it. | No — fix the request first |
+| 400 | `invalid_field` | A field's value breaks its rule. field names it and the message says how. | No — fix the request first |
+| 400 | `missing_delivery_id` | X-Robovue-Delivery-Id is missing. | No — fix the request first |
+| 400 | `invalid_delivery_id` | X-Robovue-Delivery-Id is longer than 200 characters, or has spaces or non-ASCII characters. | No — fix the request first |
+| 400 | `bot_cap_reached` | This would be a new bot and your plan's bot limit is reached. Archive and delete a bot you no longer use, or raise the limit on the Billing page. | No — fix the request first |
+| 401 | `missing_signature` | X-Robovue-Signature is missing. | No — fix the request first |
+| 401 | `missing_timestamp` | X-Robovue-Timestamp is missing. | No — fix the request first |
+| 401 | `invalid_timestamp` | X-Robovue-Timestamp isn't whole Unix seconds — milliseconds are the usual cause. | No — fix the request first |
+| 401 | `timestamp_out_of_range` | X-Robovue-Timestamp is more than 5 minutes from Robovue's clock. The message gives the server's time; fix the sending machine's clock. | Yes, once re-signed with the current time |
+| 401 | `invalid_signature` | The signature doesn't match. Check the secret, and that you sign the timestamp, the delivery or run id and the exact bytes you send. | No — fix the request first |
+| 404 | `unknown_tenant` | No workspace has this tenant id. Copy the URL from your Connect page. | No — fix the request first |
+| 409 | `delivery_id_conflict` | The delivery id already belongs to a different bot's run. Reuse a delivery id only for the same bot's run. | No — fix the request first |
+| 413 | `payload_too_large` | The body is over 64 KB. | No — fix the request first |
+| 415 | `unsupported_media_type` | Content-Type isn't application/json. | No — fix the request first |
+| 429 | `rate_limited` | Too many requests. Retry-After says how many seconds to wait. | Yes, after the Retry-After seconds |
+| 500 | `internal_error` | Something went wrong on Robovue's side. Quote the requestId if it keeps happening. | Yes, with backoff — the same delivery id makes it safe |
+
+#### Limits
+
+| Limit | Value | Notes |
+|---|---|---|
+| Run report size | 64 KB | Per request, payload included. Anything larger is rejected with 413 — it isn't truncated. |
+| Run reports | 600 per minute per workspace | Shared by the run report, Power Automate and UiPath endpoints. A start and its completion count as two. |
+| Attachment size | 5 MB | One file per failed run: PNG, JPEG or UTF-8 text. |
+| Attachment uploads | 50 per hour per workspace | Across all bots. |
+| Attachment storage | 500 MB per workspace | Attachments are deleted after the workspace's retention, 30 days at most, which frees their space. |
+| Management API | 300 requests per minute per workspace | Every /tenants/… request. |
+| Per address | 3,000 requests per minute per client IP | Across ingestion and the Management API together, for every workspace sending from that address. |
+<!-- contract:end -->
+
+**Signing, in one line:** `"v1=" + hex(HMAC-SHA256(key: webhook secret, message: timestamp + "\nrun\n" + delivery id + "\n" + the exact body bytes))`,
+lowercase, sent with the same timestamp in `X-Robovue-Timestamp` (Unix seconds). Sign each attempt, retries
+included, just before sending it. Sign the bytes you actually send: re-serialising the JSON after signing (a
+different key order, different whitespace) changes them and the request is rejected with `invalid_signature`.
+Connections → HTTP API has a signature checker to compare yours against.
+
+The attachment upload (`POST /ingest/{tenantId}/runs/{runId}/attachment`) uses the same scheme with the word
+`attachment` in place of `run` and the run id (lowercase, hyphenated) in place of the delivery id, computed over
+the raw file bytes instead of a JSON body. It has no delivery-id header: one attachment per run is what makes it
+safe to retry.
+
+This scheme is only for the `/ingest/{tenantId}/runs` endpoint. UiPath Orchestrator, Power Automate and
+Automation Anywhere connect to Robovue without code; Connections in Robovue sets each one up.
+
+## Versions and support
+
+- The package follows [semantic versioning](https://semver.org). `CHANGELOG.md`, in the source
+  distribution, lists what changed in each version.
+- For bots written in C# or another .NET language, [`Robovue.Sdk`](https://www.nuget.org/packages/Robovue.Sdk)
+  is the same client.
+- Questions and problems: [contact@robovue.co.uk](mailto:contact@robovue.co.uk). Quote the `RequestId` from
+  the error if there is one.
+- Found a security problem? See [robovue.co.uk/security](https://robovue.co.uk/security).
+
+## Licence
+
+MIT, so you can use, change and ship this package freely (see `LICENSE` in the package). Using the Robovue
+service is covered by the [terms](https://robovue.co.uk/terms).

robovue_sdk-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+robovue_sdk/__init__.py,sha256=YcZ9_dE2e0b_0f1ia-jB11gkYCIgdgsU57uXvPPoY0o,351
+robovue_sdk/_signature.py,sha256=C0LxJQm4CGE3Emv1uVa7Hz2pBk1uE-hqS24aUQO7HVM,1033
+robovue_sdk/_transport.py,sha256=ntk9thTKOKt2EsmLW0EiG-3Oo1DEC3EkapVBmrVYRpI,4333
+robovue_sdk/_version.py,sha256=v0S4g9l3egEtnYhqDUzI344nMOz-DFazAXJGvJLPcYI,637
+robovue_sdk/client.py,sha256=0_pMRdZeX5DOoYssvuYJmC0p1n9rFtCPk-eoP4AoX60,14647
+robovue_sdk/exceptions.py,sha256=uep_oWZfh4xjy26tNB3xMrW35XV-Zqrs8k1ex01ep14,1398
+robovue_sdk/models.py,sha256=Eb6B60FPIqfGaclcZYaCzSGUbMhZYA23dZkeAH1YgC8,2852
+robovue_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+robovue_sdk-0.2.0.dist-info/METADATA,sha256=udJubr0_WpggFR0IarH9BXB58U9BerZHRNDqh_x6PLg,23474
+robovue_sdk-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+robovue_sdk-0.2.0.dist-info/licenses/LICENSE,sha256=rezHn0C4gc7fYv0B-t7irMY9kzlFYVjZ097o-NFJUq4,1085
+robovue_sdk-0.2.0.dist-info/RECORD,,

robovue_sdk-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

robovue_sdk-0.2.0.dist-info/licenses/LICENSE

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