filoo-sdk 0.1.0__tar.gz

filoo_sdk-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+node_modules/
+dist/
+.wrangler/
+.env
+.env.local
+.env.*.local
+*.log
+.DS_Store
+public/app.css
+.idea/
+.vscode/
+coverage/
+# SDK build artifacts
+sdk/typescript/dist/
+sdk/typescript/node_modules/
+sdk/typescript/package-lock.json
+sdk/python/dist/
+sdk/python/build/
+sdk/python/*.egg-info/
+sdk/python/__pycache__/
+sdk/python/filoo/__pycache__/

filoo_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: filoo-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the Filoo URL shortener API.
+Project-URL: Homepage, https://filoo.app/api
+Project-URL: Repository, https://github.com/jrlprost/filooapp
+Author: Filoo
+License: MIT
+Keywords: filoo,qr-code,url-shortener
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# filoo-sdk
+
+Official Python SDK for the [Filoo](https://filoo.app) URL shortener API.
+
+## Install
+
+```bash
+pip install filoo-sdk
+```
+
+## Quick start
+
+```python
+from filoo import Filoo
+import os
+
+with Filoo(api_key=os.environ["FILOO_KEY"]) as filoo:
+    link = filoo.links.create(
+        destination="https://example.com/long-url",
+        username="myname",
+        slug="campaign-1",
+    )
+    print(link["short_url"])  # → https://filoo.app/myname/campaign-1
+```
+
+## Available methods
+
+- `filoo.me()`
+- `filoo.usage()`
+- `filoo.usernames()`
+- `filoo.links.create(destination, ...)`
+- `filoo.links.list(limit=, cursor=)`
+- `filoo.links.get(code)`
+- `filoo.links.update(code, **fields)`
+- `filoo.links.delete(code)`
+- `filoo.links.stats(code)`
+
+## Tier requirement
+
+The Filoo API is available on **Pro** (€9/month, 100 req/min) and **Agents** (€29/month, 1000 req/min) plans. Get a key at [filoo.app/dashboard/api-keys](https://filoo.app/dashboard/api-keys).
+
+## Errors
+
+`FilooError` is raised on non-2xx responses. Check `error.status` and `error.body`.
+
+```python
+from filoo import Filoo, FilooError
+
+try:
+    filoo.links.create(destination="...")
+except FilooError as e:
+    if e.status == 429:
+        print("Rate limited, retry later")
+```
+
+## License
+
+MIT

filoo_sdk-0.1.0/README.md

@@ -0,0 +1,58 @@
+# filoo-sdk
+
+Official Python SDK for the [Filoo](https://filoo.app) URL shortener API.
+
+## Install
+
+```bash
+pip install filoo-sdk
+```
+
+## Quick start
+
+```python
+from filoo import Filoo
+import os
+
+with Filoo(api_key=os.environ["FILOO_KEY"]) as filoo:
+    link = filoo.links.create(
+        destination="https://example.com/long-url",
+        username="myname",
+        slug="campaign-1",
+    )
+    print(link["short_url"])  # → https://filoo.app/myname/campaign-1
+```
+
+## Available methods
+
+- `filoo.me()`
+- `filoo.usage()`
+- `filoo.usernames()`
+- `filoo.links.create(destination, ...)`
+- `filoo.links.list(limit=, cursor=)`
+- `filoo.links.get(code)`
+- `filoo.links.update(code, **fields)`
+- `filoo.links.delete(code)`
+- `filoo.links.stats(code)`
+
+## Tier requirement
+
+The Filoo API is available on **Pro** (€9/month, 100 req/min) and **Agents** (€29/month, 1000 req/min) plans. Get a key at [filoo.app/dashboard/api-keys](https://filoo.app/dashboard/api-keys).
+
+## Errors
+
+`FilooError` is raised on non-2xx responses. Check `error.status` and `error.body`.
+
+```python
+from filoo import Filoo, FilooError
+
+try:
+    filoo.links.create(destination="...")
+except FilooError as e:
+    if e.status == 429:
+        print("Rate limited, retry later")
+```
+
+## License
+
+MIT

filoo_sdk-0.1.0/filoo/__init__.py

@@ -0,0 +1,144 @@
+"""Official Python SDK for the Filoo URL shortener API.
+
+Usage:
+    from filoo import Filoo
+    import os
+
+    filoo = Filoo(api_key=os.environ["FILOO_KEY"])
+    link = filoo.links.create(
+        destination="https://example.com",
+        username="myname",
+        slug="campaign-1",
+    )
+    print(link["short_url"])
+"""
+
+from typing import Any, Optional
+
+import httpx
+
+
+__version__ = "0.1.0"
+
+
+class FilooError(Exception):
+    """Raised on non-2xx HTTP responses from the Filoo API."""
+
+    def __init__(self, status: int, body: str):
+        self.status = status
+        self.body = body
+        super().__init__(f"Filoo API {status}: {body}")
+
+
+class Filoo:
+    """Filoo API client.
+
+    Args:
+        api_key: A Filoo API key with prefix `flo_live_`. Get one at
+            https://filoo.app/dashboard/api-keys (Pro or Agents tier required).
+        base_url: Override for testing.
+        timeout: HTTPX timeout in seconds (default 30).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://filoo.app",
+        timeout: float = 30.0,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+        self.links = LinksAPI(self._client)
+
+    def me(self) -> dict[str, Any]:
+        return self._get("/api/v1/me")
+
+    def usage(self) -> dict[str, Any]:
+        return self._get("/api/v1/usage")
+
+    def usernames(self) -> dict[str, Any]:
+        return self._get("/api/v1/usernames")
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "Filoo":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def _get(self, path: str) -> dict[str, Any]:
+        r = self._client.get(path)
+        if not r.is_success:
+            raise FilooError(r.status_code, r.text)
+        return r.json()
+
+
+class LinksAPI:
+    def __init__(self, client: httpx.Client):
+        self._c = client
+
+    def create(
+        self,
+        destination: str,
+        *,
+        username: Optional[str] = None,
+        slug: Optional[str] = None,
+        label: Optional[str] = None,
+        show_on_profile: bool = False,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"destination": destination}
+        if username is not None:
+            body["username"] = username
+        if slug is not None:
+            body["slug"] = slug
+        if label is not None:
+            body["label"] = label
+        if show_on_profile:
+            body["show_on_profile"] = True
+        r = self._c.post("/api/v1/links", json=body)
+        if not r.is_success:
+            raise FilooError(r.status_code, r.text)
+        return r.json()
+
+    def list(self, *, limit: int = 20, cursor: Optional[str] = None) -> dict[str, Any]:
+        params: dict[str, Any] = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        r = self._c.get("/api/v1/links", params=params)
+        if not r.is_success:
+            raise FilooError(r.status_code, r.text)
+        return r.json()
+
+    def get(self, code: str) -> dict[str, Any]:
+        r = self._c.get(f"/api/v1/links/{code}")
+        if not r.is_success:
+            raise FilooError(r.status_code, r.text)
+        return r.json()
+
+    def update(self, code: str, **fields: Any) -> dict[str, Any]:
+        r = self._c.patch(f"/api/v1/links/{code}", json=fields)
+        if not r.is_success:
+            raise FilooError(r.status_code, r.text)
+        return r.json()
+
+    def delete(self, code: str) -> dict[str, Any]:
+        r = self._c.delete(f"/api/v1/links/{code}")
+        if not r.is_success:
+            raise FilooError(r.status_code, r.text)
+        return r.json()
+
+    def stats(self, code: str) -> dict[str, Any]:
+        r = self._c.get(f"/api/v1/links/{code}/stats")
+        if not r.is_success:
+            raise FilooError(r.status_code, r.text)
+        return r.json()
+
+
+__all__ = ["Filoo", "FilooError"]

filoo_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "filoo-sdk"
+version = "0.1.0"
+description = "Official Python SDK for the Filoo URL shortener API."
+authors = [{ name = "Filoo" }]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.27"]
+keywords = ["filoo", "url-shortener", "qr-code"]
+
+[project.urls]
+Homepage = "https://filoo.app/api"
+Repository = "https://github.com/jrlprost/filooapp"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["filoo"]