blu-sdk 1.0.0__py3-none-any.whl

blu/__init__.py

@@ -0,0 +1,27 @@
+"""BLU API client. No dependencies. See README.md."""
+from ._async import AsyncBlu
+from ._core import Blu, BluDownload, BluResponse
+from ._errors import (
+    BluAllowanceError,
+    BluAuthError,
+    BluBadRequestError,
+    BluConflictError,
+    BluConnectionError,
+    BluError,
+    BluNotFoundError,
+    BluPaginationError,
+    BluPermissionError,
+    BluRateLimitError,
+    BluServerError,
+    BluUploadError,
+)
+from ._generated import SDK_VERSION, SPEC_VERSION
+from ._webhooks import SignatureCheck, check_signature, parse_signature_header, verify_signature
+
+__version__ = SDK_VERSION
+__all__ = [
+    "AsyncBlu", "Blu", "BluDownload", "BluResponse",
+    "BluAllowanceError", "BluAuthError", "BluBadRequestError", "BluConflictError", "BluConnectionError", "BluError",
+    "BluNotFoundError", "BluPaginationError", "BluPermissionError", "BluRateLimitError", "BluServerError", "BluUploadError",
+    "SDK_VERSION", "SPEC_VERSION", "SignatureCheck", "check_signature", "parse_signature_header", "verify_signature",
+]

blu/_async.py

@@ -0,0 +1,44 @@
+"""The same client for asyncio. It runs the standard-library client on a worker thread, so a call
+never blocks your event loop. Methods ending in _all are async iterators."""
+import asyncio
+
+from ._core import Blu
+from ._generated import GROUPS
+
+_END = object()
+
+
+async def _walk(method, args, kwargs):
+    iterator = await asyncio.to_thread(method, *args, **kwargs)
+    while True:
+        item = await asyncio.to_thread(next, iterator, _END)
+        if item is _END:
+            return
+        yield item
+
+
+class _AsyncGroup:
+    def __init__(self, group):
+        self._group = group
+
+    def __getattr__(self, name):
+        method = getattr(self._group, name)
+        if name.endswith("_all"):
+            return lambda *args, **kwargs: _walk(method, args, kwargs)
+
+        async def call(*args, **kwargs):
+            return await asyncio.to_thread(method, *args, **kwargs)
+
+        return call
+
+
+class AsyncBlu:
+    """Takes what Blu takes. await client.chats.send(...), async for row in client.chats.list_all(...)."""
+
+    def __init__(self, api_key=None, **config):
+        self._sync = Blu(api_key, **config)
+        for name in GROUPS:
+            setattr(self, name, _AsyncGroup(getattr(self._sync, name)))
+
+    def __repr__(self):
+        return "Async%r" % (self._sync,)

blu/_core.py

@@ -0,0 +1,428 @@
+"""The hand-written core. Everything easy to get wrong lives here, once.
+
+- One Idempotency-Key per call, kept across that call's own retries, so a retry can't send twice.
+  A new call gets a new key, and that is how you try a ``not_sent`` again on purpose.
+- Retries only when BLU or the network says trying later is safe. A 2xx is never retried, and that
+  includes 202 ``unknown``. An error that carries an ``outcome`` is never retried. A write the API
+  doesn't hold to its key goes again only when BLU itself said to.
+- http.client directly, so a redirect is never followed and the key never reaches another host.
+"""
+import datetime
+import email.utils
+import http.client
+import json
+import os
+import platform
+import random
+import re
+import ssl
+import time
+import urllib.parse
+import uuid
+
+from ._errors import BluConnectionError, BluError, BluPaginationError, error_class_for
+from ._generated import BASE_URL, GROUPS, OPERATIONS, SDK_VERSION
+from ._uploads import upload_to_vault
+
+# What an edge says when the answer never got through: the same as a dropped connection.
+_TRANSIENT_STATUS = frozenset([429, 502, 503, 504, 520, 521, 522, 523, 524, 530])
+_KEY_FORMAT = re.compile(r"[\x21-\x7e]{1,255}")
+_API_KEY_FORMAT = re.compile(r"[\x21-\x7e]+")
+_LOOPBACK = frozenset(["127.0.0.1", "localhost", "::1"])
+_JOB_IN_URL = re.compile(r"/v1/(?:creators/[^/]+/mass-messages/)?jobs/([^/?#]+)")
+# BLU settles a request within a minute. Until then "still running" is worth waiting for: a caller
+# who took it for a failure and sent again with a new key would send twice.
+_IN_FLIGHT_WAIT_SECONDS = 75.0
+
+
+class _Hidden:
+    """Holds the key so that it can't reach a log through repr, str or vars."""
+
+    __slots__ = ("_value",)
+
+    def __init__(self, value):
+        self._value = value
+
+    def __repr__(self):
+        return "<hidden>"
+
+    __str__ = __repr__
+
+    def reveal(self):
+        return self._value
+
+
+def _parse_retry_after(value):
+    if value is None:
+        return None
+    text = str(value).strip()
+    if re.fullmatch(r"[0-9]+", text):
+        return int(text) * 1000
+    try:
+        at = email.utils.parsedate_to_datetime(text)
+    except (TypeError, ValueError):
+        return None
+    if at is None:
+        return None
+    if at.tzinfo is None:
+        at = at.replace(tzinfo=datetime.timezone.utc)
+    return max(0, int((at - datetime.datetime.now(datetime.timezone.utc)).total_seconds() * 1000))
+
+
+def _path_argument(name, value, op_id):
+    if isinstance(value, bool) or not isinstance(value, (str, int)):
+        raise TypeError("%s: %s must be a string or a number, got %s." % (op_id, name, type(value).__name__))
+    text = str(value)
+    if not text or text in (".", ".."):
+        raise TypeError("%s: %s isn't a usable id." % (op_id, name))
+    return urllib.parse.quote(text, safe="")
+
+
+def _query_string(query):
+    pairs = []
+    for name, value in (query or {}).items():
+        if value is None:
+            continue
+        for one in value if isinstance(value, (list, tuple)) else [value]:
+            if isinstance(one, bool):
+                one = "true" if one else "false"
+            elif isinstance(one, (datetime.datetime, datetime.date)):
+                one = one.isoformat()
+            pairs.append((name, str(one)))
+    return "?" + urllib.parse.urlencode(pairs, quote_via=urllib.parse.quote) if pairs else ""
+
+
+class BluResponse:
+    """The answer to a call. outcome, action_id, status_url and job_id are there on a write."""
+
+    def __init__(self, status, body, headers, idempotency_key):
+        body = body if isinstance(body, dict) else {}
+        data = body.get("data")
+        self.status = status
+        self.data = data
+        self.outcome = body.get("outcome")
+        self.action_id = body.get("actionId") or headers.get("x-blu-action-id")
+        data_dict = data if isinstance(data, dict) else {}
+        self.status_url = body.get("statusUrl") or data_dict.get("statusUrl")
+        found = _JOB_IN_URL.search(str(self.status_url or ""))
+        self.job_id = data_dict.get("jobId") or (urllib.parse.unquote(found.group(1)) if found else None)
+        self.error_message = body.get("errorMessage")
+        self.replayed = headers.get("idempotent-replayed") == "true"
+        self.idempotency_key = idempotency_key
+        self.request_id = headers.get("x-request-id")
+        credits_left = headers.get("x-blu-credits-remaining")
+        self.credits_remaining = int(credits_left) if credits_left is not None and credits_left.isdigit() else None
+        self.headers = headers
+        if isinstance(body.get("hasMore"), bool):
+            self.items = data_dict.get("list") if isinstance(data_dict.get("list"), list) else []
+            self.cursor = body.get("cursor") if isinstance(body.get("cursor"), str) else ""
+            self.has_more = body["hasMore"]
+
+    def __repr__(self):
+        return "BluResponse(status=%r, outcome=%r, action_id=%r)" % (self.status, self.outcome, self.action_id)
+
+
+class BluDownload:
+    """A file coming back from the API. read(n), or save_to(path). Close it, or use ``with``."""
+
+    def __init__(self, status, headers, response, connection):
+        self.status = status
+        self.headers = headers
+        self._response = response
+        self._connection = connection
+        length = headers.get("content-length")
+        self.content_length = int(length) if length and length.isdigit() else None
+        self.content_type = headers.get("content-type")
+        self.request_id = headers.get("x-request-id")
+
+    def read(self, size=-1):
+        return self._response.read(size)
+
+    def save_to(self, path, chunk_size=1024 * 1024):
+        try:
+            with open(path, "wb") as out:
+                while True:
+                    chunk = self._response.read(chunk_size)
+                    if not chunk:
+                        return path
+                    out.write(chunk)
+        finally:
+            self.close()
+
+    def close(self):
+        self._response.close()
+        self._connection.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_exc):
+        self.close()
+
+
+class Blu:
+    """The client. Every endpoint is a method on a group, such as client.chats.send(...)."""
+
+    def __init__(self, api_key=None, *, base_url=BASE_URL, timeout=70.0, max_retries=3, max_retry_delay=60.0, retry_base_delay=0.5):
+        key = os.environ.get("BLU_KEY") if api_key is None else api_key
+        if not isinstance(key, str) or not key:
+            raise TypeError("No API key. Pass api_key, or set BLU_KEY.")
+        if not _API_KEY_FORMAT.fullmatch(key):
+            raise TypeError("That API key has spaces or control characters in it, so it can't be right.")
+        self._authorization = _Hidden("Bearer " + key)
+        parts = urllib.parse.urlsplit(str(base_url))
+        secure = parts.scheme == "https"
+        if not parts.hostname or (not secure and not (parts.scheme == "http" and parts.hostname in _LOOPBACK)):
+            raise TypeError("base_url must use https. Plain http is allowed only on this machine, for tests.")
+        if parts.username or parts.password:
+            raise TypeError("base_url can't hold a username or password.")
+        if parts.path not in ("", "/") or parts.query or parts.fragment:
+            raise TypeError("base_url is only the address, such as https://api.blu.luxe.")
+        self._secure = secure
+        self._host = parts.hostname
+        self._port = parts.port
+        self.base_url = "%s://%s" % (parts.scheme, parts.netloc)
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.max_retry_delay = max_retry_delay
+        self.retry_base_delay = retry_base_delay
+        self._user_agent = "blu-sdk-python/%s python/%s" % (SDK_VERSION, platform.python_version())
+        for name, group in GROUPS.items():
+            setattr(self, name, group(self))
+        self.vault.upload = lambda creator_id, **kwargs: upload_to_vault(self, creator_id, **kwargs)
+
+    def __repr__(self):
+        return "Blu(base_url=%r)" % (self.base_url,)
+
+    def _call(self, op_id, path_args, payload=None, *, idempotency_key=None, dry_run=False, timeout=None,
+              max_retries=None, content_length=None, range=None):  # pylint: disable=redefined-builtin
+        """One call: every generated method lands here."""
+        op = OPERATIONS[op_id]
+        target = self._target(op, path_args, payload, dry_run)
+        headers = {
+            "Authorization": self._authorization.reveal(),
+            "Accept": "*/*" if op.get("binary") else "application/json",
+            "User-Agent": self._user_agent,
+        }
+        key = self._key_for(idempotency_key) if op["write"] else None
+        if key:
+            headers["Idempotency-Key"] = key
+        if range:
+            headers["Range"] = str(range)
+        make_body, replayable, owns_body = self._prepare_body(op, payload, content_length, headers)
+        retries = self.max_retries if max_retries is None else max_retries
+        wait_for = self.timeout if timeout is None else timeout
+        attempt = 0
+        waited_since = None
+        while True:
+            try:
+                answer = self._send(op["method"], target, headers, make_body, owns_body, wait_for, op.get("binary", False))
+            except (OSError, http.client.HTTPException) as err:
+                delay = None
+                if replayable and op.get("retry_safe") and not isinstance(err, ssl.SSLCertVerificationError):
+                    delay = self._retry_delay(None, None, True, attempt, retries)
+                if delay is None:
+                    raise self._connection_error(err, op, key) from None
+                time.sleep(delay)
+                attempt += 1
+                continue
+            status = answer["status"]
+            if 200 <= status < 300:
+                return self._success(op, answer, key)
+            if 300 <= status < 400:
+                raise BluError("BLU answered HTTP %d, a redirect. It isn't followed, because your key would go with it." % status,
+                               status=status, code="unexpected_redirect", idempotency_key=key)
+            error, declared = self._error_from(answer, key)
+            if error.code == "idempotency_in_flight" and retries > 0 and replayable:
+                waited_since = time.monotonic() if waited_since is None else waited_since
+                if time.monotonic() - waited_since < _IN_FLIGHT_WAIT_SECONDS:
+                    time.sleep((error.retry_after_ms or 2000) / 1000.0)
+                    continue
+            # An edge's error says nothing about whether the call ran. Only BLU's own "try later" does.
+            delay = None
+            if replayable and (op.get("retry_safe") or declared is True):
+                delay = self._retry_delay(error, declared, False, attempt, retries)
+            if delay is None:
+                raise error
+            time.sleep(delay)
+            attempt += 1
+
+    def _iterate(self, op_id, path_args, query=None, **options):
+        """Every row of a list, page after page. Only hasMore: false ends it."""
+        op = OPERATIONS[op_id]
+        asked = dict(query or {})
+        while True:
+            page = self._call(op_id, path_args, dict(asked), **options)
+            if not hasattr(page, "has_more"):
+                raise BluPaginationError("%s: the answer doesn't say whether there's more." % op_id, request_id=page.request_id)
+            for item in page.items:
+                yield item
+            if page.has_more is False:
+                return
+            if op.get("paging") == "since":
+                last = page.items[-1].get("id") if page.items else None
+                if not last or last == asked.get("since"):
+                    raise BluPaginationError("%s: BLU says there's more, but no new event id came back to continue from." % op_id, request_id=page.request_id)
+                asked["since"] = last
+            else:
+                if not page.cursor or page.cursor == asked.get("cursor"):
+                    raise BluPaginationError("%s: BLU says there's more, but gave no new cursor to get it. This list can't be walked past this page." % op_id, request_id=page.request_id)
+                asked["cursor"] = page.cursor
+
+    def _target(self, op, path_args, payload, dry_run):
+        args = iter(path_args)
+
+        def fill(match):
+            return _path_argument(match.group(1), next(args), op["id"])
+
+        filled = re.sub(r"\{([A-Za-z0-9_]+)\}", fill, op["path"])
+        if op["write"]:
+            query = {"dry_run": "true"} if dry_run else None
+        else:
+            query = payload
+            if query is not None and not isinstance(query, dict):
+                raise TypeError("%s: the query must be a dict." % op["id"])
+        return filled + _query_string(query)
+
+    @staticmethod
+    def _key_for(given):
+        if given is None:
+            return str(uuid.uuid4())
+        if not isinstance(given, str) or not _KEY_FORMAT.fullmatch(given):
+            raise TypeError("idempotency_key must be 1 to 255 printable characters, with no spaces.")
+        return given
+
+    @staticmethod
+    def _prepare_body(op, payload, content_length, headers):
+        """(make_body, replayable, owns_body). Bytes can go again, and so can a function that opens
+        the stream afresh. A stream handed over as it is can be read once, so it isn't retried."""
+        if op.get("raw_body"):
+            headers["Content-Type"] = "application/octet-stream"
+            if isinstance(payload, (bytes, bytearray, memoryview, str)):
+                data = payload.encode("utf-8") if isinstance(payload, str) else bytes(payload)
+                headers["Content-Length"] = str(len(data))
+                return (lambda: data), True, False
+            if content_length is None:
+                raise TypeError("%s: a stream needs content_length: BLU checks each part's exact size." % op["id"])
+            headers["Content-Length"] = str(content_length)
+            if callable(payload):
+                return payload, True, True
+            if hasattr(payload, "read"):
+                return (lambda: payload), False, False
+            raise TypeError("%s: the part must be bytes, a file object, or a function that returns one." % op["id"])
+        if not op["write"] or not op.get("has_body"):
+            if op["write"] and payload is not None:
+                raise TypeError("%s takes no body." % op["id"])
+            if op["write"]:
+                headers["Content-Length"] = "0"
+            return (lambda: None), True, False
+        if payload is None:
+            if op.get("body_required"):
+                raise TypeError("%s needs a body." % op["id"])
+            headers["Content-Length"] = "0"
+            return (lambda: None), True, False
+        if not isinstance(payload, dict):
+            raise TypeError("%s: the body must be a dict." % op["id"])
+        data = json.dumps(payload).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+        headers["Content-Length"] = str(len(data))
+        return (lambda: data), True, False
+
+    def _retry_delay(self, error, declared, connection, attempt, retries):
+        """Seconds to wait before trying again, or None when this answer must not be retried."""
+        if attempt >= retries:
+            return None
+        if not connection:
+            # What BLU said about a write is final. A not_sent needs a new call and an unknown needs a person.
+            if error.outcome in ("unknown", "not_sent"):
+                return None
+            if declared is False:
+                return None
+            if declared is not True and error.status not in _TRANSIENT_STATUS:
+                return None
+        retry_after_ms = error.retry_after_ms if error is not None else None
+        if retry_after_ms is not None:
+            # Longer than we may wait: never earlier than BLU asked, so this one is the caller's to plan.
+            if retry_after_ms / 1000.0 > self.max_retry_delay:
+                return None
+            wait = retry_after_ms / 1000.0
+            return wait + random.random() * min(1.0, wait * 0.1)
+        ceiling = min(self.max_retry_delay, self.retry_base_delay * (2 ** attempt))
+        return ceiling / 2 + random.random() * (ceiling / 2)
+
+    @staticmethod
+    def _success(op, answer, key):
+        if op.get("binary"):
+            return BluDownload(answer["status"], answer["headers"], answer["response"], answer["connection"])
+        text = answer["text"]
+        body = None
+        if text:
+            try:
+                body = json.loads(text.decode("utf-8"))
+            except ValueError:
+                raise BluError("BLU answered HTTP %d, but not with JSON." % answer["status"], status=answer["status"], code="bad_response",
+                               outcome="unknown" if op["write"] else None, idempotency_key=key,
+                               request_id=answer["headers"].get("x-request-id")) from None
+        return BluResponse(answer["status"], body, answer["headers"], key)
+
+    @staticmethod
+    def _error_from(answer, key):
+        status, headers = answer["status"], answer["headers"]
+        try:
+            body = json.loads(answer["text"].decode("utf-8"))
+        except ValueError:
+            body = None
+        body = body if isinstance(body, dict) else {}
+        detail = body.get("error") if isinstance(body.get("error"), dict) else None
+        details = detail.get("details") if detail else None
+        details_dict = details if isinstance(details, dict) else {}
+        message = body.get("errorMessage") if isinstance(body.get("errorMessage"), str) and body.get("errorMessage") else "BLU answered HTTP %d." % status
+        retry_after = detail.get("retryAfterMs") if detail else None
+        if not isinstance(retry_after, (int, float)) or isinstance(retry_after, bool):
+            retry_after = _parse_retry_after(headers.get("retry-after"))
+        declared = detail.get("retryable") if detail and isinstance(detail.get("retryable"), bool) else None
+        error = error_class_for(status)(
+            message,
+            status=status,
+            code=detail.get("code") if detail else None,
+            outcome=detail.get("outcome") if detail else None,
+            retryable=declared if declared is not None else status in _TRANSIENT_STATUS,
+            retry_after_ms=retry_after,
+            details=details,
+            action_id=details_dict.get("actionId") or headers.get("x-blu-action-id"),
+            request_id=headers.get("x-request-id"),
+            idempotency_key=key,
+            replayed=headers.get("idempotent-replayed") == "true",
+        )
+        return error, declared
+
+    @staticmethod
+    def _connection_error(err, op, key):
+        write = op["write"]
+        advice = "."
+        if write:
+            advice = ", so it may or may not have happened. "
+            advice += "To ask again, pass the same idempotency_key: it can't send twice." if op.get("key_honored") else "Check before you try again."
+        return BluConnectionError("No answer from BLU" + advice, code=type(err).__name__, outcome="unknown" if write else None, idempotency_key=key)
+
+    def _send(self, method, target, headers, make_body, owns_body, timeout, want_stream):
+        """One attempt. Returns the answer, raises when no answer arrived."""
+        if self._secure:
+            connection = http.client.HTTPSConnection(self._host, self._port, timeout=timeout, context=ssl.create_default_context())
+        else:
+            connection = http.client.HTTPConnection(self._host, self._port, timeout=timeout)
+        body = make_body()
+        keep_open = False
+        try:
+            connection.request(method, target, body=body, headers=headers)
+            response = connection.getresponse()
+            answer_headers = {name.lower(): value for name, value in response.getheaders()}
+            if want_stream and 200 <= response.status < 300:
+                keep_open = True
+                return {"status": response.status, "headers": answer_headers, "response": response, "connection": connection}
+            return {"status": response.status, "headers": answer_headers, "text": response.read()}
+        finally:
+            if owns_body and hasattr(body, "close"):
+                body.close()
+            if not keep_open:
+                connection.close()

blu/_errors.py

@@ -0,0 +1,93 @@
+"""Every failure carries what BLU said about it.
+
+``outcome`` is the one that matters on a write:
+    "not_sent"  nothing happened. To try again, make a new call (a new Idempotency-Key).
+    "unknown"   OnlyFans may have done it. Check before you try again.
+"""
+
+
+class BluError(Exception):
+    def __init__(self, message, *, status=None, code=None, outcome=None, retryable=False, retry_after_ms=None,
+                 details=None, action_id=None, request_id=None, idempotency_key=None, replayed=False):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.outcome = outcome
+        self.retryable = bool(retryable)
+        self.retry_after_ms = retry_after_ms
+        self.details = details
+        self.action_id = action_id
+        self.request_id = request_id
+        self.idempotency_key = idempotency_key
+        self.replayed = bool(replayed)
+
+
+class BluBadRequestError(BluError):
+    """400 and 422: the request is wrong, and the message says what to fix."""
+
+
+class BluAuthError(BluError):
+    """401: the key is missing, wrong, expired or revoked."""
+
+
+class BluAllowanceError(BluError):
+    """402: this month's live calls are used up."""
+
+
+class BluPermissionError(BluError):
+    """403: the key can't do this."""
+
+
+class BluNotFoundError(BluError):
+    """404: no such thing for this key."""
+
+
+class BluConflictError(BluError):
+    """409: a conflict, such as Sophie handling the chat."""
+
+
+class BluRateLimitError(BluError):
+    """429: too many requests, a busy creator, or a daily limit."""
+
+
+class BluServerError(BluError):
+    """5xx."""
+
+
+class BluConnectionError(BluError):
+    """No usable answer arrived: a timeout or a dropped connection, after every retry.
+
+    On a write ``outcome`` is "unknown". To ask again, pass the same ``idempotency_key``: it
+    can't send twice.
+    """
+
+
+class BluPaginationError(BluError):
+    """BLU says there is more, but gave no way to get it. Stopping quietly would lose rows."""
+
+
+class BluUploadError(BluError):
+    """The upload helper stopped. ``upload`` is the upload's last known state, when there is one."""
+
+    def __init__(self, message, *, upload=None, **fields):
+        super().__init__(message, **fields)
+        self.upload = upload
+
+
+def error_class_for(status):
+    if status == 401:
+        return BluAuthError
+    if status == 402:
+        return BluAllowanceError
+    if status == 403:
+        return BluPermissionError
+    if status == 404:
+        return BluNotFoundError
+    if status == 409:
+        return BluConflictError
+    if status == 429:
+        return BluRateLimitError
+    if status >= 500:
+        return BluServerError
+    return BluBadRequestError