bn-shortener 0.1.0__tar.gz

bn_shortener-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BroadNet Technologies LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bn_shortener-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.5
+Name: bn-shortener
+Version: 0.1.0
+Summary: Official Python client for the BN Shortener API (b1.lc): links, QR codes, bio pages, analytics, webhooks, OAuth
+Project-URL: Homepage, https://b1.lc
+Project-URL: Documentation, https://b1.lc/docs/
+Project-URL: Source, https://github.com/BN-Shortner/bn-shortener-python
+Project-URL: Issues, https://github.com/BN-Shortner/bn-shortener-python/issues
+Author-email: BroadNet Technologies LLC <support@broadnet.me>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: b1.lc,broadnet,qr codes,short links,url shortener
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# bn-shortener (Python)
+
+Official Python client for the [BN Shortener API](https://b1.lc/docs/) (b1.lc): short links, QR codes,
+bio pages, analytics, Launch Check, webhooks and OAuth. No dependencies; Python 3.9+.
+
+```bash
+pip install bn-shortener
+```
+
+## Quick start
+
+```python
+from bn_shortener import BNShortener
+
+bn = BNShortener("bn_live_...")          # or set BN_API_KEY
+
+link = bn.links.create(url="https://example.com/spring-sale", title="Spring sale")
+print(link["short_url"])                 # https://b1.lc/AbC9
+
+stats = bn.links.stats(link["id"], period="30d")
+print(stats["summary"]["total_clicks"])
+
+for l in bn.paginate(bn.links.list, search="sale"):   # every page
+    print(l["short_code"], l["click_count"])
+```
+
+Create an API key in the dashboard: **API Portal → API keys**. A key has permissions (`read`, `write`, `delete`,
+`webhooks`, `admin`); give each integration only what it needs.
+
+## Resources
+
+| Attribute | What |
+|---|---|
+| `bn.links` | create, get, get_by_code, update, delete, archive, restore, clone, stats, clicks, referrers, devices, geo, timeline, export, import, bulk_create / bulk_update / bulk_delete, health, stream_clicks |
+| `bn.qr_codes` | create, get, update, delete, list, image (png, jpeg, webp, svg, pdf, eps), stats |
+| `bn.bio_pages` | create, get, update, delete, list, list_blocks, create_block, update_block, delete_block, reorder_blocks, analytics, subscribers, messages |
+| `bn.webhooks` | create, get, update, delete, list, test, deliveries, get_delivery, redeliver, events |
+| `bn.launch_check` | run, get, start_run, get_run, stop_run |
+| `bn.security` | scan, check, get_scan, bulk_scan, list_scans, ... |
+| `bn.messaging` | create_batch, list_batches, get_batch, list_messages, record_conversion |
+| `bn.api_keys`, `bn.account`, `bn.app_links`, `bn.system` | keys, usage + audit log, apps, API info |
+
+Every method's docstring names its endpoint and the permission it needs. Methods return the response's `data`;
+list methods return a `Page` (iterate it; `page.pagination`, `page.next_page()`); files come back as
+`BinaryResponse` (`.content`, `.content_type`, `.save(path)`):
+
+```python
+qr = bn.qr_codes.create(name="Menu", content={"url": "https://example.com/menu"})
+bn.qr_codes.image(qr["id"], format="svg", size=1000).save("menu.svg")
+```
+
+## Command line
+
+The package installs the `bn` command: `bn login`, `bn shorten URL`, `bn links`, `bn stats CODE`, `bn check CODE`
+(Launch Check, exit 1 when not ready), `bn qr URL -o file.svg`, `bn bulk file.csv`, `bn api GET /usage`. Run
+`bn --help`. The same command is a single file at https://b1.lc/cli/bn.
+
+## Errors
+
+```python
+from bn_shortener import ValidationError, RateLimitError, NotFoundError, APIError
+
+try:
+    bn.links.create(url="not a url")
+except ValidationError as e:
+    print(e.errors)        # [{'field': 'url', 'code': ..., 'message': ...}]
+except APIError as e:
+    print(e.status, e.type, e.detail, e.request_id)   # e.type links to https://b1.lc/docs/errors/...
+```
+
+Connection errors, timeouts, 408, 429 and 5xx are retried (`max_retries=2`, waiting as long as `Retry-After`
+says). Every write carries an `Idempotency-Key`, so a retry after a lost answer never creates a second link.
+Pass `request_options={"idempotency_key": "..."}` to make your own retries safe too.
+
+## Apps that act for other people (OAuth 2.1)
+
+```python
+from bn_shortener import BNShortener
+from bn_shortener.oauth import OAuthClient, TokenSession
+
+app = OAuthClient("bnc_...", redirect_uri="https://example.com/callback")
+auth = app.authorization_url(scope=["read", "write"])     # keep auth.state + auth.code_verifier in the session
+# send the person to auth.url; b1.lc sends them back to your redirect URI
+code = app.parse_callback(callback_url, expected_state=auth.state)
+token = app.exchange_code(code, auth.code_verifier)
+
+bn = BNShortener(oauth=TokenSession(app, token, on_refresh=save_token))   # refreshes by itself
+```
+
+Command-line tools without a browser use the device flow:
+
+```python
+device = app.start_device_flow(scope=["read", "write"])
+print(f"Open {device.verification_uri} and type {device.user_code}")
+token = app.wait_for_device(device)
+```
+
+Refresh tokens rotate: save the new token in `on_refresh` every time.
+
+## Webhooks
+
+```python
+from bn_shortener.webhooks import construct_event
+
+event = construct_event(request.get_data(), request.headers, WEBHOOK_SECRET)  # raises WebhookVerificationError
+```
+
+Pass the raw body, before any JSON parsing. Signatures older than 5 minutes are refused (replays).
+
+## Options
+
+`BNShortener(api_key, access_token=None, oauth=None, base_url="https://b1.lc/api/v1", timeout=30.0, max_retries=2,
+client_name=None, default_headers=None, transport=None)`. `client_name` shows your integration by name in the
+account's usage (`GET /usage`). `bn.last_response` has the status, request id and rate limit of the latest call.
+`bn.request("GET", "/path")` calls an endpoint this version does not wrap yet.
+
+## License
+
+MIT

bn_shortener-0.1.0/README.md

@@ -0,0 +1,119 @@
+# bn-shortener (Python)
+
+Official Python client for the [BN Shortener API](https://b1.lc/docs/) (b1.lc): short links, QR codes,
+bio pages, analytics, Launch Check, webhooks and OAuth. No dependencies; Python 3.9+.
+
+```bash
+pip install bn-shortener
+```
+
+## Quick start
+
+```python
+from bn_shortener import BNShortener
+
+bn = BNShortener("bn_live_...")          # or set BN_API_KEY
+
+link = bn.links.create(url="https://example.com/spring-sale", title="Spring sale")
+print(link["short_url"])                 # https://b1.lc/AbC9
+
+stats = bn.links.stats(link["id"], period="30d")
+print(stats["summary"]["total_clicks"])
+
+for l in bn.paginate(bn.links.list, search="sale"):   # every page
+    print(l["short_code"], l["click_count"])
+```
+
+Create an API key in the dashboard: **API Portal → API keys**. A key has permissions (`read`, `write`, `delete`,
+`webhooks`, `admin`); give each integration only what it needs.
+
+## Resources
+
+| Attribute | What |
+|---|---|
+| `bn.links` | create, get, get_by_code, update, delete, archive, restore, clone, stats, clicks, referrers, devices, geo, timeline, export, import, bulk_create / bulk_update / bulk_delete, health, stream_clicks |
+| `bn.qr_codes` | create, get, update, delete, list, image (png, jpeg, webp, svg, pdf, eps), stats |
+| `bn.bio_pages` | create, get, update, delete, list, list_blocks, create_block, update_block, delete_block, reorder_blocks, analytics, subscribers, messages |
+| `bn.webhooks` | create, get, update, delete, list, test, deliveries, get_delivery, redeliver, events |
+| `bn.launch_check` | run, get, start_run, get_run, stop_run |
+| `bn.security` | scan, check, get_scan, bulk_scan, list_scans, ... |
+| `bn.messaging` | create_batch, list_batches, get_batch, list_messages, record_conversion |
+| `bn.api_keys`, `bn.account`, `bn.app_links`, `bn.system` | keys, usage + audit log, apps, API info |
+
+Every method's docstring names its endpoint and the permission it needs. Methods return the response's `data`;
+list methods return a `Page` (iterate it; `page.pagination`, `page.next_page()`); files come back as
+`BinaryResponse` (`.content`, `.content_type`, `.save(path)`):
+
+```python
+qr = bn.qr_codes.create(name="Menu", content={"url": "https://example.com/menu"})
+bn.qr_codes.image(qr["id"], format="svg", size=1000).save("menu.svg")
+```
+
+## Command line
+
+The package installs the `bn` command: `bn login`, `bn shorten URL`, `bn links`, `bn stats CODE`, `bn check CODE`
+(Launch Check, exit 1 when not ready), `bn qr URL -o file.svg`, `bn bulk file.csv`, `bn api GET /usage`. Run
+`bn --help`. The same command is a single file at https://b1.lc/cli/bn.
+
+## Errors
+
+```python
+from bn_shortener import ValidationError, RateLimitError, NotFoundError, APIError
+
+try:
+    bn.links.create(url="not a url")
+except ValidationError as e:
+    print(e.errors)        # [{'field': 'url', 'code': ..., 'message': ...}]
+except APIError as e:
+    print(e.status, e.type, e.detail, e.request_id)   # e.type links to https://b1.lc/docs/errors/...
+```
+
+Connection errors, timeouts, 408, 429 and 5xx are retried (`max_retries=2`, waiting as long as `Retry-After`
+says). Every write carries an `Idempotency-Key`, so a retry after a lost answer never creates a second link.
+Pass `request_options={"idempotency_key": "..."}` to make your own retries safe too.
+
+## Apps that act for other people (OAuth 2.1)
+
+```python
+from bn_shortener import BNShortener
+from bn_shortener.oauth import OAuthClient, TokenSession
+
+app = OAuthClient("bnc_...", redirect_uri="https://example.com/callback")
+auth = app.authorization_url(scope=["read", "write"])     # keep auth.state + auth.code_verifier in the session
+# send the person to auth.url; b1.lc sends them back to your redirect URI
+code = app.parse_callback(callback_url, expected_state=auth.state)
+token = app.exchange_code(code, auth.code_verifier)
+
+bn = BNShortener(oauth=TokenSession(app, token, on_refresh=save_token))   # refreshes by itself
+```
+
+Command-line tools without a browser use the device flow:
+
+```python
+device = app.start_device_flow(scope=["read", "write"])
+print(f"Open {device.verification_uri} and type {device.user_code}")
+token = app.wait_for_device(device)
+```
+
+Refresh tokens rotate: save the new token in `on_refresh` every time.
+
+## Webhooks
+
+```python
+from bn_shortener.webhooks import construct_event
+
+event = construct_event(request.get_data(), request.headers, WEBHOOK_SECRET)  # raises WebhookVerificationError
+```
+
+Pass the raw body, before any JSON parsing. Signatures older than 5 minutes are refused (replays).
+
+## Options
+
+`BNShortener(api_key, access_token=None, oauth=None, base_url="https://b1.lc/api/v1", timeout=30.0, max_retries=2,
+client_name=None, default_headers=None, transport=None)`. `client_name` shows your integration by name in the
+account's usage (`GET /usage`). `bn.last_response` has the status, request id and rate limit of the latest call.
+`bn.request("GET", "/path")` calls an endpoint this version does not wrap yet.
+
+## License
+
+MIT

bn_shortener-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bn-shortener"
+version = "0.1.0"
+description = "Official Python client for the BN Shortener API (b1.lc): links, QR codes, bio pages, analytics, webhooks, OAuth"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "BroadNet Technologies LLC", email = "support@broadnet.me" }]
+keywords = ["url shortener", "short links", "qr codes", "b1.lc", "broadnet"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.scripts]
+bn = "bn_shortener.cli:run"
+
+[project.urls]
+Homepage = "https://b1.lc"
+Documentation = "https://b1.lc/docs/"
+Source = "https://github.com/BN-Shortner/bn-shortener-python"
+Issues = "https://github.com/BN-Shortner/bn-shortener-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bn_shortener"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q -p no:cacheprovider"

bn_shortener-0.1.0/src/bn_shortener/__init__.py

@@ -0,0 +1,13 @@
+"""BN Shortener API v3 client: https://b1.lc/docs/"""
+from . import oauth, webhooks
+from ._client import BNShortener, BinaryResponse, LastResponse, Page
+from ._errors import (APIConnectionError, APIError, APITimeoutError, AuthenticationError, BadRequestError, BNError,
+                      ConflictError, InternalServerError, NotFoundError, OAuthError, PermissionDeniedError,
+                      RateLimitError, ValidationError, WebhookVerificationError)
+from ._transport import Request, Response
+from ._version import __version__
+
+__all__ = ['BNShortener', 'Page', 'BinaryResponse', 'LastResponse', 'Request', 'Response', 'oauth', 'webhooks',
+           'BNError', 'APIError', 'APIConnectionError', 'APITimeoutError', 'BadRequestError', 'AuthenticationError',
+           'PermissionDeniedError', 'NotFoundError', 'ConflictError', 'ValidationError', 'RateLimitError',
+           'InternalServerError', 'OAuthError', 'WebhookVerificationError', '__version__']

bn_shortener-0.1.0/src/bn_shortener/__main__.py

@@ -0,0 +1,3 @@
+from .cli import run
+
+run()

bn_shortener-0.1.0/src/bn_shortener/_client.py

@@ -0,0 +1,299 @@
+import json
+import os
+import platform
+import random
+import time
+import uuid
+from typing import Any, Callable, Dict, Iterator, Mapping, Optional
+from urllib.parse import quote, urlencode
+
+from . import _transport
+from ._errors import APIConnectionError, APIError, AuthenticationError, BNError, OAuthError, error_for
+from ._generated import GeneratedResources
+from ._version import __version__
+
+DEFAULT_BASE_URL = 'https://b1.lc/api/v1'
+RETRY_STATUSES = {408, 429, 500, 502, 503, 504}
+WRITE_METHODS = {'POST', 'PUT', 'PATCH', 'DELETE'}
+MAX_RETRY_WAIT = 60.0
+
+
+class Page:
+    """One page of a list. Iterate it for the items; ``pagination`` has page, per_page, total_items, total_pages,
+    has_next, has_prev. ``client.paginate(...)`` walks every page for you."""
+
+    def __init__(self, data, meta, fetch):
+        self.data = list(data or [])
+        self.meta = meta or {}
+        self.pagination = self.meta.get('pagination') or {}
+        self._fetch = fetch
+
+    @property
+    def has_next(self):
+        p = self.pagination
+        if 'has_next' in p:
+            return bool(p['has_next'])
+        return bool(p.get('total_pages') and p.get('page', 1) < p['total_pages'])
+
+    def next_page(self):
+        """The following page, or None after the last one."""
+        if not self.has_next:
+            return None
+        return self._fetch(int(self.pagination.get('page', 1)) + 1)
+
+    def __iter__(self):
+        return iter(self.data)
+
+    def __len__(self):
+        return len(self.data)
+
+    def __getitem__(self, i):
+        return self.data[i]
+
+    def __repr__(self):
+        return f'<Page {self.pagination.get("page", "?")}/{self.pagination.get("total_pages", "?")}: {len(self.data)} items>'
+
+
+class BinaryResponse:
+    """A file answer (QR code image, CSV export): ``content`` bytes plus ``content_type``, ``filename`` and headers."""
+
+    def __init__(self, content, headers):
+        self.content = content
+        self.headers = headers
+        self.content_type = headers.get('content-type', '').split(';')[0].strip()
+        cd = headers.get('content-disposition', '')
+        self.filename = cd.split('filename=', 1)[1].strip('"; ') if 'filename=' in cd else None
+
+    @property
+    def text(self):
+        return self.content.decode('utf-8')
+
+    def save(self, path):
+        with open(path, 'wb') as f:
+            f.write(self.content)
+        return path
+
+    def __repr__(self):
+        return f'<BinaryResponse {self.content_type} {len(self.content)} bytes>'
+
+
+class LastResponse:
+    """Status, headers and rate limit of the latest answer (``client.last_response``)."""
+
+    def __init__(self, status, headers):
+        self.status = status
+        self.headers = headers
+        self.request_id = headers.get('x-request-id')
+
+        def num(name):
+            try:
+                return int(headers[name])
+            except (KeyError, ValueError):
+                return None
+        self.rate_limit = {'limit': num('x-ratelimit-limit'), 'remaining': num('x-ratelimit-remaining'),
+                           'reset': num('x-ratelimit-reset')}
+        self.idempotent_replay = headers.get('idempotency-replayed') == 'true' or headers.get('x-idempotency-replayed') == 'true'
+
+
+def _clean(params):
+    out = {}
+    for k, v in (params or {}).items():
+        if v is None:
+            continue
+        if isinstance(v, bool):
+            v = 'true' if v else 'false'
+        elif isinstance(v, (list, tuple)):
+            v = ','.join(str(x) for x in v)
+        out[k] = v
+    return out
+
+
+class BNShortener(GeneratedResources):
+    """Client for the BN Shortener API v3 (https://b1.lc/docs/).
+
+    Authenticate with an API key (``api_key=`` or the ``BN_API_KEY`` environment variable), an OAuth access token
+    (``access_token=``), or an ``oauth.TokenSession`` that refreshes itself (``oauth=``).
+
+    Every resource is an attribute: ``client.links``, ``client.qr_codes``, ``client.bio_pages``, ``client.webhooks``...
+    Writes get an Idempotency-Key automatically, so retries after a timeout or 5xx never do the work twice.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, *, access_token: Optional[str] = None, oauth=None,
+                 base_url: Optional[str] = None, timeout: float = 30.0, max_retries: int = 2,
+                 client_name: Optional[str] = None, default_headers: Optional[Mapping[str, str]] = None,
+                 transport: Optional[Callable[[_transport.Request], _transport.Response]] = None):
+        if not (api_key or access_token or oauth):
+            api_key = os.environ.get('BN_API_KEY')
+        if not (api_key or access_token or oauth):
+            raise BNError('Pass api_key=, access_token= or oauth= (or set BN_API_KEY)')
+        self.api_key = api_key
+        self.access_token = access_token
+        self.oauth = oauth
+        self.base_url = (base_url or os.environ.get('BN_BASE_URL') or DEFAULT_BASE_URL).rstrip('/')
+        self.timeout = timeout
+        self.max_retries = max(0, int(max_retries))
+        self.client_name = client_name
+        self.default_headers = dict(default_headers or {})
+        self.transport = transport or _transport.urllib_transport
+        self.last_response: Optional[LastResponse] = None
+        self._sleep = time.sleep
+        self._init_resources()
+
+    # ---- public helpers ----------------------------------------------------------------------------------------
+    def paginate(self, method, *args, **kwargs) -> Iterator[Any]:
+        """Every item of a list method, page after page: ``for link in client.paginate(client.links.list, search='x')``."""
+        page = method(*args, **kwargs)
+        while page is not None:
+            yield from page
+            page = page.next_page()
+
+    def request(self, method: str, path: str, *, query=None, body=None, idempotency_key=None, headers=None):
+        """Call an endpoint this version does not wrap yet. ``path`` is relative to base_url (e.g. '/links')."""
+        return self._request(method.upper(), path, query=query, body=body,
+                             options={'idempotency_key': idempotency_key, 'headers': headers})
+
+    # ---- internals ---------------------------------------------------------------------------------------------
+    def _headers(self, options):
+        h = {'Accept': 'application/json', 'User-Agent': f'bn-shortener-python/{__version__} (Python {platform.python_version()})',
+             'X-BN-Client': self.client_name or f'bn-python/{__version__}'}
+        h.update(self.default_headers)
+        if self.oauth is not None:
+            try:
+                h['Authorization'] = 'Bearer ' + self.oauth.get_access_token()
+            except OAuthError as e:
+                if e.ended:  # disconnected, revoked, expired: the app must connect again
+                    raise AuthenticationError(401, {'title': 'Authentication Required',
+                                                    'detail': f'Could not refresh the access token ({e})'}) from e
+                raise APIConnectionError(f'The token endpoint is unavailable ({e}); try again') from e
+        elif self.access_token:
+            h['Authorization'] = 'Bearer ' + self.access_token
+        else:
+            h['X-API-Key'] = self.api_key
+        h.update((options or {}).get('headers') or {})
+        return h
+
+    def _url(self, path, path_params=None, query=None):
+        for k, v in (path_params or {}).items():
+            path = path.replace('{' + k + '}', quote(str(v), safe=''))
+        q = _clean(query)
+        return self.base_url + path + ('?' + urlencode(q) if q else '')
+
+    def _retry_wait(self, attempt, headers):
+        ra = headers.get('retry-after') if headers else None
+        if ra:
+            try:
+                return min(MAX_RETRY_WAIT, max(0.0, float(ra)))
+            except ValueError:
+                pass
+        return min(8.0, 0.5 * (2 ** attempt)) * (0.75 + random.random() / 2)
+
+    def _send(self, method, url, body, options, stream=False):
+        options = options or {}
+        data = None
+        idem = None
+        if body is not None:
+            data = json.dumps(body, default=str).encode('utf-8')
+        if method in WRITE_METHODS:
+            idem = options.get('idempotency_key') or f'bn-sdk-{uuid.uuid4().hex}'
+        timeout = options.get('timeout') or self.timeout
+        retried_auth = False
+        attempt = 0
+        while True:
+            headers = self._headers(options)
+            if data is not None:
+                headers['Content-Type'] = 'application/json'
+            if idem:
+                headers['Idempotency-Key'] = idem
+            try:
+                resp = self.transport(_transport.Request(method, url, headers, data, timeout, stream))
+            except APIConnectionError:
+                if attempt < self.max_retries:
+                    self._sleep(self._retry_wait(attempt, None))
+                    attempt += 1
+                    continue
+                raise
+            self.last_response = LastResponse(resp.status, resp.headers)
+            if resp.status == 401 and self.oauth is not None and not retried_auth and self.oauth.can_refresh():
+                retried_auth = True  # the access token may have been revoked or expired early: refresh once
+                try:
+                    self.oauth.refresh_now(only_if=headers['Authorization'][len('Bearer '):])
+                except OAuthError as e:
+                    if e.ended:
+                        return resp  # the sign-in itself ended: the caller gets the 401 as AuthenticationError
+                    raise APIConnectionError(f'The token endpoint is unavailable ({e}); try again') from e
+                resp.close()
+                continue
+            # 409 + Retry-After = our earlier try with this Idempotency-Key is still running (e.g. after a timeout):
+            # asking again shortly returns its stored answer. A real conflict (code taken) has no Retry-After.
+            in_flight = resp.status == 409 and idem and 'retry-after' in resp.headers
+            if (resp.status in RETRY_STATUSES or in_flight) and attempt < self.max_retries:
+                resp.close()
+                self._sleep(self._retry_wait(attempt, resp.headers))
+                attempt += 1
+                continue
+            return resp
+
+    def _raise_for(self, resp):
+        body = resp.body
+        if resp.lines is not None:
+            body = b''.join(resp.lines)
+        try:
+            problem = json.loads(body.decode('utf-8')) if body else {}
+        except ValueError:
+            problem = {'title': f'HTTP {resp.status}', 'detail': body[:200].decode('utf-8', 'replace')}
+        raise error_for(resp.status, problem, resp.headers)
+
+    def _request(self, method, path, *, path_params=None, query=None, body=None, paged=False, options=None):
+        url = self._url(path, path_params, query)
+        resp = self._send(method, url, body, options)
+        if resp.status >= 300:  # the API never redirects; a 3xx means a proxy or wrong base_url
+            self._raise_for(resp)
+        ctype = resp.headers.get('content-type', '')
+        if 'json' not in ctype:
+            if not resp.body and resp.status == 204:
+                return None
+            return BinaryResponse(resp.body, resp.headers)
+        payload = json.loads(resp.body.decode('utf-8')) if resp.body else None
+        if isinstance(payload, dict) and 'success' in payload and 'data' in payload:
+            if paged:
+                def fetch(n):
+                    return self._request(method, path, path_params=path_params, query={**(query or {}), 'page': n},
+                                         paged=True, options=options)
+                return Page(payload['data'], payload.get('meta'), fetch)
+            return payload['data']
+        return payload
+
+    def _stream(self, path, *, path_params=None, query=None, options=None):
+        """Server-sent events as dicts. Heartbeats are skipped; the stream ends when the server closes it."""
+        options = dict(options or {})
+        options.setdefault('headers', {})
+        options['headers'] = {**options['headers'], 'Accept': 'text/event-stream'}
+        resp = self._send('GET', self._url(path, path_params, query), None, options, stream=True)
+        if resp.status >= 400:
+            self._raise_for(resp)
+        event, data = None, []
+        try:
+            for raw in resp.lines:
+                line = raw.decode('utf-8').rstrip('\r\n')
+                if not line:
+                    if data:
+                        text = '\n'.join(data)
+                        try:
+                            item = json.loads(text)
+                        except ValueError:
+                            item = {'data': text}
+                        if event and isinstance(item, dict):
+                            item.setdefault('event', event)
+                        yield item
+                    event, data = None, []
+                elif line.startswith(':'):
+                    continue
+                elif line.startswith('event:'):
+                    event = line[6:].strip()
+                elif line.startswith('data:'):
+                    data.append(line[5:].lstrip())
+        finally:
+            resp.close()
+
+
+__all__ = ['BNShortener', 'Page', 'BinaryResponse', 'LastResponse', 'APIError', 'AuthenticationError']