fluidcloud 0.1.0__tar.gz

fluidcloud-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# --- Python -----------------------------------------------------------------
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+*.db
+*.sqlite3
+
+# --- Env / secrets ----------------------------------------------------------
+.env
+.env.*
+!.env.example
+
+# --- Node / Next.js ---------------------------------------------------------
+node_modules/
+.next/
+out/
+dist/
+build/
+.turbo/
+next-env.d.ts
+*.tsbuildinfo
+
+# --- Cloudflare Workers / wrangler ------------------------------------------
+.wrangler/
+.dev.vars
+# wrangler bundles from the TS source; a stray tsc emit next to it is build noise.
+workers/share/src/*.js
+
+# --- Editor / OS ------------------------------------------------------------
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.log
+
+# --- Host deploy artifacts (leftover source tarballs from the old transfer flow)
+*.tgz

fluidcloud-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: fluidcloud
+Version: 0.1.0
+Summary: Official Python SDK for FluidCloud — private file storage, shareable raw links, and stable public (hotlinkable) URLs.
+Project-URL: Homepage, https://cloud.fluidvip.com
+Project-URL: Source, https://github.com/Trebuu/FluidCloud
+Author: Fluidvip
+License-Expression: MIT
+Keywords: cdn,fluidcloud,share-links,storage,uploads
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fluidcloud — Python SDK for FluidCloud
+
+Official Python client for [FluidCloud](https://cloud.fluidvip.com) — file storage
+with shareable raw links and **stable public (hotlinkable) URLs**. The SDK hides the
+upload plumbing (presign → direct-to-storage PUT → complete, including multipart for
+large files) behind a single `upload()` call.
+
+📚 **Full documentation:** <https://cloud.fluidvip.com/docs>
+
+## Install
+
+```bash
+pip install fluidcloud
+```
+
+Requires Python 3.8+. The only runtime dependency is `httpx`.
+
+## Quick start
+
+```python
+from fluidcloud import FluidCloud
+
+fc = FluidCloud(api_key="fck_live_...")        # base_url defaults to production
+
+# A Space is a top-level bucket; folders and files live inside it.
+space = fc.spaces.create("Brand Assets")
+
+# Upload — one call hides presign -> PUT -> complete (+ multipart for big files).
+asset = fc.files.upload("logo.png", space_id=space.id, public=True)
+print(asset.public_url)        # stable, inline, cacheable hotlink (use as <img src>)
+
+# Or mint links explicitly:
+public = fc.files.public_url(asset.id)                 # permanent (never expires)
+signed = fc.files.signed_url(asset.id, expires_in_days=7, permission="view")
+```
+
+## Authentication
+
+Create an API key in the [dashboard](https://cloud.fluidvip.com) (Settings →
+Developer; an active subscription is required) and pass it to the client. The key
+(`fck_live_…` / `fck_test_…`) is sent as `X-API-Key`. Keys are **scoped**; a call
+outside a key's scopes raises `PermissionError_` (HTTP 403 `insufficient_scope`).
+
+## API surface
+
+```python
+fc.spaces.list() / create(name)
+fc.folders.list(space_id, parent_id=None) / create(name, space_id, parent_id=None)
+          / rename(id, name) / move(id, parent_id) / delete(id) / restore(id)
+fc.files.upload(path_or_bytes_or_fileobj, space_id, folder_id=None,
+                name=None, content_type=None, public=False)
+         .list(space_id, folder_id=None) / get(id)
+         .rename(id, name) / move(id, folder_id) / delete(id) / restore(id)
+         .download_url(id)                # short-lived download URL
+         .public_url(id)                  # permanent public hotlink (Link)
+         .signed_url(id, expires_in_days=7, permission="view")   # expiring (Link)
+fc.shares.list(file_id=None, include_inactive=False) / revoke(share_id)
+fc.quota.usage()                          # bytes_used / bytes_limit / links_*
+```
+
+`public_url` vs `signed_url`: a **public** link never expires and is served inline +
+edge-cached (ideal for embedding an image in a page, a bot message, or a vision
+model's `image_url`). A **signed** link expires (1–365 days). Use
+`fc.shares.revoke(link.id)` to revoke either.
+
+## Errors
+
+All errors derive from `FluidCloudError`: `AuthError` (401),
+`QuotaExceededError` (402), `PermissionError_` (403), `NotFoundError` (404),
+`ConflictError` (409, e.g. sharing a file still being scanned), or `ApiError`.
+
+## Notes
+
+- The client is synchronous (`httpx`) and works as a context manager:
+  `with FluidCloud(api_key=...) as fc: ...`.
+- The SDK targets the versioned API (`/api/v1`).
+- Override the API origin with `base_url=...` if you have been given a different endpoint.
+
+MIT licensed.

fluidcloud-0.1.0/README.md

@@ -0,0 +1,79 @@
+# fluidcloud — Python SDK for FluidCloud
+
+Official Python client for [FluidCloud](https://cloud.fluidvip.com) — file storage
+with shareable raw links and **stable public (hotlinkable) URLs**. The SDK hides the
+upload plumbing (presign → direct-to-storage PUT → complete, including multipart for
+large files) behind a single `upload()` call.
+
+📚 **Full documentation:** <https://cloud.fluidvip.com/docs>
+
+## Install
+
+```bash
+pip install fluidcloud
+```
+
+Requires Python 3.8+. The only runtime dependency is `httpx`.
+
+## Quick start
+
+```python
+from fluidcloud import FluidCloud
+
+fc = FluidCloud(api_key="fck_live_...")        # base_url defaults to production
+
+# A Space is a top-level bucket; folders and files live inside it.
+space = fc.spaces.create("Brand Assets")
+
+# Upload — one call hides presign -> PUT -> complete (+ multipart for big files).
+asset = fc.files.upload("logo.png", space_id=space.id, public=True)
+print(asset.public_url)        # stable, inline, cacheable hotlink (use as <img src>)
+
+# Or mint links explicitly:
+public = fc.files.public_url(asset.id)                 # permanent (never expires)
+signed = fc.files.signed_url(asset.id, expires_in_days=7, permission="view")
+```
+
+## Authentication
+
+Create an API key in the [dashboard](https://cloud.fluidvip.com) (Settings →
+Developer; an active subscription is required) and pass it to the client. The key
+(`fck_live_…` / `fck_test_…`) is sent as `X-API-Key`. Keys are **scoped**; a call
+outside a key's scopes raises `PermissionError_` (HTTP 403 `insufficient_scope`).
+
+## API surface
+
+```python
+fc.spaces.list() / create(name)
+fc.folders.list(space_id, parent_id=None) / create(name, space_id, parent_id=None)
+          / rename(id, name) / move(id, parent_id) / delete(id) / restore(id)
+fc.files.upload(path_or_bytes_or_fileobj, space_id, folder_id=None,
+                name=None, content_type=None, public=False)
+         .list(space_id, folder_id=None) / get(id)
+         .rename(id, name) / move(id, folder_id) / delete(id) / restore(id)
+         .download_url(id)                # short-lived download URL
+         .public_url(id)                  # permanent public hotlink (Link)
+         .signed_url(id, expires_in_days=7, permission="view")   # expiring (Link)
+fc.shares.list(file_id=None, include_inactive=False) / revoke(share_id)
+fc.quota.usage()                          # bytes_used / bytes_limit / links_*
+```
+
+`public_url` vs `signed_url`: a **public** link never expires and is served inline +
+edge-cached (ideal for embedding an image in a page, a bot message, or a vision
+model's `image_url`). A **signed** link expires (1–365 days). Use
+`fc.shares.revoke(link.id)` to revoke either.
+
+## Errors
+
+All errors derive from `FluidCloudError`: `AuthError` (401),
+`QuotaExceededError` (402), `PermissionError_` (403), `NotFoundError` (404),
+`ConflictError` (409, e.g. sharing a file still being scanned), or `ApiError`.
+
+## Notes
+
+- The client is synchronous (`httpx`) and works as a context manager:
+  `with FluidCloud(api_key=...) as fc: ...`.
+- The SDK targets the versioned API (`/api/v1`).
+- Override the API origin with `base_url=...` if you have been given a different endpoint.
+
+MIT licensed.

fluidcloud-0.1.0/fluidcloud/__init__.py

@@ -0,0 +1,40 @@
+"""FluidCloud — official Python SDK.
+
+    from fluidcloud import FluidCloud
+    fc = FluidCloud(api_key="fck_live_...")
+    asset = fc.files.upload("logo.png", space_id=space_id, public=True)
+    print(asset.public_url)
+"""
+
+from .client import FluidCloud
+from .errors import (
+    ApiError,
+    AuthError,
+    ConflictError,
+    FluidCloudError,
+    NotFoundError,
+    PermissionError_,
+    QuotaExceededError,
+)
+from .models import DelegatedToken, File, Folder, Link, Quota, Share, Space
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FluidCloud",
+    "FluidCloudError",
+    "ApiError",
+    "AuthError",
+    "PermissionError_",
+    "NotFoundError",
+    "QuotaExceededError",
+    "ConflictError",
+    "Space",
+    "Folder",
+    "File",
+    "Quota",
+    "Link",
+    "Share",
+    "DelegatedToken",
+    "__version__",
+]

fluidcloud-0.1.0/fluidcloud/client.py

@@ -0,0 +1,420 @@
+"""FluidCloud Python client.
+
+    from fluidcloud import FluidCloud
+    fc = FluidCloud(api_key="fck_live_...")          # base_url defaults to prod
+
+    sp = fc.spaces.create("Brand Assets")
+    asset = fc.files.upload("logo.png", space_id=sp.id, public=True)
+    print(asset.public_url)                          # stable hotlinkable URL
+
+The client targets the versioned API (``/api/v1``) and authenticates with a
+first-party API key: ``fck_…`` keys are sent as ``X-API-Key``; any other value is
+treated as a bearer token (a Supabase JWT) and sent as ``Authorization: Bearer``.
+``files.upload`` hides the whole presign -> direct-PUT -> complete flow, including
+multipart for files >= 100 MB.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import mimetypes
+import os
+from typing import Any, BinaryIO, Dict, List, Optional, Tuple, Union
+
+import httpx
+
+from .errors import ApiError, error_for
+from .models import DelegatedToken, File, Folder, Link, Quota, Share, Space
+
+__all__ = ["FluidCloud"]
+
+PathOrData = Union[str, bytes, bytearray, BinaryIO]
+
+DEFAULT_BASE_URL = "https://api-cloud.fluidvip.com"
+
+
+def _drop_none(d: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+class FluidCloud:
+    """The FluidCloud API client.
+
+    Args:
+        api_key: A first-party API key (``fck_live_…`` / ``fck_test_…``) sent as
+            ``X-API-Key``, or a Supabase JWT (sent as a bearer token).
+        base_url: API origin. Defaults to production
+            (``https://api-cloud.fluidvip.com``); point at
+            ``https://api-green-cloud.fluidvip.com`` for the green/test stack.
+        api_version: API version segment. Defaults to ``"v1"``.
+        timeout: Per-request timeout in seconds (uploads can be slow — default 300).
+        http_client: An optional pre-built ``httpx.Client`` (handy for tests/mocks).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        api_version: str = "v1",
+        timeout: float = 300.0,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._api = f"{self._base_url}/api/{api_version}"
+        self._http = http_client or httpx.Client(timeout=timeout)
+
+        self.spaces = _Spaces(self)
+        self.folders = _Folders(self)
+        self.files = _Files(self)
+        self.shares = _Shares(self)
+        self.quota = _Quota(self)
+
+    # -- cross-service delegation (federation) ------------------------------
+    def exchange_service_token(
+        self,
+        user_jwt: str,
+        app: str,
+        *,
+        job_id: Optional[str] = None,
+        ttl_seconds: Optional[int] = None,
+    ) -> DelegatedToken:
+        """Trade this (service) key + an end user's Supabase JWT for a delegation token.
+
+        First-party only: the key must hold ``service:delegate`` (and
+        ``service:jobtoken`` when ``job_id`` is given, for a longer-lived worker
+        token). The returned ``fcd_`` token acts AS the user, scoped to their
+        tenant + ``app`` namespace. See :meth:`as_user` for a ready-bound client.
+        """
+        body = _drop_none(
+            {"user_jwt": user_jwt, "app": app, "job_id": job_id, "ttl_seconds": ttl_seconds}
+        )
+        return DelegatedToken.from_dict(self._request("POST", "/auth/service-token", json=body))
+
+    def as_user(
+        self,
+        user_jwt: str,
+        app: str,
+        *,
+        job_id: Optional[str] = None,
+        ttl_seconds: Optional[int] = None,
+        timeout: float = 300.0,
+    ) -> "FluidCloud":
+        """Return a NEW client that acts AS the end user (federation).
+
+        Exchanges this service key + the user's JWT for a delegation token and
+        returns a :class:`FluidCloud` bound to it — so a federated product
+        (FluidTalk/FluidGhost) stores + serves a user's media in the USER's tenant
+        with unchanged call sites. The new client reuses this one's base URL +
+        HTTP client.
+        """
+        token = self.exchange_service_token(user_jwt, app, job_id=job_id, ttl_seconds=ttl_seconds)
+        return FluidCloud(api_key=token.token, base_url=self._base_url, timeout=timeout, http_client=self._http)
+
+    # -- lifecycle ----------------------------------------------------------
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "FluidCloud":
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.close()
+
+    # -- low-level HTTP -----------------------------------------------------
+    def _auth_headers(self) -> Dict[str, str]:
+        if self._api_key.startswith("fck_"):
+            return {"X-API-Key": self._api_key}
+        return {"Authorization": f"Bearer {self._api_key}"}
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        resp = self._http.request(
+            method,
+            self._api + path,
+            json=json,
+            params=params,
+            headers={"Accept": "application/json", **self._auth_headers()},
+        )
+        return self._handle(resp)
+
+    @staticmethod
+    def _handle(resp: httpx.Response) -> Any:
+        if resp.status_code == 204 or not resp.content:
+            if resp.is_success:
+                return None
+        if resp.is_success:
+            return resp.json()
+        detail: Any
+        try:
+            detail = resp.json().get("detail")
+        except Exception:
+            detail = resp.text
+        raise error_for(resp.status_code, detail)
+
+    def _put_bytes(self, url: str, data: bytes, content_type: Optional[str]) -> str:
+        """PUT raw bytes to a presigned URL (NOT an API call — no auth header).
+
+        Returns the object's ETag (needed to complete a multipart upload).
+        """
+        headers = {"Content-Type": content_type} if content_type else {}
+        resp = self._http.put(url, content=data, headers=headers)
+        if not resp.is_success:
+            raise ApiError(resp.status_code, resp.text[:300], message="presigned upload PUT failed")
+        return resp.headers.get("etag", "")
+
+
+# ---------------------------------------------------------------------------
+# Upload source normalization
+# ---------------------------------------------------------------------------
+
+def _normalize_source(
+    file: PathOrData,
+    name: Optional[str],
+    content_type: Optional[str],
+) -> Tuple[BinaryIO, int, str, str]:
+    """Resolve (stream, size, name, content_type) from a path / bytes / file object."""
+    if isinstance(file, (bytes, bytearray)):
+        stream: BinaryIO = io.BytesIO(bytes(file))
+        size = len(file)
+        name = name or "upload.bin"
+    elif isinstance(file, str):
+        size = os.path.getsize(file)
+        name = name or os.path.basename(file)
+        stream = open(file, "rb")  # noqa: SIM115 (closed by the caller via upload())
+    elif hasattr(file, "read"):
+        stream = file  # type: ignore[assignment]
+        # Determine size by seeking, restoring the original position afterward.
+        pos = stream.tell()
+        stream.seek(0, os.SEEK_END)
+        size = stream.tell() - pos
+        stream.seek(pos)
+        name = name or getattr(file, "name", None) or "upload.bin"
+        if name:
+            name = os.path.basename(str(name))
+    else:
+        raise TypeError("file must be a path (str), bytes, or a binary file object")
+
+    if not content_type:
+        content_type = mimetypes.guess_type(name)[0] or "application/octet-stream"
+    return stream, size, name, content_type
+
+
+# ---------------------------------------------------------------------------
+# Resources
+# ---------------------------------------------------------------------------
+
+class _Resource:
+    def __init__(self, client: FluidCloud) -> None:
+        self._c = client
+
+
+class _Spaces(_Resource):
+    def list(self) -> List[Space]:
+        return [Space.from_dict(x) for x in self._c._request("GET", "/spaces")]
+
+    def create(self, name: str) -> Space:
+        return Space.from_dict(self._c._request("POST", "/spaces", json={"name": name}))
+
+
+class _Folders(_Resource):
+    def list(self, space_id: str, parent_id: Optional[str] = None, *, trash: bool = False) -> List[Folder]:
+        params = _drop_none({"space_id": space_id, "parent_id": parent_id, "trash": trash})
+        return [Folder.from_dict(x) for x in self._c._request("GET", "/folders", params=params)]
+
+    def create(self, name: str, space_id: str, parent_id: Optional[str] = None) -> Folder:
+        body = _drop_none({"name": name, "space_id": space_id, "parent_id": parent_id})
+        return Folder.from_dict(self._c._request("POST", "/folders", json=body))
+
+    def rename(self, folder_id: str, name: str) -> Folder:
+        return Folder.from_dict(self._c._request("PATCH", f"/folders/{folder_id}", json={"name": name}))
+
+    def move(self, folder_id: str, parent_id: Optional[str]) -> Folder:
+        # parent_id is sent EXPLICITLY (incl. null = move to space root).
+        return Folder.from_dict(
+            self._c._request("PATCH", f"/folders/{folder_id}", json={"parent_id": parent_id})
+        )
+
+    def delete(self, folder_id: str) -> Folder:
+        return Folder.from_dict(self._c._request("DELETE", f"/folders/{folder_id}"))
+
+    def restore(self, folder_id: str) -> Folder:
+        return Folder.from_dict(self._c._request("POST", f"/folders/{folder_id}/restore"))
+
+
+class _Files(_Resource):
+    def upload(
+        self,
+        file: PathOrData,
+        space_id: str,
+        *,
+        folder_id: Optional[str] = None,
+        name: Optional[str] = None,
+        content_type: Optional[str] = None,
+        public: bool = False,
+        app: Optional[str] = None,
+        client_key: Optional[str] = None,
+    ) -> File:
+        """Upload a file and return the stored :class:`~fluidcloud.models.File`.
+
+        Hides the full flow: presign (single PUT for <100 MB, multipart otherwise)
+        -> direct upload to storage -> complete. When ``public=True`` a permanent
+        public link is minted and set on the result's ``public_url``.
+
+        Args:
+            file: A filesystem path, raw ``bytes``, or an open binary file object.
+            space_id: The Space to store the file in.
+            folder_id: Optional folder within the Space (default: Space root).
+            name: Override the stored filename (default: derived from the source).
+            content_type: Override the MIME type (default: guessed from the name).
+            public: Also mint a stable public hotlink and set ``result.public_url``.
+            app: Federation — the originating product (e.g. ``"fluidtalk"``); tags
+                + key-namespaces the object. Omit for the native app.
+            client_key: Federation — the caller's own logical key, so it can later
+                ``files.resolve(client_key, app=...)`` without a local key->id map.
+        """
+        stream, size, name, content_type = _normalize_source(file, name, content_type)
+        opened_path = isinstance(file, str)
+        try:
+            ticket = self._c._request(
+                "POST",
+                "/uploads/initiate",
+                json={
+                    "original_name": name,
+                    "content_type": content_type,
+                    "size": size,
+                    "space_id": space_id,
+                    "folder_id": folder_id,
+                    "app": app,
+                },
+            )
+            digest = hashlib.sha256()
+            upload_id: Optional[str] = None
+            parts: Optional[List[Dict[str, Any]]] = None
+
+            if ticket["mode"] == "single":
+                data = stream.read()
+                digest.update(data)
+                self._c._put_bytes(ticket["upload_url"], data, content_type)
+            else:
+                upload_id = ticket["upload_id"]
+                part_size = int(ticket["part_size"])
+                parts = []
+                for part in ticket["part_urls"]:
+                    chunk = stream.read(part_size)
+                    digest.update(chunk)
+                    etag = self._c._put_bytes(part["url"], chunk, None)
+                    parts.append({"PartNumber": part["part_number"], "ETag": etag})
+
+            row = self._c._request(
+                "POST",
+                "/uploads/complete",
+                json={
+                    "file_id": ticket["file_id"],
+                    "key": ticket["key"],
+                    "upload_id": upload_id,
+                    "parts": parts,
+                    "original_name": name,
+                    "mime": content_type,
+                    "size": size,
+                    "sha256": digest.hexdigest(),
+                    "space_id": space_id,
+                    "folder_id": folder_id,
+                    "app": app,
+                    "client_key": client_key,
+                },
+            )
+        finally:
+            if opened_path:
+                stream.close()
+
+        result = File.from_dict(row)
+        if public:
+            result.public_url = self.public_url(result.id).url
+        return result
+
+    def list(
+        self,
+        space_id: str,
+        folder_id: Optional[str] = None,
+        *,
+        trash: bool = False,
+        app: Optional[str] = None,
+    ) -> List[File]:
+        params = _drop_none({"space_id": space_id, "folder_id": folder_id, "trash": trash, "app": app})
+        return [File.from_dict(x) for x in self._c._request("GET", "/files", params=params)]
+
+    def get(self, file_id: str) -> File:
+        return File.from_dict(self._c._request("GET", f"/files/{file_id}"))
+
+    def resolve(self, client_key: str, *, app: Optional[str] = None) -> File:
+        """Resolve a file by the caller's own logical ``client_key`` (federation).
+
+        Lets a federated client fetch the file it uploaded under its own key
+        without keeping a key->id map. Scoped to the caller's tenant + ``app``
+        namespace; raises ``NotFoundError`` if there's no live match.
+        """
+        params = _drop_none({"client_key": client_key, "app": app})
+        return File.from_dict(self._c._request("GET", "/files/resolve", params=params))
+
+    def rename(self, file_id: str, name: str) -> File:
+        return File.from_dict(self._c._request("PATCH", f"/files/{file_id}", json={"original_name": name}))
+
+    def move(self, file_id: str, folder_id: Optional[str]) -> File:
+        return File.from_dict(self._c._request("PATCH", f"/files/{file_id}", json={"folder_id": folder_id}))
+
+    def delete(self, file_id: str) -> File:
+        return File.from_dict(self._c._request("DELETE", f"/files/{file_id}"))
+
+    def restore(self, file_id: str) -> File:
+        return File.from_dict(self._c._request("POST", f"/files/{file_id}/restore"))
+
+    def download_url(self, file_id: str) -> str:
+        """A short-lived presigned GET URL for the OWNER to download the file."""
+        return self._c._request("GET", f"/files/{file_id}/download")["url"]
+
+    def public_url(self, file_id: str) -> Link:
+        """Mint (and return) a STABLE PUBLIC hotlink — a permanent, inline,
+        cacheable URL suitable for ``<img>``/embeds. Never expires until revoked.
+        """
+        return Link.from_dict(
+            self._c._request("POST", "/shares", json={"file_id": file_id, "expires_in_days": None})
+        )
+
+    def signed_url(self, file_id: str, *, expires_in_days: int = 7, permission: str = "view") -> Link:
+        """Mint an EXPIRING share link (1..365 days)."""
+        return Link.from_dict(
+            self._c._request(
+                "POST",
+                "/shares",
+                json={
+                    "file_id": file_id,
+                    "expires_in_days": expires_in_days,
+                    "permission": permission,
+                },
+            )
+        )
+
+
+class _Shares(_Resource):
+    def list(self, *, file_id: Optional[str] = None, include_inactive: bool = False) -> List[Share]:
+        params = _drop_none({"file_id": file_id, "include_inactive": include_inactive})
+        return [Share.from_dict(x) for x in self._c._request("GET", "/shares", params=params)]
+
+    def revoke(self, share_id: str) -> None:
+        self._c._request("DELETE", f"/shares/{share_id}")
+
+
+class _Quota(_Resource):
+    def usage(self) -> Quota:
+        return Quota.from_dict(self._c._request("GET", "/quota"))

fluidcloud-0.1.0/fluidcloud/errors.py

@@ -0,0 +1,62 @@
+"""Typed exceptions raised by the FluidCloud SDK.
+
+Every non-2xx API response is mapped to one of these. They all derive from
+:class:`FluidCloudError`, so callers can ``except FluidCloudError`` to catch any
+SDK/API failure, or catch a specific subclass (e.g. :class:`QuotaExceededError`)
+to handle it.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class FluidCloudError(Exception):
+    """Base class for every error this SDK raises."""
+
+
+class ApiError(FluidCloudError):
+    """A non-2xx HTTP response from the FluidCloud API (or a presigned PUT).
+
+    Attributes:
+        status: The HTTP status code.
+        detail: The parsed ``detail`` field of the error body (str or dict), or
+            the raw response text when it wasn't JSON.
+    """
+
+    def __init__(self, status: int, detail: Any = None, message: Optional[str] = None):
+        self.status = status
+        self.detail = detail
+        super().__init__(message or f"FluidCloud API error {status}: {detail!r}")
+
+
+class AuthError(ApiError):
+    """401 — the API key / token is missing, malformed, or revoked."""
+
+
+class PermissionError_(ApiError):
+    """403 — the key lacks a required scope (``insufficient_scope``) or access."""
+
+
+class NotFoundError(ApiError):
+    """404 — the resource does not exist within the caller's tenant."""
+
+
+class QuotaExceededError(ApiError):
+    """402 — the tenant is over its storage / share-link cap."""
+
+
+class ConflictError(ApiError):
+    """409 — e.g. sharing a file that has not finished scanning (not 'clean')."""
+
+
+def error_for(status: int, detail: Any) -> ApiError:
+    """Map an HTTP status + parsed detail to the most specific ApiError subclass."""
+    cls = {
+        401: AuthError,
+        402: QuotaExceededError,
+        403: PermissionError_,
+        404: NotFoundError,
+        409: ConflictError,
+    }.get(status, ApiError)
+    return cls(status, detail)

fluidcloud-0.1.0/fluidcloud/models.py

@@ -0,0 +1,125 @@
+"""Typed result objects returned by the SDK.
+
+These are light dataclasses mirroring the API's response shapes (FastAPI
+serializes UUID/datetime columns to strings, so ids and timestamps are ``str``).
+Each ``from_dict`` ignores unknown keys so a server that adds a field never breaks
+an older SDK.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+from typing import Optional, Type, TypeVar
+
+T = TypeVar("T", bound="_Model")
+
+
+class _Model:
+    @classmethod
+    def from_dict(cls: Type[T], data: dict) -> T:
+        """Build the dataclass from a response dict, dropping unknown keys."""
+        known = {f.name for f in fields(cls)}  # type: ignore[arg-type]
+        return cls(**{k: v for k, v in data.items() if k in known})  # type: ignore[arg-type]
+
+
+@dataclass
+class Space(_Model):
+    id: str
+    name: str
+    tenant_id: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+
+@dataclass
+class Folder(_Model):
+    id: str
+    name: str
+    space_id: Optional[str] = None
+    parent_id: Optional[str] = None
+    tenant_id: Optional[str] = None
+    deleted_at: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+
+@dataclass
+class File(_Model):
+    id: str
+    original_name: str
+    name: Optional[str] = None
+    space_id: Optional[str] = None
+    folder_id: Optional[str] = None
+    tenant_id: Optional[str] = None
+    mime: Optional[str] = None
+    size: Optional[int] = None
+    sha256: Optional[str] = None
+    scan_status: Optional[str] = None
+    status: Optional[str] = None
+    created_by: Optional[str] = None
+    # Federation (Ecosystem Storage Federation): the originating product, and the
+    # caller's own logical key (when uploaded by a federated client).
+    source_app: Optional[str] = None
+    client_key: Optional[str] = None
+    deleted_at: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+    # Set by files.upload(..., public=True): the stable public hotlink URL.
+    public_url: Optional[str] = None
+
+
+@dataclass
+class DelegatedToken(_Model):
+    """The result of a cross-service token exchange (federation).
+
+    A first-party service trades its key + an end user's JWT for ``token`` (an
+    ``fcd_`` delegation token) that acts AS that user. Use ``FluidCloud.as_user``
+    to get a client already bound to it.
+    """
+
+    token: str
+    expires_in: int = 0
+    tenant_id: Optional[str] = None
+    user_id: Optional[str] = None
+    app: Optional[str] = None
+    token_type: str = "Bearer"
+
+
+@dataclass
+class Quota(_Model):
+    bytes_used: int
+    bytes_limit: int
+    links_used: int
+    links_limit: int
+    # Per-product storage footprint within the shared pool (federation).
+    by_app: Optional[list] = None
+
+
+@dataclass
+class Link(_Model):
+    """A minted share link (the create response). ``url`` is the raw file URL.
+
+    ``expires_at`` is ``None`` for a PERMANENT public link (``files.public_url``);
+    an ISO-8601 string for an expiring one (``files.signed_url``).
+    """
+
+    url: str
+    id: str
+    permission: str = "view"
+    expires_at: Optional[str] = None
+
+
+@dataclass
+class Share(_Model):
+    """A listed share link (``shares.list``) — the token itself is never returned."""
+
+    id: str
+    file_id: str
+    permission: str
+    expires_at: Optional[str] = None
+    max_downloads: Optional[int] = None
+    download_count: int = 0
+    revoked: bool = False
+    has_password: bool = False
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None

fluidcloud-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fluidcloud"
+version = "0.1.0"
+description = "Official Python SDK for FluidCloud — private file storage, shareable raw links, and stable public (hotlinkable) URLs."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+authors = [{ name = "Fluidvip" }]
+keywords = ["fluidcloud", "storage", "uploads", "cdn", "share-links"]
+dependencies = ["httpx>=0.24"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://cloud.fluidvip.com"
+Source = "https://github.com/Trebuu/FluidCloud"
+
+[tool.hatch.build.targets.wheel]
+packages = ["fluidcloud"]

fluidcloud-0.1.0/tests/test_client.py

@@ -0,0 +1,263 @@
+"""Unit tests for the FluidCloud SDK using httpx MockTransport (no network).
+
+These assert the SDK's request *shapes* — that upload() walks initiate -> PUT ->
+complete, that the presigned PUT carries no API auth, that public_url posts
+expires_in_days=null, that auth headers are chosen correctly, and that errors map
+to typed exceptions.
+"""
+
+from __future__ import annotations
+
+import json as jsonlib
+
+import httpx
+import pytest
+
+from fluidcloud import FluidCloud
+from fluidcloud.errors import PermissionError_, QuotaExceededError
+
+
+def _client(handler, api_key="fck_live_test"):
+    transport = httpx.MockTransport(handler)
+    return FluidCloud(api_key=api_key, base_url="https://api.test", http_client=httpx.Client(transport=transport))
+
+
+def _body(request):
+    return jsonlib.loads(request.content.decode())
+
+
+# ---------------------------------------------------------------------------
+# Auth header selection
+# ---------------------------------------------------------------------------
+
+def test_fck_key_uses_x_api_key():
+    seen = {}
+
+    def handler(request):
+        seen["x-api-key"] = request.headers.get("x-api-key")
+        seen["authorization"] = request.headers.get("authorization")
+        return httpx.Response(200, json=[])
+
+    _client(handler, api_key="fck_live_abc").spaces.list()
+    assert seen["x-api-key"] == "fck_live_abc"
+    assert seen["authorization"] is None
+
+
+def test_jwt_uses_bearer():
+    seen = {}
+
+    def handler(request):
+        seen["x-api-key"] = request.headers.get("x-api-key")
+        seen["authorization"] = request.headers.get("authorization")
+        return httpx.Response(200, json=[])
+
+    _client(handler, api_key="eyJhbG.payload.sig").spaces.list()
+    assert seen["authorization"] == "Bearer eyJhbG.payload.sig"
+    assert seen["x-api-key"] is None
+
+
+# ---------------------------------------------------------------------------
+# Upload (single) + public link
+# ---------------------------------------------------------------------------
+
+def test_upload_single_public():
+    seen = {"put_auth": "unset"}
+
+    def handler(request):
+        p = request.url.path
+        if request.method == "POST" and p == "/api/v1/uploads/initiate":
+            b = _body(request)
+            assert b["original_name"] == "logo.png"
+            assert b["space_id"] == "sp1"
+            assert b["content_type"] == "image/png"
+            return httpx.Response(200, json={
+                "file_id": "f1", "key": "t/sp1/incoming/f1.png",
+                "mode": "single", "upload_url": "https://r2.test/put/f1",
+            })
+        if request.method == "PUT" and request.url.host == "r2.test":
+            # The presigned PUT must NOT carry the API key.
+            seen["put_auth"] = request.headers.get("x-api-key")
+            assert request.headers.get("content-type") == "image/png"
+            return httpx.Response(200, headers={"ETag": '"etag1"'})
+        if request.method == "POST" and p == "/api/v1/uploads/complete":
+            b = _body(request)
+            assert b["file_id"] == "f1"
+            assert b["key"] == "t/sp1/incoming/f1.png"
+            assert b["upload_id"] is None and b["parts"] is None
+            assert b["sha256"] and len(b["sha256"]) == 64  # computed client-side
+            return httpx.Response(200, json={
+                "id": "f1", "original_name": "logo.png",
+                "scan_status": "clean", "status": "pending", "size": 8,
+            })
+        if request.method == "POST" and p == "/api/v1/shares":
+            b = _body(request)
+            assert b["file_id"] == "f1"
+            assert b["expires_in_days"] is None  # permanent / public
+            return httpx.Response(201, json={
+                "url": "https://files.test/s/TOKEN", "id": "sh1",
+                "permission": "view", "expires_at": None,
+            })
+        return httpx.Response(404, json={"detail": "unexpected"})
+
+    asset = _client(handler).files.upload(b"\x89PNGdata", space_id="sp1", name="logo.png", public=True)
+    assert asset.id == "f1"
+    assert asset.scan_status == "clean"
+    assert asset.public_url == "https://files.test/s/TOKEN"
+    assert seen["put_auth"] is None  # no API auth on the presigned PUT
+
+
+# ---------------------------------------------------------------------------
+# Upload (multipart)
+# ---------------------------------------------------------------------------
+
+def test_upload_multipart():
+    puts = []
+
+    def handler(request):
+        p = request.url.path
+        if p == "/api/v1/uploads/initiate":
+            return httpx.Response(200, json={
+                "file_id": "f2", "key": "t/sp1/incoming/f2.bin", "mode": "multipart",
+                "upload_id": "U1", "part_size": 5,
+                "part_urls": [
+                    {"part_number": 1, "url": "https://r2.test/part/1"},
+                    {"part_number": 2, "url": "https://r2.test/part/2"},
+                ],
+            })
+        if request.method == "PUT" and request.url.host == "r2.test":
+            puts.append(len(request.content))
+            n = request.url.path.split("/")[-1]
+            return httpx.Response(200, headers={"ETag": f'"e{n}"'})
+        if p == "/api/v1/uploads/complete":
+            b = _body(request)
+            assert b["upload_id"] == "U1"
+            assert b["parts"] == [
+                {"PartNumber": 1, "ETag": '"e1"'},
+                {"PartNumber": 2, "ETag": '"e2"'},
+            ]
+            return httpx.Response(200, json={"id": "f2", "original_name": "f2.bin"})
+        return httpx.Response(404, json={"detail": "unexpected"})
+
+    asset = _client(handler).files.upload(b"0123456789", space_id="sp1", name="f2.bin")
+    assert asset.id == "f2"
+    assert puts == [5, 5]  # two 5-byte parts
+
+
+# ---------------------------------------------------------------------------
+# Links
+# ---------------------------------------------------------------------------
+
+def test_signed_url_sends_expiry():
+    def handler(request):
+        b = _body(request)
+        assert b["expires_in_days"] == 14
+        assert b["permission"] == "download"
+        return httpx.Response(201, json={
+            "url": "https://files.test/s/T2", "id": "sh2",
+            "permission": "download", "expires_at": "2026-07-01T00:00:00Z",
+        })
+
+    link = _client(handler).files.signed_url("f1", expires_in_days=14, permission="download")
+    assert link.url == "https://files.test/s/T2"
+    assert link.expires_at is not None
+
+
+# ---------------------------------------------------------------------------
+# Error mapping
+# ---------------------------------------------------------------------------
+
+def test_403_maps_to_permission_error():
+    def handler(request):
+        return httpx.Response(403, json={"detail": {"error": "insufficient_scope", "required": ["files:write"]}})
+
+    with pytest.raises(PermissionError_) as ei:
+        _client(handler).files.delete("f1")
+    assert ei.value.status == 403
+
+
+def test_402_maps_to_quota_error():
+    def handler(request):
+        return httpx.Response(402, json={"detail": "quota_exceeded"})
+
+    with pytest.raises(QuotaExceededError):
+        _client(handler).files.upload(b"x", space_id="sp1", name="x.bin")
+
+
+# ---------------------------------------------------------------------------
+# Federation: app namespacing + client_key + resolve + delegation
+# ---------------------------------------------------------------------------
+
+def test_upload_passes_app_and_client_key():
+    seen = {}
+
+    def handler(request):
+        p = request.url.path
+        if p == "/api/v1/uploads/initiate":
+            seen["initiate"] = _body(request)
+            return httpx.Response(200, json={
+                "file_id": "f1", "key": "t/fluidtalk/sp1/incoming/f1.png",
+                "mode": "single", "upload_url": "https://r2.test/put/f1",
+            })
+        if request.method == "PUT" and request.url.host == "r2.test":
+            return httpx.Response(200, headers={"ETag": '"e"'})
+        if p == "/api/v1/uploads/complete":
+            seen["complete"] = _body(request)
+            return httpx.Response(200, json={
+                "id": "f1", "original_name": "p.png", "source_app": "fluidtalk",
+                "client_key": "personas/9/p.png",
+            })
+        return httpx.Response(404, json={"detail": "unexpected"})
+
+    asset = _client(handler).files.upload(
+        b"x", space_id="sp1", name="p.png", app="fluidtalk", client_key="personas/9/p.png",
+    )
+    assert seen["initiate"]["app"] == "fluidtalk"
+    assert seen["complete"]["app"] == "fluidtalk"
+    assert seen["complete"]["client_key"] == "personas/9/p.png"
+    assert asset.source_app == "fluidtalk"
+    assert asset.client_key == "personas/9/p.png"
+
+
+def test_files_resolve_by_client_key():
+    def handler(request):
+        assert request.url.path == "/api/v1/files/resolve"
+        assert dict(request.url.params)["client_key"] == "personas/9/p.png"
+        assert dict(request.url.params)["app"] == "fluidtalk"
+        return httpx.Response(200, json={"id": "f1", "original_name": "p.png", "client_key": "personas/9/p.png"})
+
+    f = _client(handler).files.resolve("personas/9/p.png", app="fluidtalk")
+    assert f.id == "f1"
+
+
+def test_exchange_service_token_and_as_user():
+    seen = {}
+
+    def handler(request):
+        p = request.url.path
+        if p == "/api/v1/auth/service-token":
+            seen["exchange_body"] = _body(request)
+            seen["exchange_auth"] = request.headers.get("x-api-key")
+            return httpx.Response(200, json={
+                "token": "fcd_USERTOKEN", "expires_in": 3600,
+                "tenant_id": "tenant-1", "user_id": "user-9", "app": "fluidtalk",
+            })
+        if p == "/api/v1/spaces":
+            # The as_user client must authenticate with the fcd_ token as Bearer.
+            seen["asuser_bearer"] = request.headers.get("authorization")
+            seen["asuser_xapikey"] = request.headers.get("x-api-key")
+            return httpx.Response(200, json=[])
+        return httpx.Response(404, json={"detail": "unexpected"})
+
+    fc = _client(handler, api_key="fck_live_svc")
+    tok = fc.exchange_service_token("user.jwt", "fluidtalk", job_id="job-1")
+    assert tok.token == "fcd_USERTOKEN"
+    assert tok.tenant_id == "tenant-1"
+    assert seen["exchange_auth"] == "fck_live_svc"  # service key auths the exchange
+    assert seen["exchange_body"]["user_jwt"] == "user.jwt"
+    assert seen["exchange_body"]["job_id"] == "job-1"
+
+    # as_user() returns a client bound to the delegation token.
+    user_client = fc.as_user("user.jwt", "fluidtalk")
+    user_client.spaces.list()
+    assert seen["asuser_bearer"] == "Bearer fcd_USERTOKEN"
+    assert seen["asuser_xapikey"] is None

fluidcloud-0.1.0/tests/test_e2e_green.py

@@ -0,0 +1,56 @@
+"""Live integration test — skipped unless FLUIDCLOUD_API_KEY is set.
+
+Run against a real FluidCloud stack:
+
+    FLUIDCLOUD_API_KEY=fck_live_... \
+    FLUIDCLOUD_BASE_URL=https://api-green-cloud.fluidvip.com \
+    pytest tests/test_e2e_green.py -v
+
+It uploads a tiny PNG, publishes a permanent link, fetches that hotlink (hitting
+the share Worker) and checks the bytes, then cleans up.
+"""
+
+from __future__ import annotations
+
+import os
+import urllib.request
+
+import pytest
+
+from fluidcloud import FluidCloud
+
+API_KEY = os.environ.get("FLUIDCLOUD_API_KEY")
+BASE_URL = os.environ.get("FLUIDCLOUD_BASE_URL", "https://api-green-cloud.fluidvip.com")
+
+pytestmark = pytest.mark.skipif(
+    not API_KEY, reason="set FLUIDCLOUD_API_KEY to run the live integration test"
+)
+
+# A 1x1 PNG (valid magic bytes so the server-side scan allowlists it).
+PNG = bytes(
+    [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0, 0, 0, 0x0D, 0x49, 0x48,
+     0x44, 0x52, 0, 0, 0, 1, 0, 0, 0, 1, 8, 6, 0, 0, 0, 0x1F, 0x15, 0xC4, 0x89,
+     0, 0, 0, 0x0D, 0x49, 0x44, 0x41, 0x54, 0x78, 0x9C, 0x62, 0, 1, 0, 0, 5, 0,
+     1, 0x0D, 0x0A, 0x2D, 0xB4, 0, 0, 0, 0, 0x49, 0x45, 0x4E, 0x44, 0xAE, 0x42,
+     0x60, 0x82]
+)
+
+
+def test_live_upload_public_fetch_delete():
+    fc = FluidCloud(api_key=API_KEY, base_url=BASE_URL)
+    try:
+        space_id = fc.spaces.list()[0].id
+        asset = fc.files.upload(PNG, space_id=space_id, name="ci_e2e.png", public=True)
+        assert asset.scan_status == "clean"
+        assert asset.public_url
+
+        req = urllib.request.Request(asset.public_url, headers={"User-Agent": "Mozilla/5.0"})
+        resp = urllib.request.urlopen(req, timeout=40)
+        assert resp.status == 200
+        assert resp.read() == PNG
+        assert resp.headers.get("content-type") == "image/png"
+
+        assert any(f.id == asset.id for f in fc.files.list(space_id))
+        fc.files.delete(asset.id)
+    finally:
+        fc.close()