flowflex 0.1.0__py3-none-any.whl

flowflex/__init__.py

@@ -0,0 +1,21 @@
+"""Official FlowFlex SDK for Python.
+
+Fire custom-integration events and attach private files without handling
+presigned URLs yourself.
+"""
+
+from .client import FlowFlex, SendEventResult
+from .errors import FlowFlexConfigError, FlowFlexError, FlowFlexUploadError
+from .file import FileRef, file
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FlowFlex",
+    "SendEventResult",
+    "FileRef",
+    "file",
+    "FlowFlexError",
+    "FlowFlexConfigError",
+    "FlowFlexUploadError",
+]

flowflex/client.py

@@ -0,0 +1,313 @@
+"""FlowFlex client — fire custom-integration events with optional private files."""
+
+import base64
+import re
+import uuid as _uuid
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Callable, Dict, List, Optional, Tuple
+from urllib.parse import quote, urlparse
+
+import requests
+
+from .errors import FlowFlexConfigError, FlowFlexError, FlowFlexUploadError
+from .file import FileRef, FileSource, file as make_file
+
+# 25 MB — mirrors the backend's asset size limit.
+DEFAULT_MAX_FILE_BYTES = 25 * 1024 * 1024
+
+_CONTROL_CHARS = re.compile(r"[\r\n\x00-\x1f\x7f]")
+
+_LOOPBACK_HOSTS = {"localhost", "127.0.0.1", "[::1]", "::1"}
+
+
+def _assert_safe_header_value(label: str, value: str) -> None:
+    """Reject values that would break out of an HTTP header (CRLF / control
+    chars) — prevents header-injection via the event name or idempotency key."""
+    if _CONTROL_CHARS.search(value):
+        raise FlowFlexConfigError(f"{label} contains invalid control characters")
+
+
+class SendEventResult:
+    """Result returned by ``send_event``."""
+
+    def __init__(self, response: Any, uploaded_assets: Dict[str, str]) -> None:
+        #: Raw response body from the events endpoint.
+        self.response = response
+        #: Map of payload paths -> assetId, for every file that was uploaded.
+        self.uploaded_assets = uploaded_assets
+
+    def __repr__(self) -> str:
+        return (
+            f"SendEventResult(response={self.response!r}, "
+            f"uploaded_assets={self.uploaded_assets!r})"
+        )
+
+
+class FlowFlex:
+    """FlowFlex custom-integration client.
+
+    Example::
+
+        from flowflex import FlowFlex
+
+        ff = FlowFlex(
+            api_key="cik_xxx",
+            api_secret="yyy",
+            integration_code="ic_abc123",
+            base_url="https://api.flowflex.ai",
+        )
+        ff.send_event("order.placed", payload={"name": "Ada"})
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        api_secret: str,
+        integration_code: str,
+        base_url: str,
+        timeout_seconds: float = 30.0,
+        max_file_bytes: int = DEFAULT_MAX_FILE_BYTES,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        if not api_key:
+            raise FlowFlexConfigError("api_key is required")
+        if not api_secret:
+            raise FlowFlexConfigError("api_secret is required")
+        if not integration_code:
+            raise FlowFlexConfigError("integration_code is required")
+        if not base_url:
+            raise FlowFlexConfigError("base_url is required")
+
+        # Validate base_url and enforce HTTPS off-loopback so Basic-auth
+        # credentials are never sent in cleartext.
+        stripped = re.sub(r"/api/?$", "", base_url).rstrip("/")
+        parsed = urlparse(stripped)
+        if parsed.scheme not in ("http", "https") or not parsed.hostname:
+            raise FlowFlexConfigError(f'base_url is not a valid URL: "{base_url}"')
+        if parsed.scheme != "https" and parsed.hostname not in _LOOPBACK_HOSTS:
+            raise FlowFlexConfigError(
+                f'base_url must use https (got "{parsed.scheme}://{parsed.hostname}"). '
+                "Basic-auth credentials would otherwise be sent in cleartext. "
+                "Plain http is only allowed for localhost."
+            )
+
+        self._base_url = stripped
+        self._integration_code = integration_code
+        self._timeout = timeout_seconds
+        self._max_file_bytes = max_file_bytes
+        self._session = session or requests.Session()
+        token = base64.b64encode(f"{api_key}:{api_secret}".encode()).decode()
+        self._auth_header = f"Basic {token}"
+
+    # ------------------------------------------------------------------ files
+
+    def file(
+        self,
+        source: FileSource,
+        *,
+        filename: Optional[str] = None,
+        mime: Optional[str] = None,
+        size: Optional[int] = None,
+    ) -> FileRef:
+        """Convenience re-export so callers can do ``ff.file(...)``."""
+        return make_file(source, filename=filename, mime=mime, size=size)
+
+    # ------------------------------------------------------------------- http
+
+    def _request(self, method: str, url: str, **kwargs: Any) -> Any:
+        """HTTP wrapper with timeout + JSON parsing + error normalization."""
+        try:
+            res = self._session.request(method, url, timeout=self._timeout, **kwargs)
+        except requests.Timeout as err:
+            raise FlowFlexError(
+                f"Request to {url} timed out after {self._timeout}s"
+            ) from err
+        except requests.RequestException as err:
+            raise FlowFlexError(f"Network error calling {url}: {err}") from err
+
+        body: Any = res.text
+        if body and "application/json" in (res.headers.get("content-type") or ""):
+            try:
+                body = res.json()
+            except ValueError:
+                pass  # leave as text
+
+        if not res.ok:
+            message = None
+            if isinstance(body, dict):
+                message = body.get("error") or body.get("message")
+            message = message or f"Request to {url} failed with status {res.status_code}"
+            code = body.get("code") or body.get("name") if isinstance(body, dict) else None
+            raise FlowFlexError(
+                str(message), status=res.status_code, code=code, details=body
+            )
+
+        return body
+
+    # ------------------------------------------------------------------ assets
+
+    def create_upload_url(
+        self, *, filename: str, mime: str, size: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """Request a presigned upload URL.
+
+        Most callers don't need this directly — use ``file()`` inside an event
+        payload and let ``send_event`` handle uploads.
+        """
+        payload: Dict[str, Any] = {"filename": filename, "mime": mime}
+        if size is not None:
+            payload["size"] = size
+        return self._request(
+            "POST",
+            f"{self._base_url}/v1/assets/upload-url",
+            headers={"Authorization": self._auth_header},
+            json=payload,
+        )
+
+    def upload_file(self, ref: FileRef) -> str:
+        """Upload one FileRef and return its assetId."""
+        data = ref.read_bytes()
+        # Fail fast on oversized files instead of uploading then being rejected.
+        if len(data) > self._max_file_bytes:
+            raise FlowFlexUploadError(
+                f'"{ref.filename}" is {len(data)} bytes, '
+                f"over the {self._max_file_bytes}-byte limit"
+            )
+
+        info = self.create_upload_url(
+            filename=ref.filename, mime=ref.mime, size=ref.size
+        )
+        asset_id, upload_url = info["assetId"], info["uploadUrl"]
+
+        # PUT the raw bytes straight to storage. No auth header — the presigned
+        # URL carries its own token, and an extra Authorization breaks it.
+        try:
+            res = requests.put(
+                upload_url,
+                data=data,
+                headers={"Content-Type": ref.mime},
+                timeout=self._timeout,
+            )
+        except requests.RequestException as err:
+            raise FlowFlexUploadError(
+                f'Failed to upload "{ref.filename}": {err}'
+            ) from err
+
+        if not res.ok:
+            raise FlowFlexUploadError(
+                f'Storage rejected upload of "{ref.filename}" (status {res.status_code})',
+                status=res.status_code,
+                details=res.text,
+            )
+
+        return asset_id
+
+    # ----------------------------------------------------------------- events
+
+    def _clone_and_collect(
+        self,
+        value: Any,
+        path: str,
+        refs: List[Tuple[Any, Any, FileRef, str]],
+    ) -> Any:
+        """Deep-clone a payload, collecting every FileRef anywhere inside it
+        (nested dicts, lists, mixed) alongside its parent container + key so we
+        can patch the assetId back in after upload."""
+        if isinstance(value, FileRef):
+            return value  # bare FileRef — caller decides
+
+        if isinstance(value, list):
+            out_list: List[Any] = [None] * len(value)
+            for i, v in enumerate(value):
+                p = f"{path}[{i}]"
+                if isinstance(v, FileRef):
+                    refs.append((out_list, i, v, p))
+                else:
+                    out_list[i] = self._clone_and_collect(v, p, refs)
+            return out_list
+
+        if isinstance(value, dict):
+            out: Dict[str, Any] = {}
+            for k, v in value.items():
+                p = f"{path}.{k}" if path else str(k)
+                if isinstance(v, FileRef):
+                    refs.append((out, k, v, p))
+                else:
+                    out[k] = self._clone_and_collect(v, p, refs)
+            return out
+
+        return value
+
+    def _resolve_files(self, payload: Any) -> Tuple[Any, Dict[str, str]]:
+        """Upload every FileRef in a payload and return a deep copy with each
+        replaced by its assetId string, plus a map of path -> assetId.
+
+        Uploads run in parallel; the SAME FileRef instance reused in multiple
+        places is uploaded only once and its assetId reused everywhere.
+        """
+        refs: List[Tuple[Any, Any, FileRef, str]] = []
+        resolved = self._clone_and_collect(payload, "", refs)
+
+        # Dedupe by FileRef identity so reusing one file() uploads once.
+        unique_refs = list({id(r[2]): r[2] for r in refs}.values())
+        id_by_ref: Dict[int, str] = {}
+        if unique_refs:
+            with ThreadPoolExecutor(max_workers=min(8, len(unique_refs))) as pool:
+                for ref, asset_id in zip(
+                    unique_refs, pool.map(self.upload_file, unique_refs)
+                ):
+                    id_by_ref[id(ref)] = asset_id
+
+        uploaded: Dict[str, str] = {}
+        for container, key, ref, path in refs:
+            asset_id = id_by_ref[id(ref)]
+            container[key] = asset_id
+            uploaded[path] = asset_id
+
+        return resolved, uploaded
+
+    def send_event(
+        self,
+        event: str,
+        *,
+        payload: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> SendEventResult:
+        """Fire a custom-integration event into FlowFlex.
+
+        Any ``file()`` in the payload is uploaded first and replaced with its
+        assetId, so a flow's media node can reference it as e.g.
+        ``{{trigger.assetId}}``.
+
+        Example::
+
+            ff.send_event("invoice.created", payload={
+                "assetId": ff.file("./invoice.pdf"),
+                "name": "Ada",
+            })
+        """
+        if not event:
+            raise FlowFlexError("event name is required")
+
+        # These flow into HTTP headers — reject control characters (CRLF) to
+        # prevent header injection.
+        _assert_safe_header_value("event", event)
+        idem_key = idempotency_key or str(_uuid.uuid4())
+        _assert_safe_header_value("idempotency_key", idem_key)
+
+        resolved, uploaded = self._resolve_files(payload or {})
+
+        response = self._request(
+            "POST",
+            # Encode the code so it can't break out of the URL path.
+            f"{self._base_url}/v1/events/{quote(self._integration_code, safe='')}",
+            headers={
+                "Authorization": self._auth_header,
+                "x-event": event,
+                "x-idempotency-key": idem_key,
+            },
+            json=resolved,
+        )
+
+        return SendEventResult(response, uploaded)

flowflex/errors.py

@@ -0,0 +1,34 @@
+"""Error types raised by the FlowFlex SDK."""
+
+from typing import Any, Optional
+
+
+class FlowFlexError(Exception):
+    """Base error for every failure raised by the SDK.
+
+    Carries the HTTP status (when the failure came from an API call) and the
+    machine-readable code returned by the backend (e.g. "MIME_NOT_ALLOWED",
+    "ASSET_FILE_MISSING").
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: Optional[int] = None,
+        code: Optional[str] = None,
+        details: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.details = details
+
+
+class FlowFlexConfigError(FlowFlexError):
+    """Raised when the SDK is constructed with missing/invalid configuration."""
+
+
+class FlowFlexUploadError(FlowFlexError):
+    """Raised when a file attachment cannot be uploaded."""

flowflex/file.py

@@ -0,0 +1,138 @@
+"""Lazy file references for event attachments."""
+
+import io
+import os
+from pathlib import Path
+from typing import BinaryIO, Optional, Union
+
+from .errors import FlowFlexUploadError
+
+FileSource = Union[str, Path, bytes, bytearray, BinaryIO]
+
+# Maps common extensions -> MIME types accepted by the FlowFlex assets API.
+EXT_TO_MIME = {
+    "pdf": "application/pdf",
+    "doc": "application/msword",
+    "docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "xls": "application/vnd.ms-excel",
+    "xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "ppt": "application/vnd.ms-powerpoint",
+    "pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    "txt": "text/plain",
+    "jpg": "image/jpeg",
+    "jpeg": "image/jpeg",
+    "png": "image/png",
+    "mp4": "video/mp4",
+    "3gp": "video/3gpp",
+    "aac": "audio/aac",
+    "amr": "audio/amr",
+    "mp3": "audio/mpeg",
+    "ogg": "audio/ogg",
+}
+
+
+def _infer_mime_from_name(name: str) -> Optional[str]:
+    ext = name.rsplit(".", 1)[-1].lower() if "." in name else None
+    return EXT_TO_MIME.get(ext) if ext else None
+
+
+class FileRef:
+    """A lazy reference to a file the caller wants to attach to an event.
+
+    The bytes are not read until the event is sent. Create one with
+    ``FlowFlex.file()`` or the standalone ``file()`` helper.
+    """
+
+    def __init__(
+        self,
+        source: FileSource,
+        *,
+        filename: Optional[str] = None,
+        mime: Optional[str] = None,
+        size: Optional[int] = None,
+    ) -> None:
+        self.source = source
+        self._filename = filename
+        self._mime = mime
+        self._size = size
+
+    @property
+    def filename(self) -> str:
+        """Resolve the filename, inferring from a path source when possible."""
+        if self._filename:
+            return self._filename
+        if isinstance(self.source, (str, Path)):
+            return os.path.basename(str(self.source))
+        name = getattr(self.source, "name", None)
+        if isinstance(name, str) and name and not name.startswith("<"):
+            return os.path.basename(name)
+        raise FlowFlexUploadError(
+            "Cannot determine filename for attachment — pass filename= to file()"
+        )
+
+    @property
+    def mime(self) -> str:
+        """Resolve the MIME type, inferring from the filename when possible."""
+        if self._mime:
+            return self._mime
+        inferred = _infer_mime_from_name(self.filename)
+        if inferred:
+            return inferred
+        raise FlowFlexUploadError(
+            f'Cannot determine MIME type for "{self.filename}" — pass mime= to file()'
+        )
+
+    @property
+    def size(self) -> Optional[int]:
+        if self._size is not None:
+            return self._size
+        if isinstance(self.source, (bytes, bytearray)):
+            return len(self.source)
+        return None
+
+    def read_bytes(self) -> bytes:
+        """Read the file bytes, ready to PUT to storage."""
+        src = self.source
+        if isinstance(src, (str, Path)):
+            try:
+                with open(src, "rb") as fh:
+                    return fh.read()
+            except OSError as err:
+                raise FlowFlexUploadError(
+                    f'Failed to read "{src}": {err}'
+                ) from err
+        if isinstance(src, (bytes, bytearray)):
+            return bytes(src)
+        if hasattr(src, "read"):
+            data = src.read()
+            if isinstance(data, str):
+                data = data.encode()
+            if hasattr(src, "seek"):
+                try:
+                    src.seek(0)
+                except (OSError, io.UnsupportedOperation):
+                    pass
+            return data
+        raise FlowFlexUploadError("Unsupported file source")
+
+
+def file(
+    source: FileSource,
+    *,
+    filename: Optional[str] = None,
+    mime: Optional[str] = None,
+    size: Optional[int] = None,
+) -> FileRef:
+    """Wrap a file so it can be attached to an event payload.
+
+    The SDK uploads it via a presigned URL when the event is sent and swaps it
+    for its ``assetId``.
+
+    Example::
+
+        ff.send_event("invoice.created", payload={
+            "assetId": file("./invoice.pdf"),
+            "customer_id": "cust_123",
+        })
+    """
+    return FileRef(source, filename=filename, mime=mime, size=size)

flowflex-0.1.0.dist-info/METADATA

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: flowflex
+Version: 0.1.0
+Summary: Official FlowFlex SDK — fire custom-integration events and attach private files without handling presigned URLs yourself.
+Project-URL: Homepage, https://flowflex.ai
+License: UNLICENSED
+Keywords: automation,flowflex,flows,sdk,whatsapp
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Description-Content-Type: text/markdown
+
+# flowflex
+
+Official Python SDK for firing **FlowFlex custom-integration events** and
+attaching **private files** to them — without ever dealing with presigned URLs,
+Basic-auth headers, or the multi-step upload dance yourself.
+
+```bash
+pip install flowflex
+```
+
+Requires Python 3.9+.
+
+---
+
+## Quick start
+
+```python
+from flowflex import FlowFlex
+
+ff = FlowFlex(
+    api_key="cik_xxx",            # from your custom integration
+    api_secret="yyy",
+    integration_code="ic_abc123", # the code in your event URL: /v1/events/<code>
+    base_url="https://api.flowflex.ai",
+)
+
+# Plain event, no file
+ff.send_event("order.placed", payload={"name": "Ada", "order_id": "ord_42"})
+```
+
+In your flow builder, the values land under `trigger` — e.g. `{{trigger.name}}`,
+`{{trigger.order_id}}`.
+
+---
+
+## Attaching a private file
+
+Wrap any file in `ff.file(...)` and drop it into the payload. The SDK uploads it
+through a presigned URL and replaces it with its opaque `assetId` before the
+event is sent. **The file bytes go straight to storage — they never pass through
+the FlowFlex app server.**
+
+```python
+ff.send_event("invoice.created", payload={
+    "assetId": ff.file("./invoice.pdf"),  # ← becomes "asset_..." on the wire
+    "customer_id": "cust_123",
+})
+```
+
+Then in your flow's **Media Message** node:
+
+1. Set **File source** → `Private file (assetId)`
+2. Set the **Asset ID** field → `{{trigger.assetId}}`
+
+The key you use in the payload is the key you reference in the flow. If you send
+`{"invoice": ff.file(...)}`, reference it as `{{trigger.invoice}}`.
+
+### Multiple files
+
+A flow can have as many media nodes as you like — put a `file()` anywhere in the
+payload (top-level, nested, or in lists) and the SDK uploads them **all in
+parallel** and swaps each for its `assetId`. The shape is entirely up to you;
+reference each one by its path in the flow builder.
+
+```python
+ff.send_event("order.shipped", payload={
+    "invoice": ff.file("./invoice.pdf"),                    # {{trigger.invoice}}
+    "label":   ff.file("./label.png"),                      # {{trigger.label}}
+    "gallery": [ff.file("./a.jpg"), ff.file("./b.jpg")],    # {{trigger.gallery[0]}}, {{trigger.gallery[1]}}
+    "order":   {"receipt": ff.file("./receipt.pdf")},       # {{trigger.order.receipt}}
+    "note":    "non-file values pass through untouched",
+})
+# → {"invoice": "asset_a", "label": "asset_b",
+#    "gallery": ["asset_c", "asset_d"],
+#    "order": {"receipt": "asset_e"}, "note": "..."}
+```
+
+`result.uploaded_assets` maps each payload path to its assetId, e.g.
+`{"invoice": "asset_a", "gallery[0]": "asset_c", "order.receipt": "asset_e"}`.
+
+**Reusing one file across nodes:** if you pass the *same* `file()` instance in
+multiple places, it's uploaded only once and the same `assetId` is used
+everywhere:
+
+```python
+banner = ff.file("./banner.png")
+ff.send_event("promo.sent", payload={
+    "header": banner, "footer": banner,  # one upload, same assetId in both
+})
+```
+
+---
+
+## Supplying file bytes other ways
+
+`file()` accepts a path (`str` or `pathlib.Path`), raw `bytes`, or any binary
+file-like object. When the type can't be inferred, pass `filename` and `mime`:
+
+```python
+# Raw bytes
+ff.file(pdf_bytes, filename="invoice.pdf", mime="application/pdf")
+
+# An open file object
+with open("invoice.pdf", "rb") as fh:
+    ff.send_event("invoice.created", payload={"assetId": ff.file(fh)})
+
+# Override the stored filename
+ff.file("./tmp-7f3a.pdf", filename="Invoice-2026.pdf")
+```
+
+**Allowed types:** PDF, DOC(X), XLS(X), PPT(X), TXT, JPEG, PNG, MP4, 3GPP, AAC,
+AMR, MP3, OGG. **Max size:** 25 MB.
+
+---
+
+## API
+
+### `FlowFlex(...)`
+
+| Option             | Type               | Required | Notes                                                                          |
+| ------------------ | ------------------ | -------- | ------------------------------------------------------------------------------ |
+| `api_key`          | str                | yes      | Custom-integration key (`cik_…`).                                              |
+| `api_secret`       | str                | yes      | Custom-integration secret.                                                     |
+| `integration_code` | str                | yes      | The `<code>` in `/v1/events/<code>`.                                           |
+| `base_url`         | str                | yes      | FlowFlex host. Must be `https` (except `localhost`). Trailing `/api` stripped. |
+| `timeout_seconds`  | float              | no       | Per-request timeout. Default `30.0`.                                           |
+| `max_file_bytes`   | int                | no       | Client-side size cap. Default `26214400` (25 MB).                              |
+| `session`          | requests.Session   | no       | Custom session for connection pooling / proxies.                               |
+
+### `ff.send_event(event, payload=None, idempotency_key=None)`
+
+Uploads any `file()` in `payload`, then POSTs the event. Returns a
+`SendEventResult`:
+
+```python
+result.response         # raw body from the events endpoint
+result.uploaded_assets  # dict: payload path → assetId
+```
+
+An `idempotency_key` is auto-generated (UUID) if you don't pass one — safe to
+retry the same call.
+
+### `ff.file(source, filename=None, mime=None, size=None)`
+
+Returns a lazy `FileRef`. Bytes are read only when the event is sent.
+
+### Lower-level helpers
+
+```python
+info = ff.create_upload_url(filename="x.pdf", mime="application/pdf")
+# → {"assetId": ..., "uploadUrl": ..., "token": ...}
+
+asset_id = ff.upload_file(ff.file("./x.pdf"))  # upload, get assetId
+```
+
+---
+
+## Errors
+
+All errors extend `FlowFlexError` (`.message`, `.status`, `.code`, `.details`):
+
+- `FlowFlexConfigError` — bad/missing constructor options.
+- `FlowFlexUploadError` — a file couldn't be read or storage rejected it.
+- `FlowFlexError` — API or network failure (`.code` is the backend error code,
+  e.g. `MIME_NOT_ALLOWED`, `ASSET_FILE_MISSING`).
+
+```python
+from flowflex import FlowFlex, FlowFlexError
+
+try:
+    ff.send_event("invoice.created", payload={"assetId": ff.file("./big.pdf")})
+except FlowFlexError as err:
+    print(err.code, err.status, err.message)
+```
+
+---
+
+## File lifetime & storage cleanup
+
+> **Important — read before using file attachments in production.**
+
+When you call `ff.file(...)`, the file is uploaded to **private storage** that
+only the FlowFlex backend can read. It is **not** a public URL and the caller
+cannot access it after upload.
+
+### How long does the file stay?
+
+| Phase | Duration |
+| ----- | -------- |
+| Presigned upload URL valid | **2 hours** from `create_upload_url` |
+| File kept in storage | **48 hours** from upload |
+| After 48 hours | File **deleted from storage** + record removed |
+
+### What this means for you
+
+- **Do not store `assetId` long-term** expecting to reuse it. It expires in 48h.
+- **Each event send should get a fresh `assetId`** by calling `send_event` with
+  a new `ff.file(...)`. The SDK handles the upload automatically.
+- If you fire the event more than 48h after uploading, the file will be gone and
+  the flow will fail with `ASSET_FILE_MISSING`. Keep your event send close to
+  the upload.
+- **Re-sending the same message** to a different recipient after 48h requires a
+  fresh upload — call `send_event` again with the file, don't reuse the old assetId.
+
+### Typical correct pattern
+
+```python
+# ✅ Upload + fire in the same operation — always fresh
+ff.send_event("invoice.created", payload={"assetId": ff.file("./invoice.pdf")})
+
+# ❌ Don't store assetId and reuse it hours later
+result = ff.send_event(...)
+# ... 50 hours later ...
+# result.uploaded_assets["assetId"] is now expired and deleted
+```
+
+---
+
+## Security
+
+Your `api_key`/`api_secret` are integration-wide credentials — anyone who
+obtains them can fire events and upload files as you. Keep them in environment
+variables or a secrets manager, never in source control.
+
+Protections built in:
+
+- **HTTPS enforced.** `base_url` must be `https://` (only `localhost` may use
+  `http`), so Basic-auth credentials are never sent in cleartext.
+- **No credential leakage.** The `Authorization` header is never included in
+  error messages or `FlowFlexError.details`.
+- **Header-injection safe.** The `event` name and `idempotency_key` are rejected
+  if they contain control characters (CRLF).
+- **Path-injection safe.** `integration_code` is URL-encoded into the request path.
+- **Per-request timeouts** (default 30 s) on every network call.
+- **Client-side size cap** (default 25 MB) so oversized files fail before upload.

flowflex-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+flowflex/__init__.py,sha256=NOB4fnoAS6Zvxvy4HOBTInsLP32AhGyvn_cco-J9Dkk,474
+flowflex/client.py,sha256=6mn8JtXWhSq8IUP-UeX1yAu0f3QDcYM0tt3O_obhuJM,11610
+flowflex/errors.py,sha256=OhOh0ip1gOuC5hRClLN38YjSBss-C9cBjZ-ynt25WgY,921
+flowflex/file.py,sha256=Jb7zFnFgih4F5-sD-WVkWpG0rKyuLsw-nnc3H9JqZBY,4384
+flowflex-0.1.0.dist-info/METADATA,sha256=1lNyRuizyskdXPR24jR4r_H2Vm7zxzVAXltP5Tp98lI,9078
+flowflex-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+flowflex-0.1.0.dist-info/RECORD,,

flowflex-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any