dbbyte 0.1.0__py3-none-any.whl

dbbyte/__init__.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from .client import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, DBByteClient
+from .errors import DBByteError
+from .objects import ObjectsResource
+from .types import (
+    DeleteResponse,
+    DownloadResult,
+    FileListItem,
+    FileVersionPreview,
+    HealthResponse,
+    ListObjectsResponse,
+    ListVersionsResponse,
+    SignedUrlResponse,
+    UploadedObject,
+    VersionEntry,
+)
+
+__all__ = [
+    "DBByte",
+    "DBByteError",
+    "HealthResponse",
+    "UploadedObject",
+    "ListObjectsResponse",
+    "FileListItem",
+    "FileVersionPreview",
+    "SignedUrlResponse",
+    "ListVersionsResponse",
+    "VersionEntry",
+    "DeleteResponse",
+    "DownloadResult",
+]
+
+
+class DBByte:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self._client = DBByteClient(api_key, base_url, timeout)
+        self.objects = ObjectsResource(self._client)
+
+    def health(self) -> HealthResponse:
+        result = self._client.request_json("GET", "/health")
+        return result  # type: ignore[no-any-return]

dbbyte/client.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Dict, NoReturn, Optional
+
+from .errors import DBByteError
+
+DEFAULT_BASE_URL = "https://api.dbbyte.com"
+DEFAULT_TIMEOUT = 30.0
+USER_AGENT = "dbbyte-python/0.1.0"
+
+
+class DBByteClient:
+    """Thin HTTP wrapper. Paths passed to request_* do NOT include /v1 -
+    in production the Cloudflare Worker gateway in front of
+    api.dbbyte.com inserts /api/v1 itself. If you point base_url at a
+    Next.js dev server directly (bypassing the Worker), include /api/v1
+    in base_url instead."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        if not api_key:
+            raise ValueError("DBByte: api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _build_url(self, path: str, query: Optional[Dict[str, Any]] = None) -> str:
+        url = f"{self.base_url}{path}"
+        if query:
+            filtered = {k: v for k, v in query.items() if v is not None}
+            if filtered:
+                url += "?" + urllib.parse.urlencode(filtered)
+        return url
+
+    def _headers(self, extra: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": USER_AGENT,
+        }
+        if extra:
+            headers.update(extra)
+        return headers
+
+    def _raise_for_error(self, e: urllib.error.HTTPError) -> NoReturn:
+        raw = e.read()
+        retry_after = None
+        ra_header = e.headers.get("Retry-After") if e.headers else None
+        if ra_header is not None:
+            try:
+                retry_after = int(ra_header)
+            except ValueError:
+                retry_after = None
+        message = e.reason
+        hint = None
+        try:
+            body = json.loads(raw.decode("utf-8"))
+            message = body.get("error", message)
+            hint = body.get("hint")
+        except (ValueError, UnicodeDecodeError):
+            # Non-JSON body: this didn't come from the DBByte API itself
+            # (which always returns {"error": ...}) - likely blocked
+            # upstream, e.g. by Cloudflare's edge/WAF before reaching
+            # the app.
+            hint = "Response was not JSON - request may have been blocked before reaching the API"
+        raise DBByteError(message, e.code, hint, retry_after) from None
+
+    def request_json(
+        self,
+        method: str,
+        path: str,
+        query: Optional[Dict[str, Any]] = None,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        url = self._build_url(path, query)
+        data = None
+        headers = self._headers()
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                raw = res.read()
+                return json.loads(raw.decode("utf-8")) if raw else None
+        except urllib.error.HTTPError as e:
+            self._raise_for_error(e)
+        except urllib.error.URLError as e:
+            raise DBByteError(f"Request failed: {e.reason}", 0) from None
+
+    def request_form(
+        self,
+        method: str,
+        path: str,
+        filename: str,
+        file_bytes: bytes,
+        content_type: Optional[str],
+        query: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        url = self._build_url(path, query)
+        boundary = uuid.uuid4().hex
+        ct = content_type or "application/octet-stream"
+        # Filename is only escaped for embedded quotes, matching the
+        # Node SDK's simplicity - the server is the source of truth for
+        # what filenames it accepts.
+        safe_filename = filename.replace('"', '\\"')
+        parts = [
+            f"--{boundary}\r\n".encode(),
+            (
+                f'Content-Disposition: form-data; name="file"; '
+                f'filename="{safe_filename}"\r\n'
+                f"Content-Type: {ct}\r\n\r\n"
+            ).encode(),
+            file_bytes,
+            f"\r\n--{boundary}--\r\n".encode(),
+        ]
+        data = b"".join(parts)
+
+        headers = self._headers(
+            {"Content-Type": f"multipart/form-data; boundary={boundary}"}
+        )
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                raw = res.read()
+                return json.loads(raw.decode("utf-8")) if raw else None
+        except urllib.error.HTTPError as e:
+            self._raise_for_error(e)
+        except urllib.error.URLError as e:
+            raise DBByteError(f"Request failed: {e.reason}", 0) from None
+
+    def request_binary(
+        self,
+        method: str,
+        path: str,
+        query: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        url = self._build_url(path, query)
+        req = urllib.request.Request(url, headers=self._headers(), method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                data = res.read()
+                content_type = res.headers.get(
+                    "Content-Type", "application/octet-stream"
+                )
+                disposition = res.headers.get("Content-Disposition")
+                filename = None
+                if disposition and "filename=" in disposition:
+                    filename = disposition.split("filename=", 1)[1].strip('"')
+                result: Dict[str, Any] = {"data": data, "content_type": content_type}
+                if filename:
+                    result["filename"] = filename
+                return result
+        except urllib.error.HTTPError as e:
+            self._raise_for_error(e)
+        except urllib.error.URLError as e:
+            raise DBByteError(f"Request failed: {e.reason}", 0) from None

dbbyte/errors.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class DBByteError(Exception):
+    """Raised on any DBByte API error.
+
+    The API returns {"error": str, "hint"?: str} on failure. There is no
+    "code" field - do not rely on one.
+
+    A 429 can mean two different things and only one is retryable:
+      - Burst rate limit: retry_after is set (seconds until you can
+        retry). Transient, safe to retry after that delay.
+      - Plan API request quota exceeded: retry_after is None. Retrying
+        immediately won't help until the billing period resets or the
+        plan is upgraded.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status: int,
+        hint: Optional[str] = None,
+        retry_after: Optional[int] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.message = message
+        self.hint = hint
+        self.retry_after = retry_after
+
+    def __repr__(self) -> str:
+        return (
+            f"DBByteError(status={self.status!r}, message={self.message!r}, "
+            f"hint={self.hint!r}, retry_after={self.retry_after!r})"
+        )

dbbyte/objects.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .client import DBByteClient
+from .types import (
+    DeleteResponse,
+    DownloadResult,
+    ListObjectsResponse,
+    ListVersionsResponse,
+    SignedUrlResponse,
+    UploadedObject,
+)
+from .utils import encode_key
+
+
+class ObjectsResource:
+    def __init__(self, client: DBByteClient) -> None:
+        self._client = client
+
+    def upload(
+        self,
+        bucket: str,
+        key: str,
+        body: bytes,
+        content_type: Optional[str] = None,
+        overwrite: bool = False,
+    ) -> UploadedObject:
+        result = self._client.request_form(
+            "POST",
+            f"/storage/{bucket}/upload",
+            filename=key,
+            file_bytes=body,
+            content_type=content_type,
+            query={"overwrite": "true" if overwrite else None},
+        )
+        return result  # type: ignore[no-any-return]
+
+    def list(
+        self,
+        bucket: str,
+        prefix: Optional[str] = None,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> ListObjectsResponse:
+        result = self._client.request_json(
+            "GET",
+            f"/storage/{bucket}/list",
+            query={"prefix": prefix, "cursor": cursor, "limit": limit},
+        )
+        return result  # type: ignore[no-any-return]
+
+    def download(
+        self,
+        bucket: str,
+        key: str,
+        version: Optional[str] = None,
+    ) -> DownloadResult:
+        result = self._client.request_binary(
+            "GET",
+            f"/storage/{bucket}/download/{encode_key(key)}",
+            query={"version": version},
+        )
+        return result  # type: ignore[return-value]
+
+    def download_all_versions(self, bucket: str, key: str) -> DownloadResult:
+        """Returns a zip of every version of this key."""
+        result = self._client.request_binary(
+            "GET",
+            f"/storage/{bucket}/download/{encode_key(key)}",
+            query={"version": "all"},
+        )
+        return result  # type: ignore[return-value]
+
+    def delete(
+        self,
+        bucket: str,
+        key: str,
+        version: Optional[str] = None,
+    ) -> DeleteResponse:
+        result = self._client.request_json(
+            "DELETE",
+            f"/storage/{bucket}/delete/{encode_key(key)}",
+            query={"version": version},
+        )
+        return result  # type: ignore[no-any-return]
+
+    def delete_all_versions(self, bucket: str, key: str) -> DeleteResponse:
+        """Permanently deletes every version of this key."""
+        result = self._client.request_json(
+            "DELETE",
+            f"/storage/{bucket}/delete/{encode_key(key)}",
+            query={"version": "all"},
+        )
+        return result  # type: ignore[no-any-return]
+
+    def sign(
+        self,
+        bucket: str,
+        key: str,
+        version: Optional[str] = None,
+        expires_in: Optional[int] = None,
+    ) -> SignedUrlResponse:
+        body: Dict[str, Any] = {}
+        if version is not None:
+            body["version"] = version
+        if expires_in is not None:
+            body["expiresIn"] = expires_in
+        result = self._client.request_json(
+            "POST",
+            f"/storage/{bucket}/sign/{encode_key(key)}",
+            body=body,
+        )
+        return result  # type: ignore[no-any-return]
+
+    def versions(
+        self,
+        bucket: str,
+        key: str,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> ListVersionsResponse:
+        result = self._client.request_json(
+            "GET",
+            f"/storage/{bucket}/versions/{encode_key(key)}",
+            query={"limit": limit, "cursor": cursor},
+        )
+        return result  # type: ignore[no-any-return]

dbbyte/types.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, TypedDict
+
+
+class HealthChecks(TypedDict):
+    api: Dict[str, Any]
+    database: Dict[str, Any]
+
+
+class HealthResponse(TypedDict):
+    status: str  # "ok" | "degraded"
+    timestamp: str
+    uptimeSeconds: int
+    checks: HealthChecks
+    responseTimeMs: int
+
+
+class UploadedObject(TypedDict):
+    """Returned on a successful upload. Matches the storage server's
+    real response shape exactly - not inferred."""
+
+    success: bool
+    key: str  # server-generated storage key, not the name you passed
+    name: str  # the name you uploaded it as
+    size: int
+    mimeType: str
+    fileId: str
+
+
+class FileVersionPreview(TypedDict):
+    key: str
+    size: int
+    mimeType: str
+    isLatest: bool
+    createdAt: str
+    updatedAt: str
+
+
+class FileListItem(TypedDict):
+    key: str
+    name: str
+    size: int
+    isPublic: bool
+    createdAt: str
+    updatedAt: str
+    versionCount: int
+    versions: List[FileVersionPreview]
+    hasMoreVersions: bool
+
+
+class ListObjectsResponse(TypedDict):
+    files: List[FileListItem]
+    nextCursor: Optional[str]
+    hasMore: bool
+
+
+class SignedUrlResponse(TypedDict):
+    url: str
+    expiresIn: int
+
+
+class VersionEntry(TypedDict):
+    versionKey: str
+    size: int
+    mimeType: str
+    isLatest: bool
+    isDeleted: bool
+    createdAt: str
+    updatedAt: str
+
+
+class ListVersionsResponse(TypedDict):
+    versions: List[VersionEntry]
+    nextCursor: Optional[str]
+    hasMore: bool
+
+
+class _DeleteResponseOptional(TypedDict, total=False):
+    # Only present when deleting every version at once.
+    deletedVersions: int
+
+
+class DeleteResponse(_DeleteResponseOptional):
+    success: bool
+
+
+class _DownloadResultOptional(TypedDict, total=False):
+    filename: str
+
+
+class DownloadResult(_DownloadResultOptional):
+    data: bytes
+    content_type: str

dbbyte/utils.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from urllib.parse import quote
+
+
+def encode_key(key: str) -> str:
+    """Object keys can contain slashes (e.g. "images/logo.png"). The
+    API's catch-all routes expect each path segment encoded
+    individually, then rejoined with "/" - encoding the whole key would
+    also encode the slashes themselves."""
+    return "/".join(quote(segment, safe="") for segment in key.split("/"))

dbbyte-0.1.0.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: dbbyte
+Version: 0.1.0
+Summary: Official DBByte SDK for Python
+Author: DBByte, LLC
+License: MIT
+Project-URL: Homepage, https://dbbyte.com
+Project-URL: Repository, https://github.com/dbbyte/python-sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# dbbyte
+
+Official DBByte SDK for Python. A thin, typed wrapper over the DBByte v1 REST API. Standard library only - no dependencies.
+
+## Status
+
+Covers object storage: upload, list, download, delete, versioning, and signed URLs. There is no bucket management, CDN cache control, or analytics API yet - those aren't part of the v1 REST API, so they aren't in the SDK.
+
+## Installation
+
+```bash
+pip install dbbyte
+```
+
+Requires Python 3.9+.
+
+## Usage
+
+```python
+import os
+from dbbyte import DBByte
+
+db = DBByte(api_key=os.environ["DBBYTE_API_KEY"])
+```
+
+| Argument | Type | Description |
+| --- | --- | --- |
+| `api_key` | `str` | Your DBByte API key. Required. |
+| `base_url` | `str` | Override the API base URL. Defaults to `https://api.dbbyte.com`. |
+| `timeout` | `float` | Request timeout in seconds. Defaults to `30.0`. |
+
+### Health check
+
+```python
+status = db.health()
+```
+
+### Upload
+
+```python
+with open("logo.png", "rb") as f:
+    body = f.read()
+
+obj = db.objects.upload(
+    "my-bucket",
+    key="images/logo.png",
+    body=body,
+    content_type="image/png",
+)
+
+# Re-uploading the same name fails with 409 unless you opt in:
+db.objects.upload("my-bucket", key="images/logo.png", body=body, overwrite=True)
+```
+
+### List
+
+```python
+result = db.objects.list("my-bucket")
+files = result["files"]
+
+# Paginate:
+next_page = db.objects.list("my-bucket", cursor=result["nextCursor"])
+```
+
+### Download
+
+```python
+result = db.objects.download("my-bucket", "images/logo.png")
+data = result["data"]  # bytes
+
+# A specific historical version:
+db.objects.download("my-bucket", "images/logo.png", version="some-version-key")
+
+# Every version, zipped:
+zip_result = db.objects.download_all_versions("my-bucket", "images/logo.png")
+```
+
+### Versions
+
+```python
+result = db.objects.versions("my-bucket", "images/logo.png")
+```
+
+### Signed URLs
+
+```python
+result = db.objects.sign("my-bucket", "images/logo.png", expires_in=3600)  # max 604800 (7 days)
+url = result["url"]
+```
+
+### Delete
+
+```python
+db.objects.delete("my-bucket", "images/logo.png")
+
+# A specific version only:
+db.objects.delete("my-bucket", "images/logo.png", version="some-version-key")
+
+# Every version, permanently:
+db.objects.delete_all_versions("my-bucket", "images/logo.png")
+```
+
+## Error handling
+
+All SDK methods raise a `DBByteError` on API errors.
+
+```python
+from dbbyte import DBByte, DBByteError
+
+db = DBByte(api_key=os.environ["DBBYTE_API_KEY"])
+
+try:
+    db.objects.download("my-bucket", "does-not-exist.png")
+except DBByteError as e:
+    print(e.status)   # e.g. 404
+    print(e.message)  # e.g. "File not found"
+    print(e.hint)     # present on some errors, e.g. upload conflicts
+```
+
+### Rate limits vs quota limits
+
+A `429` can mean two different things, and only one is worth retrying:
+
+- **Burst rate limit** - `e.retry_after` is set (seconds until you can retry). Transient, safe to retry after that delay.
+- **Plan API request quota exceeded** - `e.retry_after` is `None`. Retrying immediately won't help; you're out of quota until your billing period resets or you upgrade.
+
+```python
+except DBByteError as e:
+    if e.status == 429:
+        if e.retry_after is not None:
+            # wait e.retry_after seconds, then retry
+            pass
+        else:
+            # plan quota exceeded, don't retry blindly
+            pass
+```
+
+## Known limitations
+
+- **Upload allowed types**: the server enforces a fixed MIME type whitelist (common image, video, audio, PDF, Word, and plain-text formats). Uploading anything else returns a `400` from the server - the SDK doesn't pre-validate this client-side.
+- **50MB max file size**, enforced server-side.
+- **Synchronous only.** No async client yet.
+
+## License
+
+MIT

dbbyte-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+dbbyte/__init__.py,sha256=oPgWsCtp3Yz9uwIloSRgIUWhVYk0nOMezwZK4H9oWcA,1162
+dbbyte/client.py,sha256=oG38mUu1445xG0dFcSjtX4TGxFExEYuImbkyNezRYrk,6205
+dbbyte/errors.py,sha256=ji_WLZ_WD9LxMrFtVU29b7_vol8B5OVbKlC7Cbl6mzU,1152
+dbbyte/objects.py,sha256=atxpsMPU8BR3s7MeNDAacx54IuNUWsW9Fe2Upq8LEx0,3792
+dbbyte/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dbbyte/types.py,sha256=ZaN1Gjk9OqmrXDIIv3qekP7Xs4HYQNKYo-Yviy4HUe8,1876
+dbbyte/utils.py,sha256=gfsDOIhMlT1iG16lldRAEDB8x18-S-APMBxZxhBhp8k,421
+dbbyte-0.1.0.dist-info/licenses/LICENSE,sha256=gLycZuuP67_sfgACPG4TWFugJi7cpQMFHEcd1KMZ5jA,1068
+dbbyte-0.1.0.dist-info/METADATA,sha256=95VJ0B6jaY6tgYUCWPCKsR_HZrmzTZsMSXdTcflIp0g,4371
+dbbyte-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+dbbyte-0.1.0.dist-info/top_level.txt,sha256=aaFgCSCELmGozk0K4pT0Aj97PzKkMMSrU41EZ8xRnH8,7
+dbbyte-0.1.0.dist-info/RECORD,,

dbbyte-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dbbyte-0.1.0.dist-info/licenses/LICENSE

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

dbbyte-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dbbyte