nexium-storage 0.1.0__tar.gz

nexium_storage-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: nexium-storage
+Version: 0.1.0
+Summary: Official Python SDK for NEXIUM Storage
+Author-email: NEXIUM <ai.nexium@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://nexiumai.io
+Project-URL: Documentation, https://console.nexiumai.io/docs
+Keywords: nexium,storage,s3,r2,file-upload,cloud
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: requests
+Requires-Dist: requests>=2.28; extra == "requests"
+
+# nexium-storage
+
+Official Python SDK for [NEXIUM Storage](https://nexiumai.io) — upload, serve and manage files via a simple API.
+
+## Install
+
+```bash
+pip install nexium-storage
+
+# For file upload support:
+pip install "nexium-storage[requests]"
+```
+
+## Quick start
+
+```python
+import os
+from nexium_storage import NexiumStorage
+
+storage = NexiumStorage(api_key=os.getenv("NEXIUM_API_KEY"))
+
+# Upload
+with open("photo.jpg", "rb") as f:
+    file = storage.upload(bucket_id, f, "photo.jpg", "image/jpeg")
+print(file.url)
+
+# List
+result = storage.list(bucket_id, search="photo")
+for f in result.files:
+    print(f.filename, f.size_bytes)
+
+# Download URL
+url = storage.download(file.id)
+
+# Rename
+storage.rename(file.id, "new-name.jpg")
+
+# Delete
+storage.delete(file.id)
+```
+
+## Webhook verification
+
+```python
+from nexium_storage import NexiumStorage, NexiumError
+
+# Flask example
+@app.route("/webhook", methods=["POST"])
+def webhook():
+    try:
+        payload = NexiumStorage.verify_webhook(
+            request.get_data(),
+            request.headers.get("X-Nexium-Signature"),
+            os.getenv("NEXIUM_WEBHOOK_SECRET"),
+        )
+        print(payload["event"], payload["data"])
+        return "", 200
+    except NexiumError:
+        return "", 401
+```
+
+## License
+
+MIT

nexium_storage-0.1.0/README.md

@@ -0,0 +1,64 @@
+# nexium-storage
+
+Official Python SDK for [NEXIUM Storage](https://nexiumai.io) — upload, serve and manage files via a simple API.
+
+## Install
+
+```bash
+pip install nexium-storage
+
+# For file upload support:
+pip install "nexium-storage[requests]"
+```
+
+## Quick start
+
+```python
+import os
+from nexium_storage import NexiumStorage
+
+storage = NexiumStorage(api_key=os.getenv("NEXIUM_API_KEY"))
+
+# Upload
+with open("photo.jpg", "rb") as f:
+    file = storage.upload(bucket_id, f, "photo.jpg", "image/jpeg")
+print(file.url)
+
+# List
+result = storage.list(bucket_id, search="photo")
+for f in result.files:
+    print(f.filename, f.size_bytes)
+
+# Download URL
+url = storage.download(file.id)
+
+# Rename
+storage.rename(file.id, "new-name.jpg")
+
+# Delete
+storage.delete(file.id)
+```
+
+## Webhook verification
+
+```python
+from nexium_storage import NexiumStorage, NexiumError
+
+# Flask example
+@app.route("/webhook", methods=["POST"])
+def webhook():
+    try:
+        payload = NexiumStorage.verify_webhook(
+            request.get_data(),
+            request.headers.get("X-Nexium-Signature"),
+            os.getenv("NEXIUM_WEBHOOK_SECRET"),
+        )
+        print(payload["event"], payload["data"])
+        return "", 200
+    except NexiumError:
+        return "", 401
+```
+
+## License
+
+MIT

nexium_storage-0.1.0/nexium_storage/__init__.py

@@ -0,0 +1,4 @@
+from .client import NexiumStorage, NexiumError, StoredFile, FileList
+
+__all__ = ["NexiumStorage", "NexiumError", "StoredFile", "FileList"]
+__version__ = "0.1.0"

nexium_storage-0.1.0/nexium_storage/client.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from dataclasses import dataclass
+from typing import IO, Any, Callable, Optional
+import urllib.request
+import urllib.parse
+import urllib.error
+
+DEFAULT_BASE_URL = "https://api.nexiumai.io"
+
+
+@dataclass
+class StoredFile:
+    id: str
+    bucket_id: str
+    object_key: str
+    filename: str
+    mime_type: str
+    size_bytes: int
+    url: str
+    created_at: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "StoredFile":
+        return cls(**{k: d[k] for k in cls.__dataclass_fields__})
+
+
+@dataclass
+class FileList:
+    files: list[StoredFile]
+    total: int
+    page: int
+    per_page: int
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "FileList":
+        return cls(
+            files=[StoredFile.from_dict(f) for f in d.get("files", [])],
+            total=d["total"],
+            page=d["page"],
+            per_page=d["per_page"],
+        )
+
+
+class NexiumError(Exception):
+    def __init__(self, status: int, message: str):
+        super().__init__(message)
+        self.status = status
+        self.message = message
+
+
+class NexiumStorage:
+    """NEXIUM Storage Python SDK."""
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+
+    def _request(self, method: str, path: str, **kwargs) -> Any:
+        try:
+            import requests
+            json_body = kwargs.pop("json_body", None)
+            headers = {"Authorization": f"Bearer {self.api_key}"}
+            req_kwargs: dict = {"headers": headers, **kwargs}
+            if json_body is not None:
+                req_kwargs["json"] = json_body
+            resp = requests.request(method, f"{self.base_url}{path}", **req_kwargs)
+            if resp.status_code == 204:
+                return None
+            data = resp.json()
+            if not resp.ok:
+                raise NexiumError(resp.status_code, data.get("message", "Request failed"))
+            return data
+        except ImportError:
+            return self._request_stdlib(method, path, **kwargs)
+
+    def _request_stdlib(self, method: str, path: str, json_body=None, **_) -> Any:
+        url = f"{self.base_url}{path}"
+        body = json.dumps(json_body).encode() if json_body else None
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+        req = urllib.request.Request(url, data=body, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req) as resp:
+                if resp.status == 204:
+                    return None
+                return json.loads(resp.read())
+        except urllib.error.HTTPError as e:
+            data = json.loads(e.read())
+            raise NexiumError(e.code, data.get("message", "Request failed")) from e
+
+    # ─── Files ────────────────────────────────────────────────────────────────
+
+    def list(
+        self,
+        bucket_id: str,
+        search: str = "",
+        page: int = 1,
+        per_page: int = 24,
+    ) -> FileList:
+        """List files in a bucket."""
+        params: dict[str, Any] = {"page": page, "per_page": per_page}
+        if search:
+            params["search"] = search
+        qs = urllib.parse.urlencode(params)
+        data = self._request("GET", f"/api/v1/ext/buckets/{bucket_id}/files?{qs}")
+        return FileList.from_dict(data)
+
+    def upload(
+        self,
+        bucket_id: str,
+        file: IO[bytes],
+        filename: str,
+        mime_type: str = "application/octet-stream",
+        on_progress: Optional[Callable[[int], None]] = None,
+    ) -> StoredFile:
+        """Upload a file to a bucket. `file` can be any file-like object."""
+        try:
+            import requests
+            headers = {"Authorization": f"Bearer {self.api_key}"}
+            resp = requests.post(
+                f"{self.base_url}/api/v1/ext/buckets/{bucket_id}/files",
+                headers=headers,
+                files={"file": (filename, file, mime_type)},
+            )
+            data = resp.json()
+            if not resp.ok:
+                raise NexiumError(resp.status_code, data.get("message", "Upload failed"))
+            return StoredFile.from_dict(data)
+        except ImportError:
+            raise NexiumError(0, "Install `requests` for file upload: pip install requests")
+
+    def download(self, file_id: str) -> str:
+        """Get a temporary download URL for a file."""
+        data = self._request("GET", f"/api/v1/ext/files/{file_id}/download")
+        return data["url"]
+
+    def rename(self, file_id: str, filename: str) -> StoredFile:
+        """Rename a file."""
+        data = self._request("PATCH", f"/api/v1/ext/files/{file_id}", json_body={"filename": filename})
+        return StoredFile.from_dict(data)
+
+    def delete(self, file_id: str) -> None:
+        """Delete a file."""
+        self._request("DELETE", f"/api/v1/ext/files/{file_id}")
+
+    # ─── Webhooks ─────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def verify_webhook(raw_body: bytes | str, signature: str, secret: str) -> Any:
+        """Verify a webhook signature and return the parsed payload.
+
+        Raises NexiumError if the signature is invalid.
+        """
+        if isinstance(raw_body, str):
+            raw_body = raw_body.encode()
+        expected = "sha256=" + hmac.new(
+            secret.encode(), raw_body, hashlib.sha256
+        ).hexdigest()
+        if not hmac.compare_digest(expected, signature):
+            raise NexiumError(401, "Invalid webhook signature")
+        return json.loads(raw_body)

nexium_storage-0.1.0/nexium_storage.egg-info/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: nexium-storage
+Version: 0.1.0
+Summary: Official Python SDK for NEXIUM Storage
+Author-email: NEXIUM <ai.nexium@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://nexiumai.io
+Project-URL: Documentation, https://console.nexiumai.io/docs
+Keywords: nexium,storage,s3,r2,file-upload,cloud
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: requests
+Requires-Dist: requests>=2.28; extra == "requests"
+
+# nexium-storage
+
+Official Python SDK for [NEXIUM Storage](https://nexiumai.io) — upload, serve and manage files via a simple API.
+
+## Install
+
+```bash
+pip install nexium-storage
+
+# For file upload support:
+pip install "nexium-storage[requests]"
+```
+
+## Quick start
+
+```python
+import os
+from nexium_storage import NexiumStorage
+
+storage = NexiumStorage(api_key=os.getenv("NEXIUM_API_KEY"))
+
+# Upload
+with open("photo.jpg", "rb") as f:
+    file = storage.upload(bucket_id, f, "photo.jpg", "image/jpeg")
+print(file.url)
+
+# List
+result = storage.list(bucket_id, search="photo")
+for f in result.files:
+    print(f.filename, f.size_bytes)
+
+# Download URL
+url = storage.download(file.id)
+
+# Rename
+storage.rename(file.id, "new-name.jpg")
+
+# Delete
+storage.delete(file.id)
+```
+
+## Webhook verification
+
+```python
+from nexium_storage import NexiumStorage, NexiumError
+
+# Flask example
+@app.route("/webhook", methods=["POST"])
+def webhook():
+    try:
+        payload = NexiumStorage.verify_webhook(
+            request.get_data(),
+            request.headers.get("X-Nexium-Signature"),
+            os.getenv("NEXIUM_WEBHOOK_SECRET"),
+        )
+        print(payload["event"], payload["data"])
+        return "", 200
+    except NexiumError:
+        return "", 401
+```
+
+## License
+
+MIT

nexium_storage-0.1.0/nexium_storage.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+nexium_storage/__init__.py
+nexium_storage/client.py
+nexium_storage.egg-info/PKG-INFO
+nexium_storage.egg-info/SOURCES.txt
+nexium_storage.egg-info/dependency_links.txt
+nexium_storage.egg-info/requires.txt
+nexium_storage.egg-info/top_level.txt

nexium_storage-0.1.0/nexium_storage.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nexium_storage-0.1.0/nexium_storage.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[requests]
+requests>=2.28

nexium_storage-0.1.0/nexium_storage.egg-info/top_level.txt

@@ -0,0 +1 @@
+nexium_storage

nexium_storage-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nexium-storage"
+version = "0.1.0"
+description = "Official Python SDK for NEXIUM Storage"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+authors = [
+  { name = "NEXIUM", email = "ai.nexium@gmail.com" }
+]
+keywords = ["nexium", "storage", "s3", "r2", "file-upload", "cloud"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.optional-dependencies]
+requests = ["requests>=2.28"]
+
+[project.urls]
+Homepage = "https://nexiumai.io"
+Documentation = "https://console.nexiumai.io/docs"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["nexium_storage*"]

nexium_storage-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+