sendflo 0.1.0__tar.gz

sendflo-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+node_modules/
+dist/
+build/
+.next/
+out/
+target/
+target-shell-scratch/
+src-tauri/target/
+.turbo/
+.env
+.env.*
+!.env.example
+*.log
+.DS_Store
+Thumbs.db
+.vs/
+.vscode/
+
+# Vercel
+.vercel
+
+# TypeScript incremental build cache — machine-local, changes on every typecheck.
+*.tsbuildinfo
+
+# Tauri generates these from tauri.conf.json + capabilities on every build.
+apps/desktop/src-tauri/gen/schemas/
+
+# Next static export for the desktop/mobile shells (generated by build:shell).
+apps/web/out/
+.next-shell/
+
+# Capacitor-generated native projects. Regenerate with `pnpm --filter @sendflo/mobile android:setup`
+# (which re-applies scripts/patch-android.mjs). Committing them means merge conflicts in
+# generated Gradle files and a second copy of the plugin sources.
+apps/mobile/android/
+apps/mobile/ios/
+apps/mobile/www/
+
+# Tauri updater signing: the PRIVATE key never enters git (CI holds it as a secret).
+apps/desktop/.tauri-signing/sendflo.key
+
+# Northflank automation (local only — never commit)
+.env.northflank
+infrastructure/northflank/secrets.local.json
+infrastructure/northflank/secrets.jackson.local.json
+go/*.exe
+
+# Python bytecode (packages/sdk-python tests)
+__pycache__/
+*.pyc

sendflo-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 — 2026-10-20
+
+First public release.
+
+- Parity with the TypeScript SDK: notification channels, recipient feedback, agent tasks,
+  `list_webhooks`, `delete_webhook`, `download_inbox_item`, `save_inbox_item`.

sendflo-0.1.0/LICENSE

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

sendflo-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: sendflo
+Version: 0.1.0
+Summary: SendFlo for Python: send files, request files, manage transfers and AI agent tasks. Standard library only.
+Project-URL: Homepage, https://sendflo.app
+Project-URL: Documentation, https://sendflo.app/docs/cli#python
+Author-email: SendFlo LLC <dev@sendflo.app>
+License: MIT
+License-File: LICENSE
+Keywords: ai agents,file sharing,file transfer,sendflo,upload
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: File Sharing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# sendflo
+
+SendFlo for Python: send files and get a link, ask someone for a file, manage your transfers, and
+give files to AI agents. Python 3.9+, **standard library only** — nothing else to install, so it
+drops into locked-down agent containers.
+
+```sh
+pip install sendflo
+```
+
+Create an API key in SendFlo → Settings → Developer (<https://sendflo.app/settings/developer>)
+and set `SENDFLO_API_KEY` (or pass `api_key=`).
+
+## Send a file
+
+```python
+from sendflo import SendFlo
+
+flo = SendFlo()                      # reads SENDFLO_API_KEY
+sent = flo.send_file("report.pdf", password="optional")
+print(sent.url)                      # https://sendflo.app/l/…
+```
+
+The bytes go straight to storage through a presigned multipart upload, each part retried on its
+own.
+
+## Ask someone for a file
+
+```python
+ask = flo.request_file("Upload your Q3 expense CSV")
+print(ask.url)                       # they upload there with no account
+
+items = flo.list_inbox(inbox_id)
+flo.save_inbox_item(items[0].id, "q3.csv")
+```
+
+## Manage what you've sent
+
+`list_links()`, `revoke_link(id)`, and for a whole send: `get_transfer`, `pause_transfer`,
+`resume_transfer`, `revoke_transfer`, `transfer_activity`, `transfer_audit`, `transfer_people`,
+`set_transfer_person_access`. Recipient feedback: `link_feedback`, `link_feedback_comments`,
+`export_link_feedback`.
+
+## Agents
+
+`list_agents()`, `send_to_agent(cloud_agent_id, file_ids, instruction=…)`, `list_agent_tasks()`,
+`get_agent_task(id)`, `answer_agent_task(…)`, `cancel_agent_task`, `retry_agent_task`,
+`wait_for_agent_task(id)`.
+
+## Webhooks and notifications
+
+`create_webhook(url, events)`, `list_webhooks()`, `delete_webhook(id)`, and
+`verify_webhook_signature(secret, header, body)` for inbound deliveries (constant-time, with a
+5-minute replay window). Notification channels: `list_notification_channels`,
+`add_notification_channel`, `update_notification_channel`, `remove_notification_channel`,
+`test_notification_channel`.
+
+## Errors
+
+Every non-2xx response raises `SendFloError` with `status`, a stable `code`, and `retryable` /
+`out_of_credits`. Reads are retried with backoff; `402` (out of credits) never is.
+
+## Licence
+
+MIT © SendFlo LLC. Questions: support@sendflo.app.

sendflo-0.1.0/README.md

@@ -0,0 +1,65 @@
+# sendflo
+
+SendFlo for Python: send files and get a link, ask someone for a file, manage your transfers, and
+give files to AI agents. Python 3.9+, **standard library only** — nothing else to install, so it
+drops into locked-down agent containers.
+
+```sh
+pip install sendflo
+```
+
+Create an API key in SendFlo → Settings → Developer (<https://sendflo.app/settings/developer>)
+and set `SENDFLO_API_KEY` (or pass `api_key=`).
+
+## Send a file
+
+```python
+from sendflo import SendFlo
+
+flo = SendFlo()                      # reads SENDFLO_API_KEY
+sent = flo.send_file("report.pdf", password="optional")
+print(sent.url)                      # https://sendflo.app/l/…
+```
+
+The bytes go straight to storage through a presigned multipart upload, each part retried on its
+own.
+
+## Ask someone for a file
+
+```python
+ask = flo.request_file("Upload your Q3 expense CSV")
+print(ask.url)                       # they upload there with no account
+
+items = flo.list_inbox(inbox_id)
+flo.save_inbox_item(items[0].id, "q3.csv")
+```
+
+## Manage what you've sent
+
+`list_links()`, `revoke_link(id)`, and for a whole send: `get_transfer`, `pause_transfer`,
+`resume_transfer`, `revoke_transfer`, `transfer_activity`, `transfer_audit`, `transfer_people`,
+`set_transfer_person_access`. Recipient feedback: `link_feedback`, `link_feedback_comments`,
+`export_link_feedback`.
+
+## Agents
+
+`list_agents()`, `send_to_agent(cloud_agent_id, file_ids, instruction=…)`, `list_agent_tasks()`,
+`get_agent_task(id)`, `answer_agent_task(…)`, `cancel_agent_task`, `retry_agent_task`,
+`wait_for_agent_task(id)`.
+
+## Webhooks and notifications
+
+`create_webhook(url, events)`, `list_webhooks()`, `delete_webhook(id)`, and
+`verify_webhook_signature(secret, header, body)` for inbound deliveries (constant-time, with a
+5-minute replay window). Notification channels: `list_notification_channels`,
+`add_notification_channel`, `update_notification_channel`, `remove_notification_channel`,
+`test_notification_channel`.
+
+## Errors
+
+Every non-2xx response raises `SendFloError` with `status`, a stable `code`, and `retryable` /
+`out_of_credits`. Reads are retried with backoff; `402` (out of credits) never is.
+
+## Licence
+
+MIT © SendFlo LLC. Questions: support@sendflo.app.

sendflo-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "sendflo"
+version = "0.1.0"
+description = "SendFlo for Python: send files, request files, manage transfers and AI agent tasks. Standard library only."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "SendFlo LLC", email = "dev@sendflo.app" }]
+keywords = ["sendflo", "file transfer", "file sharing", "upload", "ai agents"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Communications :: File Sharing",
+]
+# Deliberately empty. Agent runtimes are often locked-down containers where adding a
+# dependency is a conversation with someone's security team; stdlib-only makes this a drop-in.
+dependencies = []
+
+[project.urls]
+Homepage = "https://sendflo.app"
+Documentation = "https://sendflo.app/docs/cli#python"
+
+[build-system]
+requires = ["hatchling==1.27.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sendflo"]
+
+[tool.hatch.build.targets.sdist]
+include = ["sendflo", "tests", "README.md", "LICENSE", "CHANGELOG.md"]

sendflo-0.1.0/sendflo/__init__.py

@@ -0,0 +1,500 @@
+"""
+SendFlo Python SDK (PLAN 3.6).
+
+Handwritten for the same reason as the TypeScript one: the call people want — ``send_file`` —
+spans three endpoints plus a presigned multipart upload with per-part retries, and a generated
+client would hand all of that back to the caller.
+
+Standard library only. Agent runtimes are frequently locked-down containers where adding
+``requests`` is a conversation with someone's security team, and this needs to be a drop-in.
+
+    from sendflo import SendFlo
+
+    flo = SendFlo(api_key=os.environ["SENDFLO_API_KEY"])
+    link = flo.send_file("report.pdf")
+    ask  = flo.request_file("Upload your Q3 expense CSV")
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Any, BinaryIO, Callable, Iterable
+
+__all__ = [
+    "SendFlo",
+    "SendFloError",
+    "SendResult",
+    "FileRequest",
+    "InboxItem",
+    "verify_webhook_signature",
+]
+
+DEFAULT_BASE_URL = "https://api.sendflo.app"
+__version__ = "0.1.0"
+_FINAL_TASK_STATES = frozenset({"completed", "failed", "canceled", "rejected", "expired"})
+
+
+class SendFloError(Exception):
+    """Every non-2xx response. Callers branch on ``code``, never on the message text."""
+
+    def __init__(self, status: int, code: str, message: str, detail: str | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.detail = detail
+
+    @property
+    def retryable(self) -> bool:
+        """True when retrying the same call could plausibly succeed."""
+        return self.status == 429 or self.status >= 500
+
+    @property
+    def out_of_credits(self) -> bool:
+        """The one error an agent must handle explicitly: the operation did NOT happen."""
+        return self.status == 402
+
+
+@dataclass
+class SendResult:
+    file_id: str
+    link_id: str
+    slug: str
+    url: str
+
+
+@dataclass
+class FileRequest:
+    id: str
+    slug: str
+    url: str
+    state: str
+    prompt: str | None = None
+    expires_at: str | None = None
+
+
+@dataclass
+class InboxItem:
+    id: str
+    file_id: str
+    name: str
+    size: int
+    content_type: str | None
+    scan_state: str
+    sender: str | None
+    received_at: str
+
+
+def _backoff(attempt: int) -> float:
+    """Exponential with full jitter — a fleet of agents retrying in lockstep is a self-inflicted
+    thundering herd."""
+    return random.random() * min(30.0, 0.5 * (2**attempt))
+
+
+class SendFlo:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        max_retries: int = 3,
+        timeout: float = 30.0,
+    ) -> None:
+        key = api_key or os.environ.get("SENDFLO_API_KEY")
+        if not key:
+            raise ValueError("SendFlo: api_key is required (or set SENDFLO_API_KEY)")
+        self.api_key = key
+        self.base_url = (base_url or os.environ.get("SENDFLO_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.max_retries = max_retries
+        self.timeout = timeout
+
+    # ── core request ──────────────────────────────────────────────────────────
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        headers = {"authorization": f"Bearer {self.api_key}", "accept": "application/json"}
+        data = None
+        if body is not None:
+            # Drop None values so optional params are genuinely absent rather than explicit null.
+            payload = {k: v for k, v in body.items() if v is not None}
+            data = json.dumps(payload).encode()
+            headers["content-type"] = "application/json"
+        if idempotency_key:
+            headers["idempotency-key"] = idempotency_key
+
+        last_error: Exception | None = None
+        for attempt in range(self.max_retries + 1):
+            req = urllib.request.Request(f"{self.base_url}{path}", data=data, headers=headers, method=method)
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                    raw = res.read()
+                    return json.loads(raw) if raw else None
+            except urllib.error.HTTPError as e:
+                problem: dict[str, Any] = {}
+                try:
+                    problem = json.loads(e.read())
+                except Exception:
+                    pass
+                error = SendFloError(
+                    e.code,
+                    problem.get("code", f"http_{e.code}"),
+                    problem.get("title", e.reason or "request failed"),
+                    problem.get("detail"),
+                )
+                # 402 is terminal — retrying an out-of-credits call only burns rate limit.
+                if not error.retryable or attempt == self.max_retries:
+                    raise error from None
+                retry_after = e.headers.get("retry-after") if e.headers else None
+                time.sleep(float(retry_after) if retry_after and retry_after.isdigit() else _backoff(attempt))
+                last_error = error
+            except urllib.error.URLError as e:
+                # Without an idempotency key we cannot know whether a non-GET was processed,
+                # so retrying it risks a duplicate. GETs are always safe.
+                if method != "GET" and not idempotency_key:
+                    raise
+                if attempt == self.max_retries:
+                    raise
+                last_error = e
+                time.sleep(_backoff(attempt))
+        raise last_error or RuntimeError("SendFlo: request failed")
+
+    # ── sending ───────────────────────────────────────────────────────────────
+
+    def send_file(
+        self,
+        file: str | BinaryIO,
+        name: str | None = None,
+        expires_in_days: int = 7,
+        password: str | None = None,
+        max_downloads: int | None = None,
+        note: str | None = None,
+        on_progress: Callable[[int, int], None] | None = None,
+    ) -> SendResult:
+        """Upload and return a shareable link.
+
+        Bytes go straight to object storage via presigned multipart — they never pass through
+        the API, which is why a 40 GB send doesn't depend on how much memory the API has.
+        """
+        if isinstance(file, str):
+            path = file
+            size = os.path.getsize(path)
+            name = name or os.path.basename(path)
+            handle: BinaryIO = open(path, "rb")
+            close_after = True
+        else:
+            handle, close_after = file, False
+            handle.seek(0, os.SEEK_END)
+            size = handle.tell()
+            handle.seek(0)
+            name = name or getattr(handle, "name", "file")
+            name = os.path.basename(str(name))
+
+        if size == 0:
+            if close_after:
+                handle.close()
+            raise ValueError("SendFlo: cannot send a zero-byte file")
+
+        expires_at = (datetime.now(timezone.utc) + timedelta(days=expires_in_days)).isoformat()
+
+        try:
+            created = self._request("POST", "/v1/transfers", {"name": name, "size": size, "expires_at": expires_at})
+            upload = created["upload"]
+            part_size = upload["part_size"]
+            part_urls: list[str] = upload["part_urls"]
+
+            parts = []
+            sent = 0
+            for index, url in enumerate(part_urls):
+                chunk = handle.read(part_size)
+                etag = self._put_part(url, chunk)
+                parts.append({"part_number": index + 1, "etag": etag})
+                sent += len(chunk)
+                if on_progress:
+                    on_progress(sent, size)
+
+            completed = self._request("POST", f"/v1/transfers/{created['id']}/complete", {"parts": parts})
+            link = self._request(
+                "POST",
+                "/v1/links",
+                {
+                    "file_id": completed["file_id"],
+                    "password": password,
+                    "expires_at": expires_at,
+                    "max_downloads": max_downloads,
+                    "note": note,
+                },
+            )
+            return SendResult(completed["file_id"], link["id"], link["slug"], link["url"])
+        finally:
+            if close_after:
+                handle.close()
+
+    def _put_part(self, url: str, chunk: bytes) -> str:
+        """A part is idempotent by definition — the same part number overwrites — so retrying
+        one is always safe, and far cheaper than restarting the upload."""
+        last: Exception | None = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                req = urllib.request.Request(url, data=chunk, method="PUT")
+                with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                    etag = res.headers.get("etag")
+                    if not etag:
+                        # Failing here names the cause; the alternative is a confusing error at
+                        # multipart completion, far from the actual misconfiguration.
+                        raise SendFloError(
+                            0,
+                            "etag_missing",
+                            "Storage did not return an ETag",
+                            "The bucket's CORS policy must include ETag in ExposeHeaders.",
+                        )
+                    return etag.strip('"')
+            except SendFloError:
+                raise
+            except Exception as e:
+                last = e
+                if attempt == self.max_retries:
+                    raise
+                time.sleep(_backoff(attempt))
+        raise last or RuntimeError("part upload failed")
+
+    # ── agent surfaces ────────────────────────────────────────────────────────
+
+    def request_file(
+        self,
+        prompt: str,
+        max_files: int = 1,
+        max_bytes_per_file: int | None = None,
+        deliver_to_inbox_id: str | None = None,
+        expires_in_days: int = 7,
+        idempotency_key: str | None = None,
+    ) -> FileRequest:
+        """Ask a HUMAN for a file. Returns a URL they can upload to with no account."""
+        res = self._request(
+            "POST",
+            "/v1/file-requests",
+            {
+                "prompt": prompt,
+                "max_files": max_files,
+                "max_bytes_per_file": max_bytes_per_file,
+                "deliver_to_inbox_id": deliver_to_inbox_id,
+                "expires_at": (datetime.now(timezone.utc) + timedelta(days=expires_in_days)).isoformat(),
+            },
+            idempotency_key=idempotency_key,
+        )
+        return FileRequest(res["id"], res["slug"], res["url"], res["state"], res.get("prompt"), res.get("expires_at"))
+
+    def get_file_request(self, request_id: str) -> FileRequest:
+        res = self._request("GET", f"/v1/file-requests/{request_id}")
+        return FileRequest(res["id"], res["slug"], res["url"], res["state"], res.get("prompt"), res.get("expires_at"))
+
+    def create_inbox(self, name: str | None = None, ttl_days: int = 7) -> dict[str, Any]:
+        return self._request("POST", "/v1/inboxes", {"name": name, "default_ttl_seconds": ttl_days * 86400})
+
+    def list_inbox(self, inbox_id: str) -> list[InboxItem]:
+        res = self._request("GET", f"/v1/inboxes/{inbox_id}/items")
+        return [
+            InboxItem(
+                i["id"],
+                i["file"]["id"],
+                i["file"]["name"],
+                int(i["file"]["size"]),
+                i["file"].get("content_type"),
+                i["file"]["scan_state"],
+                i.get("from"),
+                i["received_at"],
+            )
+            for i in res["data"]
+        ]
+
+    def list_links(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/v1/links")["data"]
+
+    def list_links_page(self, cursor: str | None = None, limit: int | None = None) -> dict[str, Any]:
+        """One page of your links, newest first (revoked ones included); pass next_cursor back."""
+        q = urllib.parse.urlencode({k: v for k, v in {"cursor": cursor, "limit": limit}.items() if v is not None})
+        return self._request("GET", f"/v1/links{'?' + q if q else ''}")
+
+    def revoke_link(self, link_id: str) -> None:
+        """Revokes ONE link (one file) and frees its storage. revoke_transfer ends a whole send."""
+        self._request("DELETE", f"/v1/links/{link_id}")
+
+    # Whole transfers (Wave 1 S6) — link_id is any link of the send.
+
+    def get_transfer(self, link_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/v1/links/{link_id}/transfer")
+
+    def pause_transfer(self, link_id: str) -> dict[str, Any]:
+        """Reversible: every file refuses with "Paused by the sender"; the files keep their storage."""
+        return self._request("PUT", f"/v1/links/{link_id}/transfer/pause")
+
+    def resume_transfer(self, link_id: str) -> dict[str, Any]:
+        """Lifts your own pause (never a safety review's)."""
+        return self._request("DELETE", f"/v1/links/{link_id}/transfer/pause")
+
+    def revoke_transfer(self, link_id: str) -> dict[str, Any]:
+        """Ends every file of the send for good and frees the storage. Can't be undone."""
+        return self._request("POST", f"/v1/links/{link_id}/transfer/revoke")
+
+    def transfer_activity(self, link_id: str, cursor: "str | None" = None, limit: "int | None" = None) -> dict[str, Any]:
+        """Who opened what, when and from where across the whole send (Wave 1 T1).
+        `people` comes on the first page; pass the previous `next_cursor` as `cursor` for older events."""
+        params = {k: v for k, v in (("cursor", cursor), ("limit", limit)) if v is not None}
+        qs = "&".join(f"{k}={v}" for k, v in params.items())
+        return self._request("GET", f"/v1/links/{link_id}/transfer/activity" + (f"?{qs}" if qs else ""))
+
+    def transfer_audit(self, link_id: str) -> dict[str, Any]:
+        """Everything that happened to the send, for an auditor or a client (Wave 1 T2), as JSON.
+        The CSV form is GET /v1/links/{id}/transfer/audit?format=csv."""
+        return self._request("GET", f"/v1/links/{link_id}/transfer/audit?format=json")
+
+    def transfer_people(self, link_id: str) -> dict[str, Any]:
+        """Everyone who can open the send and which files each can open (Wave 1 R6)."""
+        return self._request("GET", f"/v1/links/{link_id}/transfer/people")
+
+    def set_transfer_person_access(self, link_id: str, email: str, files: "str | list[str]") -> dict[str, Any]:
+        """Exactly which files `email` may open: "all", or link ids (every other file is removed; [] = the whole send).
+        Only restores addresses you removed; it never adds anyone. A Public send answers 409 `public_link`."""
+        return self._request("POST", f"/v1/links/{link_id}/transfer/people/access", {"email": email, "files": files})
+
+    def create_webhook(self, url: str, events: Iterable[str]) -> dict[str, Any]:
+        return self._request("POST", "/v1/webhooks", {"url": url, "events": list(events)})
+
+    def list_webhooks(self) -> list[dict[str, Any]]:
+        """The workspace's webhook endpoints (never their secrets), including any switched off after failures."""
+        return self._request("GET", "/v1/webhooks")["data"]
+
+    def delete_webhook(self, webhook_id: str) -> None:
+        self._request("DELETE", f"/v1/webhooks/{urllib.parse.quote(webhook_id, safe='')}")
+
+    # Received files (inboxes and upload pages).
+
+    def download_inbox_item(self, item_id: str) -> dict[str, Any]:
+        """A short-lived URL for a received file (scanned, not blocked): ``{"url", "name", "size"}``."""
+        res = self._request("POST", f"/v1/inbox-items/{urllib.parse.quote(item_id, safe='')}/download")
+        return {"url": res["url"], "name": res["name"], "size": int(res["size"])}
+
+    def save_inbox_item(self, item_id: str, path: str | None = None) -> str:
+        """Download a received file to ``path`` (default: its own name in the current directory)."""
+        d = self.download_inbox_item(item_id)
+        target = path or os.path.basename(d["name"]) or "file"
+        with urllib.request.urlopen(d["url"], timeout=self.timeout) as res, open(target, "wb") as out:
+            while True:
+                chunk = res.read(1 << 20)
+                if not chunk:
+                    break
+                out.write(chunk)
+        return target
+
+    # Recipient feedback (comments, ratings, approvals) on a send.
+
+    def link_feedback(self, link_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/v1/links/{link_id}/feedback")
+
+    def link_feedback_comments(self, link_id: str, file: str) -> list[dict[str, Any]]:
+        q = urllib.parse.urlencode({"file": file})
+        return self._request("GET", f"/v1/links/{link_id}/feedback/comments?{q}")["comments"]
+
+    def export_link_feedback(self, link_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/v1/links/{link_id}/feedback/export?format=json")
+
+    # Notification channels (email, Slack, webhook, Discord, Teams).
+
+    def list_notification_channels(self) -> dict[str, Any]:
+        return self._request("GET", "/v1/notification-channels")
+
+    def add_notification_channel(self, channel: str, name: str, target: str) -> dict[str, Any]:
+        return self._request("POST", "/v1/notification-channels", {"channel": channel, "name": name, "target": target})
+
+    def update_notification_channel(self, channel_id: str, name: str | None = None, target: str | None = None, active: bool | None = None) -> dict[str, Any]:
+        patch = {k: v for k, v in (("name", name), ("target", target), ("active", active)) if v is not None}
+        return self._request("PATCH", f"/v1/notification-channels/{channel_id}", patch)
+
+    def remove_notification_channel(self, channel_id: str) -> None:
+        self._request("DELETE", f"/v1/notification-channels/{channel_id}")
+
+    def test_notification_channel(self, channel_id: str) -> dict[str, Any]:
+        return self._request("POST", f"/v1/notification-channels/{channel_id}/test")
+
+    # Agent tasks: give files to an AI agent (a cloud agent or one on your computer) and follow it.
+
+    def list_agents(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/v1/agent-targets")["targets"]
+
+    def send_to_agent(self, cloud_agent_id: str, file_ids: Iterable[str], instruction: str | None = None, preset: str | None = None, from_name: str | None = None) -> dict[str, Any]:
+        body = {"cloud_agent_id": cloud_agent_id, "file_ids": list(file_ids), "instruction": instruction, "preset": preset, "from_name": from_name}
+        return self._request("POST", "/v1/agent-tasks", {k: v for k, v in body.items() if v is not None})["task"]
+
+    def list_agent_tasks(self, box: str | None = None, agent: str | None = None, state: str | None = None, limit: int | None = None) -> list[dict[str, Any]]:
+        q = urllib.parse.urlencode({k: v for k, v in (("box", box), ("agent", agent), ("state", state), ("limit", limit)) if v is not None})
+        return self._request("GET", f"/v1/agent-tasks{'?' + q if q else ''}")["tasks"]
+
+    def get_agent_task(self, task_id: str) -> dict[str, Any]:
+        """``{"task": …, "events": […]}``."""
+        return self._request("GET", f"/v1/agent-tasks/{task_id}")
+
+    def answer_agent_task(self, task_id: str, question_id: str, option_id: str | None = None, text: str | None = None) -> dict[str, Any]:
+        return self._request("POST", f"/v1/agent-tasks/{task_id}/answer", {"question_id": question_id, "option_id": option_id, "text": text})["task"]
+
+    def cancel_agent_task(self, task_id: str) -> dict[str, Any]:
+        return self._request("POST", f"/v1/agent-tasks/{task_id}/cancel", {})["task"]
+
+    def retry_agent_task(self, task_id: str) -> dict[str, Any]:
+        return self._request("POST", f"/v1/agent-tasks/{task_id}/retry", {})["task"]
+
+    def wait_for_agent_task(self, task_id: str, timeout: float = 600.0, interval: float = 3.0, until_question: bool = False) -> dict[str, Any]:
+        """Poll until the task finishes (or asks a question, with ``until_question``) or ``timeout`` passes."""
+        end = time.monotonic() + timeout
+        while True:
+            task = self.get_agent_task(task_id)["task"]
+            if task["state"] in _FINAL_TASK_STATES or (until_question and task["state"] == "input_required"):
+                return task
+            if time.monotonic() >= end:
+                return task
+            time.sleep(interval)
+
+    def credits(self) -> dict[str, Any]:
+        """Balance and price list, so an agent can budget BEFORE it spends."""
+        res = self._request("GET", "/v1/credits")
+        return {"balance": int(res["balance"]), "prices": {k: int(v) for k, v in res["prices"].items()}}
+
+    def usage(self) -> dict[str, Any]:
+        return self._request("GET", "/v1/usage")
+
+
+def verify_webhook_signature(
+    secret: str,
+    signature_header: str,
+    body: str | bytes,
+    tolerance_seconds: int = 300,
+) -> bool:
+    """Verify an inbound webhook.
+
+    Ships in the SDK so nobody hand-rolls the comparison: the obvious ``==`` on a hex digest is
+    timing-attackable, and a signature that omits the timestamp is replayable forever.
+    """
+    try:
+        parts = dict(p.split("=", 1) for p in signature_header.split(","))
+        timestamp = int(parts["t"])
+        provided = parts["v1"]
+    except (ValueError, KeyError):
+        return False
+
+    if abs(int(time.time()) - timestamp) > tolerance_seconds:
+        return False
+
+    payload = body if isinstance(body, bytes) else body.encode()
+    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + payload, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, provided)

sendflo-0.1.0/tests/test_sdk.py

@@ -0,0 +1,186 @@
+"""SendFlo Python SDK tests — stdlib only, against an in-process fake of the API and storage.
+
+    python -m unittest discover -s tests      (from packages/sdk-python)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import sys
+import tempfile
+import threading
+import time
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from sendflo import SendFlo, SendFloError, verify_webhook_signature  # noqa: E402
+
+
+class FakeApi:
+    """Records every request; answers the routes the SDK calls like the real API does."""
+
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, str, dict | None, dict]] = []
+        self.parts: dict[int, bytes] = {}
+        self.fail_next: dict[str, int] = {}
+        handler = self._handler()
+        self.server = ThreadingHTTPServer(("127.0.0.1", 0), handler)
+        self.base = f"http://127.0.0.1:{self.server.server_address[1]}"
+        threading.Thread(target=self.server.serve_forever, daemon=True).start()
+
+    def close(self) -> None:
+        self.server.shutdown()
+
+    def _handler(self):
+        api = self
+
+        class H(BaseHTTPRequestHandler):
+            def log_message(self, *a):  # quiet
+                pass
+
+            def _send(self, status: int, body: object | None = None, headers: dict | None = None) -> None:
+                data = b"" if body is None else json.dumps(body).encode()
+                self.send_response(status)
+                for k, v in (headers or {}).items():
+                    self.send_header(k, v)
+                if body is not None:
+                    self.send_header("content-type", "application/json")
+                self.send_header("content-length", str(len(data)))
+                self.end_headers()
+                self.wfile.write(data)
+
+            def _route(self, method: str) -> None:
+                length = int(self.headers.get("content-length") or 0)
+                raw = self.rfile.read(length) if length else b""
+                path = self.path
+                if path.startswith("/storage/part/"):
+                    n = int(path.rsplit("/", 1)[1])
+                    api.parts[n] = raw
+                    return self._send(200, None, {"etag": f'"etag-{n}"'})
+                if path == "/storage/file":
+                    # A presigned download: no API key is (or should be) sent here.
+                    api.calls.append((method, path, None, dict(self.headers)))
+                    self.send_response(200)
+                    self.send_header("content-length", "5")
+                    self.end_headers()
+                    self.wfile.write(b"a,b,c")
+                    return
+                body = json.loads(raw) if raw else None
+                api.calls.append((method, path, body, dict(self.headers)))
+                key = f"{method} {path}"
+                if api.fail_next.get(key):
+                    api.fail_next[key] -= 1
+                    return self._send(503, {"type": "x", "title": "busy", "status": 503, "code": "unavailable"})
+                if self.headers.get("authorization") != "Bearer sk_test_unit":
+                    return self._send(401, {"type": "x", "title": "Bearer token required", "status": 401, "code": "unauthenticated"})
+                if key == "POST /v1/transfers":
+                    size = body["size"]
+                    n = (size + 4 - 1) // 4
+                    return self._send(200, {"id": "t1", "upload": {"upload_id": "u", "part_size": 4, "part_urls": [f"{api.base}/storage/part/{i + 1}" for i in range(n)]}})
+                if key == "POST /v1/transfers/t1/complete":
+                    return self._send(200, {"file_id": "f1"})
+                if key == "POST /v1/links":
+                    return self._send(200, {"id": "l1", "slug": "abc", "url": "https://sendflo.app/l/abc"})
+                if key == "GET /v1/webhooks":
+                    return self._send(200, {"data": [{"id": "w1", "url": "https://x.test/h", "events": ["file.flagged"], "disabled": False}]})
+                if key == "DELETE /v1/webhooks/w1":
+                    return self._send(204)
+                if key == "POST /v1/inbox-items/i1/download":
+                    return self._send(200, {"url": f"{api.base}/storage/file", "name": "q3.csv", "size": "5", "ticket": "t"})
+                if key.startswith("GET /v1/agent-tasks/k1"):
+                    return self._send(200, {"task": {"id": "k1", "state": "completed"}, "events": []})
+                if key == "GET /v1/credits":
+                    return self._send(402, {"type": "x", "title": "Out of credits", "status": 402, "code": "insufficient_credits"})
+                return self._send(404, {"type": "x", "title": "not found", "status": 404, "code": "not_found"})
+
+            def do_GET(self):
+                self._route("GET")
+
+            def do_POST(self):
+                self._route("POST")
+
+            def do_PUT(self):
+                self._route("PUT")
+
+            def do_DELETE(self):
+                self._route("DELETE")
+
+        return H
+
+
+class SdkTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.api = FakeApi()
+        self.flo = SendFlo(api_key="sk_test_unit", base_url=self.api.base, max_retries=2, timeout=5)
+
+    def tearDown(self) -> None:
+        self.api.close()
+
+    def test_send_file_uploads_every_part_then_links(self) -> None:
+        with tempfile.NamedTemporaryFile("wb", delete=False, suffix=".txt") as f:
+            f.write(b"hello world!")
+        try:
+            r = self.flo.send_file(f.name)
+        finally:
+            os.unlink(f.name)
+        self.assertEqual(r.url, "https://sendflo.app/l/abc")
+        self.assertEqual(b"".join(self.api.parts[i] for i in sorted(self.api.parts)), b"hello world!")
+        complete = next(c for c in self.api.calls if c[1] == "/v1/transfers/t1/complete")
+        self.assertEqual([p["etag"] for p in complete[2]["parts"]], ["etag-1", "etag-2", "etag-3"])
+
+    def test_errors_carry_the_code_and_402_is_not_retried(self) -> None:
+        with self.assertRaises(SendFloError) as e:
+            self.flo.credits()
+        self.assertEqual(e.exception.code, "insufficient_credits")
+        self.assertTrue(e.exception.out_of_credits)
+        self.assertEqual(sum(1 for c in self.api.calls if c[1] == "/v1/credits"), 1)
+
+    def test_a_503_on_a_read_is_retried(self) -> None:
+        self.api.fail_next["GET /v1/webhooks"] = 1
+        hooks = self.flo.list_webhooks()
+        self.assertEqual(hooks[0]["id"], "w1")
+        self.assertEqual(sum(1 for c in self.api.calls if c[1] == "/v1/webhooks"), 2)
+
+    def test_delete_webhook_and_inbox_download(self) -> None:
+        self.flo.delete_webhook("w1")
+        self.assertIn(("DELETE", "/v1/webhooks/w1"), [(c[0], c[1]) for c in self.api.calls])
+        d = self.flo.download_inbox_item("i1")
+        self.assertEqual(d["size"], 5)
+        with tempfile.TemporaryDirectory() as tmp:
+            out = self.flo.save_inbox_item("i1", os.path.join(tmp, "q3.csv"))
+            with open(out, "rb") as fh:
+                self.assertEqual(fh.read(), b"a,b,c")
+        storage = [c for c in self.api.calls if c[1] == "/storage/file"]
+        self.assertTrue(storage and all("authorization" not in {k.lower() for k in c[3]} for c in storage), "the API key must never go to storage")
+
+    def test_wait_for_agent_task_returns_a_final_state(self) -> None:
+        task = self.flo.wait_for_agent_task("k1", timeout=5, interval=0.01)
+        self.assertEqual(task["state"], "completed")
+
+    def test_api_key_is_required(self) -> None:
+        old = os.environ.pop("SENDFLO_API_KEY", None)
+        try:
+            with self.assertRaises(ValueError):
+                SendFlo()
+        finally:
+            if old is not None:
+                os.environ["SENDFLO_API_KEY"] = old
+
+
+class WebhookSignatureTest(unittest.TestCase):
+    def test_valid_old_and_tampered(self) -> None:
+        secret, body, t = "whsec_x", '{"a":1}', int(time.time())
+        sig = hmac.new(secret.encode(), f"{t}.{body}".encode(), hashlib.sha256).hexdigest()
+        self.assertTrue(verify_webhook_signature(secret, f"t={t},v1={sig}", body))
+        self.assertFalse(verify_webhook_signature(secret, f"t={t - 3600},v1={sig}", body))
+        self.assertFalse(verify_webhook_signature(secret, f"t={t},v1={sig[:-1]}0", body))
+        self.assertFalse(verify_webhook_signature(secret, "garbage", body))
+
+
+if __name__ == "__main__":
+    unittest.main()