getfluxly 0.1.0__tar.gz

getfluxly-0.1.0/.gitignore

@@ -0,0 +1,93 @@
+.env
+.idea
+
+# --------------------
+# Django / Python
+# --------------------
+*.pyc
+__pycache__/
+*.pyo
+*.pyd
+
+# Django local DB
+db.sqlite3
+db.sqlite3-journal
+
+# Django secrets / env
+.env
+.env.*
+*.env
+
+# Logs
+*.log
+
+# --------------------
+# Virtualenvs
+# --------------------
+venv/
+.venv/
+
+# --------------------
+# IDE
+# --------------------
+.idea/
+.vscode/
+
+# --------------------
+# OS
+# --------------------
+.DS_Store
+
+# --- Node ---
+node_modules/
+**/node_modules/
+npm-debug.log*
+yarn-debug.log*
+pnpm-debug.log*
+
+# --- Python ---
+__pycache__/
+*.py[cod]
+.env
+.venv
+venv/
+
+# --- Go ---
+bin/
+*.exe
+*.out
+/apps/workers/worker-*
+
+# --- OS / IDE ---
+.DS_Store
+.idea/
+.vscode/
+
+# --- Pytest / coverage ---
+.pytest_cache/
+
+# --- SDK build output ---
+/packages/browser/dist/
+/packages/browser/dist-test/
+/packages/next/dist/
+/packages/node/dist/
+/packages/react/dist/
+/packages/sdk-js/dist/
+/packages/sdk-js/dist-test/
+.gh-tmp
+
+# --- Local planning notes (untracked, personal) ---
+/BETA_COMMUNITIES.md
+/LAUNCH_PLAN_MAY18.md
+/LINKEDIN_PAGE_SETUP.md
+/SEO_AND_LAUNCH_DISTRIBUTION_PLAN.md
+/Design Inspirations/
+
+# --- Claude Code local config ---
+.claude/
+/packages/python/dist/
+/packages/python/.venv/
+/packages/python/*.egg-info/
+/packages/ruby/*.gem
+/packages/ruby/.bundle/
+/packages/ruby/Gemfile.lock

getfluxly-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to `getfluxly` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-16
+
+### Added
+- Initial release of `getfluxly` Python SDK.
+- Synchronous `Client` and asynchronous `AsyncClient` against the
+  public REST API (`/v1/events/batch`, `/v1/identify/alias`).
+- Batched event queue with configurable `flush_at`, `flush_interval`,
+  `max_queue_size`.
+- Retry posture matching the Node SDK: 408 / 425 / 429 / 5xx with
+  exponential backoff and +/- 25% jitter, `Retry-After` honored.
+- `X-Idempotency-Key` per batch so retries dedupe at the backend.
+- `GFluxError` with stable `code` strings from `error-taxonomy.md`.
+- `py.typed` marker for downstream consumers using `mypy`.
+- Server-key-in-browser guard refuses construction in Pyodide /
+  Emscripten when a `gflux_secret_*` token is passed.

getfluxly-0.1.0/LICENSE

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

getfluxly-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: getfluxly
+Version: 0.1.0
+Summary: GetFluxly Python SDK — server-side events, identify, alias, with batching, retries, and idempotency.
+Project-URL: Homepage, https://getfluxly.com
+Project-URL: Documentation, https://docs.getfluxly.com/sdks/python
+Project-URL: Repository, https://github.com/dineshmiriyala/getfluxly
+Project-URL: Issues, https://github.com/dineshmiriyala/getfluxly/issues
+Author-email: GetFluxly <hello@getfluxly.com>
+License: MIT License
+        
+        Copyright (c) 2026 GetFluxly
+        
+        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.
+License-File: LICENSE
+Keywords: analytics,cdp,events,getfluxly,telemetry
+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: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# getfluxly (Python)
+
+Server-side Python SDK for [GetFluxly](https://getfluxly.com). Same surface as the Node SDK so observability across SDKs lives in one mental model.
+
+```bash
+pip install getfluxly
+```
+
+## Quick start (sync)
+
+```python
+from getfluxly import Client
+
+client = Client(token="gflux_secret_yourtoken")
+
+client.track("subscription_started",
+             external_id="user_42",
+             properties={"plan": "pro"})
+
+client.identify(external_id="user_42",
+                traits={"email": "x@y.com", "plan": "pro"})
+
+client.alias(user_id="user_42", anonymous_id="anon_a8f3c2")
+
+client.flush()
+client.shutdown()  # also runs from atexit
+```
+
+## Quick start (async)
+
+```python
+from getfluxly import AsyncClient
+
+async with AsyncClient(token="gflux_secret_yourtoken") as ac:
+    await ac.track("subscription_started",
+                   external_id="user_42",
+                   properties={"plan": "pro"})
+```
+
+## Defaults
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `flush_at` | 20 | Events queued before forced flush |
+| `flush_interval` | 5.0 | Periodic flush cadence, seconds |
+| `max_retries` | 2 | Per failed batch |
+| `timeout` | 5.0 | Per HTTP request, seconds |
+| `max_queue_size` | 1000 | Hard cap, raises `queue_overflow` |
+
+Retries: 408, 425, 429, and 5xx with exponential backoff and +/- 25% jitter. `Retry-After` is honored. Each batch carries a unique `X-Idempotency-Key`.
+
+## Errors
+
+```python
+from getfluxly import GFluxError
+
+try:
+    client.track("invoice_paid", external_id="user_42")
+except GFluxError as e:
+    if e.code == "queue_overflow":
+        ...  # back-pressure
+    elif e.retryable:
+        ...  # SDK already retried max_retries times
+```
+
+Full code table at `docs.getfluxly.com/snippets/error-table`.
+
+## Server keys never in browser
+
+`Client(token="gflux_secret_...")` refuses to construct if it detects a Pyodide / Emscripten runtime, so a server-side script that accidentally ships to the browser fails loudly instead of leaking the key into client traffic.
+
+## License
+
+MIT, see [LICENSE](./LICENSE).

getfluxly-0.1.0/README.md

@@ -0,0 +1,74 @@
+# getfluxly (Python)
+
+Server-side Python SDK for [GetFluxly](https://getfluxly.com). Same surface as the Node SDK so observability across SDKs lives in one mental model.
+
+```bash
+pip install getfluxly
+```
+
+## Quick start (sync)
+
+```python
+from getfluxly import Client
+
+client = Client(token="gflux_secret_yourtoken")
+
+client.track("subscription_started",
+             external_id="user_42",
+             properties={"plan": "pro"})
+
+client.identify(external_id="user_42",
+                traits={"email": "x@y.com", "plan": "pro"})
+
+client.alias(user_id="user_42", anonymous_id="anon_a8f3c2")
+
+client.flush()
+client.shutdown()  # also runs from atexit
+```
+
+## Quick start (async)
+
+```python
+from getfluxly import AsyncClient
+
+async with AsyncClient(token="gflux_secret_yourtoken") as ac:
+    await ac.track("subscription_started",
+                   external_id="user_42",
+                   properties={"plan": "pro"})
+```
+
+## Defaults
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `flush_at` | 20 | Events queued before forced flush |
+| `flush_interval` | 5.0 | Periodic flush cadence, seconds |
+| `max_retries` | 2 | Per failed batch |
+| `timeout` | 5.0 | Per HTTP request, seconds |
+| `max_queue_size` | 1000 | Hard cap, raises `queue_overflow` |
+
+Retries: 408, 425, 429, and 5xx with exponential backoff and +/- 25% jitter. `Retry-After` is honored. Each batch carries a unique `X-Idempotency-Key`.
+
+## Errors
+
+```python
+from getfluxly import GFluxError
+
+try:
+    client.track("invoice_paid", external_id="user_42")
+except GFluxError as e:
+    if e.code == "queue_overflow":
+        ...  # back-pressure
+    elif e.retryable:
+        ...  # SDK already retried max_retries times
+```
+
+Full code table at `docs.getfluxly.com/snippets/error-table`.
+
+## Server keys never in browser
+
+`Client(token="gflux_secret_...")` refuses to construct if it detects a Pyodide / Emscripten runtime, so a server-side script that accidentally ships to the browser fails loudly instead of leaking the key into client traffic.
+
+## License
+
+MIT, see [LICENSE](./LICENSE).

getfluxly-0.1.0/SECURITY.md

@@ -0,0 +1,6 @@
+# Security policy
+
+To report a vulnerability in `@getfluxly/react`, please follow the disclosure
+process documented at the repository root: [SECURITY.md](../../SECURITY.md).
+
+We do not use GitHub Issues for security reports.

getfluxly-0.1.0/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "getfluxly"
+version = "0.1.0"
+description = "GetFluxly Python SDK — server-side events, identify, alias, with batching, retries, and idempotency."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [{ name = "GetFluxly", email = "hello@getfluxly.com" }]
+keywords = [
+  "analytics",
+  "events",
+  "cdp",
+  "telemetry",
+  "getfluxly",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "respx>=0.21",
+  "mypy>=1.10",
+  "ruff>=0.6",
+  "build>=1.2",
+  "twine>=5.1",
+]
+
+[project.urls]
+Homepage = "https://getfluxly.com"
+Documentation = "https://docs.getfluxly.com/sdks/python"
+Repository = "https://github.com/dineshmiriyala/getfluxly"
+Issues = "https://github.com/dineshmiriyala/getfluxly/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/getfluxly"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/getfluxly",
+  "README.md",
+  "CHANGELOG.md",
+  "LICENSE",
+  "SECURITY.md",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "ASYNC", "SIM"]
+ignore = []
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+mypy_path = "src"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["../../tests/python"]
+# Stop conftest discovery from walking up into tests/conftest.py
+# (a Django/Postgres-aware file used by the smoke + integration
+# suites that imports psycopg). Our SDK suite is self-contained
+# under tests/python/.
+confcutdir = "../../tests/python"
+norecursedirs = ["../../tests/smoke", "../../tests/integration", "../../tests/full_cycle", "../../tests/stress", "../../tests/unit", "../../tests/browser", "../../tests/node", "../../tests/react", "../../tests/next"]

getfluxly-0.1.0/src/getfluxly/__init__.py

@@ -0,0 +1,25 @@
+"""GetFluxly Python SDK.
+
+Server-side events, identify, and alias against the GetFluxly API.
+Sync `Client` and `AsyncClient` share the same surface so application
+code can pick whichever fits its runtime.
+
+Defaults match the Node SDK so an event flowing through any GetFluxly
+SDK shows the same batching / retry / idempotency posture.
+"""
+
+from ._version import SDK_VERSION
+from .async_client import AsyncClient
+from .client import Client
+from .errors import GFluxError
+from .identity import AliasInput, IdentifyInput, TrackInput
+
+__all__ = [
+    "AsyncClient",
+    "AliasInput",
+    "Client",
+    "GFluxError",
+    "IdentifyInput",
+    "SDK_VERSION",
+    "TrackInput",
+]

getfluxly-0.1.0/src/getfluxly/_http.py

@@ -0,0 +1,226 @@
+"""Thin httpx wrapper with retry, jitter, and Retry-After.
+
+Mirrors the Node SDK's retry posture: 408 / 425 / 429 / 5xx retried
+with exponential backoff and +/- 25% jitter, ``Retry-After`` honored
+when present. Each request carries the SDK identity header so server
+logs can split traffic by SDK family + version.
+"""
+
+from __future__ import annotations
+
+import json
+import random
+import sys
+import uuid
+from typing import Any
+
+import httpx
+
+from ._version import SDK_VERSION
+from .errors import GFluxError
+
+DEFAULT_API_HOST = "https://api.getfluxly.com"
+SDK_LIBRARY = f"gflux-python/{SDK_VERSION}"
+RETRY_STATUSES = {408, 425, 429}
+
+
+def is_browser_runtime() -> bool:
+    """Return True if we're running inside a browser-like Python runtime.
+
+    Used by ``Client.__init__`` to refuse the construction if a server
+    token is being initialized in Pyodide / Emscripten. Server keys
+    must never reach client bundles.
+    """
+    return sys.platform == "emscripten" or "pyodide" in sys.modules
+
+
+def generate_idempotency_key() -> str:
+    return str(uuid.uuid4())
+
+
+def _retry_after_ms(retry_after_header: str | None, attempt: int) -> int:
+    if retry_after_header:
+        try:
+            return int(float(retry_after_header) * 1000)
+        except (TypeError, ValueError):
+            pass
+    base_ms = 200 * (2**attempt)
+    jitter = base_ms * 0.25
+    return int(base_ms + random.uniform(-jitter, jitter))
+
+
+def _should_retry(status: int) -> bool:
+    return status in RETRY_STATUSES or 500 <= status < 600
+
+
+def parse_response(response: httpx.Response) -> dict[str, Any]:
+    text = response.text or ""
+    if not text:
+        return {}
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError as exc:
+        if response.is_success:
+            raise GFluxError(
+                "gflux response body was not valid JSON",
+                code="invalid_response",
+                retryable=True,
+                status=response.status_code,
+                details={"snippet": text[:200]},
+            ) from exc
+        return {"_raw": text[:200]}
+    return parsed if isinstance(parsed, dict) else {"_raw": parsed}
+
+
+def http_error(response: httpx.Response, parsed: dict[str, Any]) -> GFluxError:
+    error_block = parsed.get("error")
+    if isinstance(error_block, dict):
+        code = error_block.get("code") or "server_error"
+        message = error_block.get("message") or response.reason_phrase
+    elif isinstance(error_block, str):
+        code = error_block
+        message = parsed.get("detail") or response.reason_phrase
+    else:
+        code = "server_error"
+        message = response.reason_phrase or "request failed"
+    retry_after = response.headers.get("Retry-After")
+    return GFluxError(
+        message,
+        code=code,
+        retryable=_should_retry(response.status_code),
+        retry_after_ms=_retry_after_ms(retry_after, 0) if retry_after else None,
+        status=response.status_code,
+        details=parsed,
+    )
+
+
+def serialize(payload: Any) -> bytes:
+    return json.dumps(payload, separators=(",", ":"), default=str).encode("utf-8")
+
+
+class HttpClient:
+    """Sync httpx wrapper. Used by ``Client``."""
+
+    def __init__(
+        self,
+        *,
+        token: str,
+        api_host: str,
+        timeout: float,
+        max_retries: int,
+    ) -> None:
+        self.token = token
+        self.api_host = api_host.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._client = httpx.Client(timeout=timeout)
+
+    def post(
+        self,
+        url: str,
+        body: Any,
+        *,
+        idempotency_key: str | None = None,
+        request_id: str | None = None,
+    ) -> dict[str, Any]:
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.token}",
+            "X-GFlux-SDK": SDK_LIBRARY,
+        }
+        if idempotency_key:
+            headers["X-Idempotency-Key"] = idempotency_key
+        if request_id:
+            headers["X-Request-Id"] = request_id
+
+        payload = serialize(body)
+
+        last_error: Exception | None = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._client.post(url, content=payload, headers=headers)
+            except httpx.HTTPError as exc:
+                last_error = exc
+                if attempt < self.max_retries:
+                    continue
+                raise GFluxError(
+                    f"network error after {attempt + 1} attempts: {exc}",
+                    code="transport_error",
+                    retryable=True,
+                ) from exc
+
+            parsed = parse_response(response)
+            if response.is_success:
+                return parsed
+            if _should_retry(response.status_code) and attempt < self.max_retries:
+                continue
+            raise http_error(response, parsed)
+
+        # Unreachable; the loop above either returns or raises.
+        assert last_error is not None
+        raise GFluxError("postJson exited without a result", code="internal_error")
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncHttpClient:
+    """Async httpx wrapper. Used by ``AsyncClient``."""
+
+    def __init__(
+        self,
+        *,
+        token: str,
+        api_host: str,
+        timeout: float,
+        max_retries: int,
+    ) -> None:
+        self.token = token
+        self.api_host = api_host.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._client = httpx.AsyncClient(timeout=timeout)
+
+    async def post(
+        self,
+        url: str,
+        body: Any,
+        *,
+        idempotency_key: str | None = None,
+        request_id: str | None = None,
+    ) -> dict[str, Any]:
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.token}",
+            "X-GFlux-SDK": SDK_LIBRARY,
+        }
+        if idempotency_key:
+            headers["X-Idempotency-Key"] = idempotency_key
+        if request_id:
+            headers["X-Request-Id"] = request_id
+
+        payload = serialize(body)
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await self._client.post(url, content=payload, headers=headers)
+            except httpx.HTTPError as exc:
+                if attempt < self.max_retries:
+                    continue
+                raise GFluxError(
+                    f"network error after {attempt + 1} attempts: {exc}",
+                    code="transport_error",
+                    retryable=True,
+                ) from exc
+
+            parsed = parse_response(response)
+            if response.is_success:
+                return parsed
+            if _should_retry(response.status_code) and attempt < self.max_retries:
+                continue
+            raise http_error(response, parsed)
+
+        raise GFluxError("postJson exited without a result", code="internal_error")
+
+    async def aclose(self) -> None:
+        await self._client.aclose()

getfluxly-0.1.0/src/getfluxly/_version.py

@@ -0,0 +1,5 @@
+"""Auto-generated by scripts/sync_version.py. Do not edit by hand,
+run ``python scripts/sync_version.py`` to regenerate from pyproject.toml.
+"""
+
+SDK_VERSION = "0.1.0"

getfluxly-0.1.0/src/getfluxly/async_client.py

@@ -0,0 +1,217 @@
+"""Async ``AsyncClient`` for asyncio runtimes."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from ._http import (
+    DEFAULT_API_HOST,
+    AsyncHttpClient,
+    generate_idempotency_key,
+    is_browser_runtime,
+)
+from .batch import (
+    EventEnvelope,
+    EventQueue,
+    FlushResult,
+    combine,
+    empty_flush_result,
+)
+from .errors import GFluxError
+from .identity import (
+    AliasInput,
+    require_alias_source,
+    require_one_id,
+)
+
+
+class AsyncClient:
+    """Asynchronous GetFluxly client.
+
+    Use as an ``async with`` context manager — the manager calls
+    ``aclose()`` on exit which flushes any buffered events.
+    """
+
+    def __init__(
+        self,
+        *,
+        token: str,
+        api_host: str = DEFAULT_API_HOST,
+        flush_at: int = 20,
+        flush_interval: float = 5.0,
+        max_retries: int = 2,
+        timeout: float = 5.0,
+        max_queue_size: int = 1000,
+    ) -> None:
+        if not token:
+            raise GFluxError("token is required", code="validation_error")
+        if token.startswith("gflux_secret_") and is_browser_runtime():
+            raise GFluxError(
+                "server token detected in a browser-like Python runtime; "
+                "use a publishable key or move this code server-side",
+                code="server_key_in_browser",
+            )
+
+        self._token = token
+        self._api_host = api_host.rstrip("/")
+        self._flush_at = flush_at
+        self._flush_interval = flush_interval
+
+        self._queue = EventQueue(max_size=max_queue_size)
+        self._http = AsyncHttpClient(
+            token=token,
+            api_host=self._api_host,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._lock = asyncio.Lock()
+        self._closed = False
+
+    # ------------------------------------------------------------------ public
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def track(
+        self,
+        event: str,
+        *,
+        anonymous_id: str | None = None,
+        external_id: str | None = None,
+        user_id: str | None = None,
+        properties: dict[str, Any] | None = None,
+        timestamp: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> FlushResult | None:
+        require_one_id(
+            anonymous_id=anonymous_id,
+            external_id=external_id,
+            user_id=user_id,
+        )
+        payload: dict[str, Any] = {"event": event}
+        if anonymous_id:
+            payload["anonymous_id"] = anonymous_id
+        if external_id:
+            payload["external_id"] = external_id
+        if user_id:
+            payload["user_id"] = user_id
+        if properties is not None:
+            payload["properties"] = properties
+        if timestamp is not None:
+            payload["timestamp"] = timestamp
+        if context is not None:
+            payload["context"] = context
+        return await self._enqueue(payload)
+
+    async def identify(
+        self,
+        *,
+        anonymous_id: str | None = None,
+        external_id: str | None = None,
+        user_id: str | None = None,
+        traits: dict[str, Any] | None = None,
+    ) -> FlushResult | None:
+        require_one_id(
+            anonymous_id=anonymous_id,
+            external_id=external_id,
+            user_id=user_id,
+        )
+        payload: dict[str, Any] = {"event": "$identify"}
+        if anonymous_id:
+            payload["anonymous_id"] = anonymous_id
+        if external_id:
+            payload["external_id"] = external_id
+        if user_id:
+            payload["user_id"] = user_id
+        if traits is not None:
+            payload["traits"] = traits
+        return await self._enqueue(payload)
+
+    async def alias(
+        self,
+        *,
+        user_id: str,
+        anonymous_id: str | None = None,
+        previous_id: str | None = None,
+        request_id: str | None = None,
+    ) -> dict[str, Any]:
+        require_alias_source(
+            AliasInput(
+                user_id=user_id,
+                anonymous_id=anonymous_id,
+                previous_id=previous_id,
+            )
+        )
+        body: dict[str, Any] = {"user_id": user_id}
+        if anonymous_id:
+            body["anonymous_id"] = anonymous_id
+        if previous_id:
+            body["previous_id"] = previous_id
+        response = await self._http.post(
+            f"{self._api_host}/v1/identify/alias",
+            body,
+            idempotency_key=generate_idempotency_key(),
+            request_id=request_id,
+        )
+        alias_obj = response.get("alias")
+        if not alias_obj:
+            raise GFluxError(
+                "alias response did not include alias data",
+                code="invalid_response",
+                retryable=True,
+                details=response,
+            )
+        return alias_obj if isinstance(alias_obj, dict) else {"_raw": alias_obj}
+
+    async def flush(self) -> FlushResult:
+        result = empty_flush_result()
+        while True:
+            async with self._lock:
+                batch = self._queue.drain(self._flush_at)
+            if not batch:
+                break
+            try:
+                response = await self._http.post(
+                    f"{self._api_host}/v1/events/batch",
+                    {"events": [e.payload for e in batch]},
+                    idempotency_key=generate_idempotency_key(),
+                )
+            except GFluxError as exc:
+                if exc.retryable:
+                    async with self._lock:
+                        self._queue.requeue_front(batch)
+                raise
+            result = combine(
+                result,
+                FlushResult(
+                    accepted=int(response.get("accepted", len(batch))),
+                    rejected=int(response.get("rejected", 0)),
+                    batches=1,
+                    errors=list(response.get("errors", [])),
+                ),
+            )
+        return result
+
+    async def aclose(self) -> FlushResult:
+        async with self._lock:
+            if self._closed:
+                return empty_flush_result()
+            self._closed = True
+        try:
+            return await self.flush()
+        finally:
+            await self._http.aclose()
+
+    # ----------------------------------------------------------------- private
+
+    async def _enqueue(self, payload: dict[str, Any]) -> FlushResult | None:
+        async with self._lock:
+            self._queue.enqueue(EventEnvelope(payload=payload))
+            should_flush = len(self._queue) >= self._flush_at
+        if should_flush:
+            return await self.flush()
+        return None

getfluxly-0.1.0/src/getfluxly/batch.py

@@ -0,0 +1,77 @@
+"""Shared event-queue / flush logic. Used by both Client and AsyncClient."""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import GFluxError
+
+
+@dataclass
+class FlushResult:
+    accepted: int
+    rejected: int
+    batches: int
+    errors: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class EventEnvelope:
+    """A single event ready for the wire.
+
+    Stays as a plain dict-style payload so the HTTP layer can JSON-
+    encode without further translation.
+    """
+
+    payload: dict[str, Any]
+
+
+class EventQueue:
+    """A bounded queue of events awaiting flush.
+
+    ``max_size`` is a hard cap. Enqueueing beyond it raises
+    ``queue_overflow`` so the caller can apply back-pressure rather
+    than silently dropping events.
+    """
+
+    def __init__(self, max_size: int) -> None:
+        self._dq: deque[EventEnvelope] = deque()
+        self._max_size = max_size
+
+    def __len__(self) -> int:
+        return len(self._dq)
+
+    def enqueue(self, env: EventEnvelope) -> None:
+        if len(self._dq) >= self._max_size:
+            raise GFluxError(
+                f"event queue is full ({self._max_size}); flush before enqueueing more",
+                code="queue_overflow",
+                retryable=False,
+                details={"max_size": self._max_size},
+            )
+        self._dq.append(env)
+
+    def drain(self, max_events: int) -> list[EventEnvelope]:
+        out: list[EventEnvelope] = []
+        for _ in range(min(max_events, len(self._dq))):
+            out.append(self._dq.popleft())
+        return out
+
+    def requeue_front(self, envs: list[EventEnvelope]) -> None:
+        for env in reversed(envs):
+            self._dq.appendleft(env)
+
+
+def empty_flush_result() -> FlushResult:
+    return FlushResult(accepted=0, rejected=0, batches=0, errors=[])
+
+
+def combine(a: FlushResult, b: FlushResult) -> FlushResult:
+    return FlushResult(
+        accepted=a.accepted + b.accepted,
+        rejected=a.rejected + b.rejected,
+        batches=a.batches + b.batches,
+        errors=a.errors + b.errors,
+    )

getfluxly-0.1.0/src/getfluxly/client.py

@@ -0,0 +1,225 @@
+"""Sync ``Client`` for server-side use."""
+
+from __future__ import annotations
+
+import atexit
+import contextlib
+import threading
+from typing import Any
+
+from ._http import (
+    DEFAULT_API_HOST,
+    HttpClient,
+    generate_idempotency_key,
+    is_browser_runtime,
+)
+from .batch import (
+    EventEnvelope,
+    EventQueue,
+    FlushResult,
+    combine,
+    empty_flush_result,
+)
+from .errors import GFluxError
+from .identity import (
+    AliasInput,
+    require_alias_source,
+    require_one_id,
+)
+
+
+class Client:
+    """Synchronous GetFluxly client.
+
+    Construction is cheap. The HTTP client is lazy — the first ``track``
+    or ``identify`` call wires up the queue; ``flush`` and ``shutdown``
+    drive the network round-trips.
+    """
+
+    def __init__(
+        self,
+        *,
+        token: str,
+        api_host: str = DEFAULT_API_HOST,
+        flush_at: int = 20,
+        flush_interval: float = 5.0,
+        max_retries: int = 2,
+        timeout: float = 5.0,
+        max_queue_size: int = 1000,
+    ) -> None:
+        if not token:
+            raise GFluxError("token is required", code="validation_error")
+        if token.startswith("gflux_secret_") and is_browser_runtime():
+            raise GFluxError(
+                "server token detected in a browser-like Python runtime; "
+                "use a publishable key or move this code server-side",
+                code="server_key_in_browser",
+            )
+
+        self._token = token
+        self._api_host = api_host.rstrip("/")
+        self._flush_at = flush_at
+        self._flush_interval = flush_interval
+        self._max_queue_size = max_queue_size
+
+        self._queue = EventQueue(max_size=max_queue_size)
+        self._http = HttpClient(
+            token=token,
+            api_host=self._api_host,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._lock = threading.Lock()
+        self._shutdown = False
+
+        atexit.register(self._safe_shutdown)
+
+    # ------------------------------------------------------------------ public
+
+    def track(
+        self,
+        event: str,
+        *,
+        anonymous_id: str | None = None,
+        external_id: str | None = None,
+        user_id: str | None = None,
+        properties: dict[str, Any] | None = None,
+        timestamp: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> FlushResult | None:
+        require_one_id(
+            anonymous_id=anonymous_id,
+            external_id=external_id,
+            user_id=user_id,
+        )
+        payload: dict[str, Any] = {"event": event}
+        if anonymous_id:
+            payload["anonymous_id"] = anonymous_id
+        if external_id:
+            payload["external_id"] = external_id
+        if user_id:
+            payload["user_id"] = user_id
+        if properties is not None:
+            payload["properties"] = properties
+        if timestamp is not None:
+            payload["timestamp"] = timestamp
+        if context is not None:
+            payload["context"] = context
+        return self._enqueue(payload)
+
+    def identify(
+        self,
+        *,
+        anonymous_id: str | None = None,
+        external_id: str | None = None,
+        user_id: str | None = None,
+        traits: dict[str, Any] | None = None,
+    ) -> FlushResult | None:
+        require_one_id(
+            anonymous_id=anonymous_id,
+            external_id=external_id,
+            user_id=user_id,
+        )
+        payload: dict[str, Any] = {"event": "$identify"}
+        if anonymous_id:
+            payload["anonymous_id"] = anonymous_id
+        if external_id:
+            payload["external_id"] = external_id
+        if user_id:
+            payload["user_id"] = user_id
+        if traits is not None:
+            payload["traits"] = traits
+        return self._enqueue(payload)
+
+    def alias(
+        self,
+        *,
+        user_id: str,
+        anonymous_id: str | None = None,
+        previous_id: str | None = None,
+        request_id: str | None = None,
+    ) -> dict[str, Any]:
+        require_alias_source(
+            AliasInput(
+                user_id=user_id,
+                anonymous_id=anonymous_id,
+                previous_id=previous_id,
+            )
+        )
+        body: dict[str, Any] = {"user_id": user_id}
+        if anonymous_id:
+            body["anonymous_id"] = anonymous_id
+        if previous_id:
+            body["previous_id"] = previous_id
+        url = f"{self._api_host}/v1/identify/alias"
+        response = self._http.post(
+            url,
+            body,
+            idempotency_key=generate_idempotency_key(),
+            request_id=request_id,
+        )
+        alias_obj = response.get("alias")
+        if not alias_obj:
+            raise GFluxError(
+                "alias response did not include alias data",
+                code="invalid_response",
+                retryable=True,
+                details=response,
+            )
+        return alias_obj if isinstance(alias_obj, dict) else {"_raw": alias_obj}
+
+    def flush(self) -> FlushResult:
+        result = empty_flush_result()
+        while True:
+            with self._lock:
+                batch = self._queue.drain(self._flush_at)
+            if not batch:
+                break
+            try:
+                response = self._http.post(
+                    f"{self._api_host}/v1/events/batch",
+                    {"events": [e.payload for e in batch]},
+                    idempotency_key=generate_idempotency_key(),
+                )
+            except GFluxError as exc:
+                if exc.retryable:
+                    # Requeue so a later flush retries. Same key would
+                    # collide; let the next flush mint a new one.
+                    with self._lock:
+                        self._queue.requeue_front(batch)
+                raise
+            result = combine(
+                result,
+                FlushResult(
+                    accepted=int(response.get("accepted", len(batch))),
+                    rejected=int(response.get("rejected", 0)),
+                    batches=1,
+                    errors=list(response.get("errors", [])),
+                ),
+            )
+        return result
+
+    def shutdown(self) -> FlushResult:
+        with self._lock:
+            if self._shutdown:
+                return empty_flush_result()
+            self._shutdown = True
+        try:
+            return self.flush()
+        finally:
+            self._http.close()
+
+    # ----------------------------------------------------------------- private
+
+    def _enqueue(self, payload: dict[str, Any]) -> FlushResult | None:
+        with self._lock:
+            self._queue.enqueue(EventEnvelope(payload=payload))
+            should_flush = len(self._queue) >= self._flush_at
+        if should_flush:
+            return self.flush()
+        return None
+
+    def _safe_shutdown(self) -> None:
+        # atexit: never raise on interpreter shutdown
+        with contextlib.suppress(Exception):
+            self.shutdown()

getfluxly-0.1.0/src/getfluxly/errors.py

@@ -0,0 +1,45 @@
+"""Typed error surface for the SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class GFluxError(Exception):
+    """Every error raised by the SDK is a ``GFluxError``.
+
+    The ``code`` attribute is one of the strings from
+    docs/sdk-standards/error-taxonomy.md and is stable across SDK
+    versions. ``retryable`` indicates whether the SDK already attempted
+    a retry, so callers know "wait and retry yourself" vs "fix the
+    payload".
+    """
+
+    code: str
+    retryable: bool
+    retry_after_ms: int | None
+    status: int | None
+    details: dict[str, Any]
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str,
+        retryable: bool = False,
+        retry_after_ms: int | None = None,
+        status: int | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.retryable = retryable
+        self.retry_after_ms = retry_after_ms
+        self.status = status
+        self.details = details or {}
+
+    def __repr__(self) -> str:
+        return (
+            f"GFluxError(code={self.code!r}, retryable={self.retryable}, "
+            f"status={self.status}, message={super().__str__()!r})"
+        )

getfluxly-0.1.0/src/getfluxly/identity.py

@@ -0,0 +1,64 @@
+"""Input dataclasses for ``track``, ``identify``, and ``alias``.
+
+Field names mirror the wire shape: ``external_id`` (snake_case),
+``anonymous_id``, etc. These are the same names the public REST API
+accepts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import GFluxError
+
+
+@dataclass
+class TrackInput:
+    event: str
+    anonymous_id: str | None = None
+    external_id: str | None = None
+    user_id: str | None = None
+    properties: dict[str, Any] | None = None
+    timestamp: str | None = None
+    context: dict[str, Any] | None = None
+
+
+@dataclass
+class IdentifyInput:
+    anonymous_id: str | None = None
+    external_id: str | None = None
+    user_id: str | None = None
+    traits: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class AliasInput:
+    user_id: str
+    anonymous_id: str | None = None
+    previous_id: str | None = None
+
+
+def require_one_id(
+    *, anonymous_id: str | None, external_id: str | None, user_id: str | None
+) -> None:
+    """Mirror the API's identity rule: at least one identifier must be set."""
+
+    if not any([anonymous_id, external_id, user_id]):
+        raise GFluxError(
+            "track / identify requires at least one of anonymous_id, external_id, user_id",
+            code="validation_error",
+        )
+
+
+def require_alias_source(input: AliasInput) -> None:
+    if not input.user_id:
+        raise GFluxError(
+            "alias requires user_id",
+            code="validation_error",
+        )
+    if not (input.anonymous_id or input.previous_id):
+        raise GFluxError(
+            "alias requires anonymous_id or previous_id",
+            code="validation_error",
+        )