azfive-capture 0.1.0__tar.gz

azfive_capture-0.1.0/.gitignore

@@ -0,0 +1,69 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+*.egg
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Node
+node_modules/
+dist/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Data
+*.parquet
+*.csv
+*.db
+
+# Rust
+**/target/
+
+# AI coding-tool state (local per-developer config/session data)
+.claude/
+.agents/
+.codex/
+
+# Impeccable (cache/session data — design.json is derived from DESIGN.md)
+.impeccable/
+frontend/src/.impeccable/
+
+# Playwright
+playwright-report/
+test-results/
+
+# DB backups
+azfive-backup-*.sql
+
+# Built frontend (produced by the Docker build's `npm run build`). Never commit
+# it: stale committed chunks get served alongside fresh ones and can pin an old
+# bundle that lacks the X-AzFive-Branch header, silently routing branch writes to main.
+backend/static/
+
+# SDK build outputs (sdk-ios SwiftPM, Flutter, Android/Gradle)
+sdk-ios/.build/
+sdk-flutter/build/
+sdk-flutter/.dart_tool/
+sdk-android/.gradle/
+sdk-android/**/build/
+sdk-jvm/.gradle/
+sdk-jvm/build/

azfive_capture-0.1.0/LICENSE

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

azfive_capture-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: azfive-capture
+Version: 0.1.0
+Summary: Capture product-analytics events into AzFive from Python servers — events, identity, feature flags & experiments.
+Author: AzFive
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# azfive-capture (Python)
+
+AzFive product analytics for Python servers — events, identity, super
+properties, and feature flags/experiments. Zero dependencies (stdlib only).
+See `sdk-spec/SPEC.md` in the AzFive repo for the cross-SDK contract.
+
+## Install
+
+```bash
+pip install azfive-capture
+```
+
+Use a **secret** API key with the `events:write` scope (AzFive → Settings → API
+Keys). Secret keys are also valid on `/v1/decide`, so server-side flag
+evaluation needs no extra setup.
+
+## Quickstart
+
+```python
+from azfive_capture import Client
+
+azfive = Client("azfive_…", host="https://analytics.example.com", project="backend")
+
+azfive.capture("invoice_paid", {"amount": 99}, distinct_id="user-42")
+azfive.people.set({"plan": "pro"}, distinct_id="user-42")
+
+# experiments / feature flags — get_flag() reports the exposure automatically,
+# deduped per (distinct_id, flag, value)
+variant = azfive.get_flag("user-42", "exp-checkout")   # 'control' | 'test' | False | None
+if azfive.is_flag_enabled("user-42", "new-onboarding"):
+    ...
+
+azfive.flush()   # also flushed by the background thread and at exit
+```
+
+Batching: events queue in memory (batch 10 / 5 s / max 1000, oldest dropped)
+and are delivered by a daemon thread; failed batches retry on the next tick.
+`close()` (also registered via `atexit`) drains the queue.
+
+## Tests
+
+```bash
+pip install -e '.[dev]' && pytest   # golden vectors from ../sdk-spec/vectors
+```

azfive_capture-0.1.0/README.md

@@ -0,0 +1,44 @@
+# azfive-capture (Python)
+
+AzFive product analytics for Python servers — events, identity, super
+properties, and feature flags/experiments. Zero dependencies (stdlib only).
+See `sdk-spec/SPEC.md` in the AzFive repo for the cross-SDK contract.
+
+## Install
+
+```bash
+pip install azfive-capture
+```
+
+Use a **secret** API key with the `events:write` scope (AzFive → Settings → API
+Keys). Secret keys are also valid on `/v1/decide`, so server-side flag
+evaluation needs no extra setup.
+
+## Quickstart
+
+```python
+from azfive_capture import Client
+
+azfive = Client("azfive_…", host="https://analytics.example.com", project="backend")
+
+azfive.capture("invoice_paid", {"amount": 99}, distinct_id="user-42")
+azfive.people.set({"plan": "pro"}, distinct_id="user-42")
+
+# experiments / feature flags — get_flag() reports the exposure automatically,
+# deduped per (distinct_id, flag, value)
+variant = azfive.get_flag("user-42", "exp-checkout")   # 'control' | 'test' | False | None
+if azfive.is_flag_enabled("user-42", "new-onboarding"):
+    ...
+
+azfive.flush()   # also flushed by the background thread and at exit
+```
+
+Batching: events queue in memory (batch 10 / 5 s / max 1000, oldest dropped)
+and are delivered by a daemon thread; failed batches retry on the next tick.
+`close()` (also registered via `atexit`) drains the queue.
+
+## Tests
+
+```bash
+pip install -e '.[dev]' && pytest   # golden vectors from ../sdk-spec/vectors
+```

azfive_capture-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "azfive-capture"
+version = "0.1.0"
+description = "Capture product-analytics events into AzFive from Python servers — events, identity, feature flags & experiments."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "AzFive" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/azfive_capture"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

azfive_capture-0.1.0/src/azfive_capture/__init__.py

@@ -0,0 +1,11 @@
+"""azfive-capture — AzFive product analytics for Python servers.
+
+Events, identity, super properties and feature flags/experiments against a
+AzFive deployment.  See ``sdk-spec/SPEC.md`` in the AzFive repo for the
+cross-SDK behavioral contract.
+"""
+
+from .client import LIB_NAME, LIB_VERSION, Client, create_client
+from .flags import FlagValue
+
+__all__ = ["Client", "create_client", "FlagValue", "LIB_NAME", "LIB_VERSION"]

azfive_capture-0.1.0/src/azfive_capture/client.py

@@ -0,0 +1,324 @@
+"""AzFive capture client for Python servers.
+
+Port of ``@azfive/capture`` (see ``sdk-spec/SPEC.md``): same event envelope,
+merge order, batching semantics and flag exposure rules, adapted to a server
+runtime — in-memory identity, no session, background flush thread, and flag
+evaluation per ``distinct_id`` through ``/v1/decide`` with a secret key.
+
+    from azfive_capture import Client
+
+    azfive = Client("azfive_…", host="https://analytics.example.com")
+    azfive.capture("invoice_paid", {"amount": 99}, distinct_id="user-42")
+    variant = azfive.get_flag("user-42", "exp-checkout")
+    azfive.flush()
+"""
+
+from __future__ import annotations
+
+import atexit
+import platform
+import threading
+from datetime import datetime, timezone
+from typing import Any
+
+from . import transport
+from .flags import FlagsManager, FlagValue
+
+LIB_VERSION = "0.1.0"
+LIB_NAME = "azfive-python"
+
+DEFAULT_BATCH_SIZE = 10
+DEFAULT_FLUSH_INTERVAL_S = 5.0
+DEFAULT_MAX_QUEUE_SIZE = 1000
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _static_props() -> dict:
+    return {
+        "$os": platform.system() or "Unknown",
+        "$os_version": platform.release() or "",
+        "$device_type": "Server",
+    }
+
+
+def merge_properties(
+    static: dict, session: dict, super_props: dict, event: dict, reserved: dict
+) -> dict:
+    """The spec'd merge order: static < session < super < event < reserved.
+    (Server SDKs have no dynamic layer; session is empty for them.)"""
+    return {**static, **session, **super_props, **event, **reserved}
+
+
+class People:
+    """``people.set`` / ``people.set_once`` — person-property events."""
+
+    def __init__(self, client: "Client") -> None:
+        self._client = client
+
+    def set(self, properties: dict, distinct_id: str | None = None) -> None:
+        self._client._track("az.set", {}, set_props=properties, distinct_id=distinct_id)
+
+    def set_once(self, properties: dict, distinct_id: str | None = None) -> None:
+        self._client._track("az.set_once", {}, set_once_props=properties, distinct_id=distinct_id)
+
+
+class Client:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        host: str,
+        project: str = "default",
+        batch_size: int = DEFAULT_BATCH_SIZE,
+        flush_interval_s: float = DEFAULT_FLUSH_INTERVAL_S,
+        max_queue_size: int = DEFAULT_MAX_QUEUE_SIZE,
+        gzip: bool = False,
+        opt_out: bool = False,
+        disable_decide: bool = False,
+        extra_static_props: dict | None = None,
+        start_flush_thread: bool = True,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        if not host:
+            raise ValueError("host is required")
+        self._api_key = api_key
+        self._host = host.rstrip("/")
+        self._project = project
+        self._batch_size = batch_size
+        self._flush_interval_s = flush_interval_s
+        self._max_queue_size = max_queue_size
+        self._gzip = gzip
+        self._opted_out = opt_out
+
+        self._distinct_id = transport.uuid4()
+        self._device_id = transport.uuid4()
+        self._identified = False
+        self._super_props: dict = {}
+        self._static = {**_static_props(), **(extra_static_props or {})}
+
+        self._queue: list[dict] = []
+        self._lock = threading.Lock()
+        self._closed = False
+
+        self.people = People(self)
+        self._flags: FlagsManager | None = None
+        if not disable_decide:
+            self._flags = FlagsManager(
+                host=self._host,
+                api_key=api_key,
+                project=project,
+                capture=self._capture_for_flags,
+            )
+
+        self._flush_event = threading.Event()
+        self._thread: threading.Thread | None = None
+        if start_flush_thread:
+            self._thread = threading.Thread(
+                target=self._flush_loop, name="azfive-capture-flush", daemon=True
+            )
+            self._thread.start()
+        atexit.register(self.close)
+
+    # ── Identity ──────────────────────────────────────────────────────────────
+
+    def get_distinct_id(self) -> str:
+        return self._distinct_id
+
+    def get_session_id(self) -> str:
+        return ""  # servers have no session
+
+    def identify(
+        self, distinct_id: str, set: dict | None = None, set_once: dict | None = None
+    ) -> None:
+        did = str(distinct_id)
+        if self._identified and self._distinct_id == did:
+            if set or set_once:
+                self._track("az.set", {}, set_props=set, set_once_props=set_once)
+            return
+        prev = self._distinct_id
+        self._distinct_id = did
+        self._identified = True
+        self._track(
+            "az.identify",
+            {"$anon_distinct_id": prev},
+            set_props=set,
+            set_once_props=set_once,
+            distinct_id=did,
+        )
+        if self._flags:
+            self._flags.reload_flags(did)
+
+    def alias(self, alias: str) -> None:
+        self._track("az.alias", {"alias": str(alias)})
+
+    def reset(self, reset_device_id: bool = False) -> None:
+        self._identified = False
+        self._distinct_id = transport.uuid4()
+        self._super_props = {}
+        if reset_device_id:
+            self._device_id = transport.uuid4()
+        # opt-out is intentionally preserved across reset()
+
+    # ── Super properties ──────────────────────────────────────────────────────
+
+    def register(self, props: dict) -> None:
+        self._super_props = {**self._super_props, **props}
+
+    def register_once(self, props: dict) -> None:
+        self._super_props = {**props, **self._super_props}  # existing values win
+
+    def unregister(self, key: str) -> None:
+        self._super_props.pop(key, None)
+
+    # ── Opt-out ───────────────────────────────────────────────────────────────
+
+    def opt_in_capturing(self) -> None:
+        self._opted_out = False
+
+    def opt_out_capturing(self) -> None:
+        self._opted_out = True
+
+    def has_opted_out_capturing(self) -> bool:
+        return self._opted_out
+
+    # ── Capture ───────────────────────────────────────────────────────────────
+
+    def capture(
+        self, event: str, properties: dict | None = None, *, distinct_id: str | None = None
+    ) -> None:
+        self._track(event, properties or {}, distinct_id=distinct_id)
+
+    def _capture_for_flags(
+        self, event: str, properties: dict, *, distinct_id: str
+    ) -> None:
+        self._track(event, properties, distinct_id=distinct_id)
+
+    def _track(
+        self,
+        event: str,
+        properties: dict,
+        *,
+        set_props: dict | None = None,
+        set_once_props: dict | None = None,
+        distinct_id: str | None = None,
+    ) -> None:
+        if self._opted_out:
+            return
+        props = dict(properties)
+        did = distinct_id or self._distinct_id
+        if props.get("distinct_id") is not None:
+            did = str(props.pop("distinct_id"))
+        evt: dict = {
+            "event": event,
+            "distinct_id": did,
+            "timestamp": _now_iso(),
+            "uuid": transport.uuid4(),
+            "properties": merge_properties(
+                self._static,
+                {},
+                self._super_props,
+                props,
+                {"$lib": LIB_NAME, "$lib_version": LIB_VERSION, "$device_id": self._device_id},
+            ),
+        }
+        if set_props:
+            evt["$set"] = set_props
+        if set_once_props:
+            evt["$set_once"] = set_once_props
+        self._enqueue(evt)
+
+    def _enqueue(self, evt: dict) -> None:
+        with self._lock:
+            self._queue.append(evt)
+            if len(self._queue) > self._max_queue_size:
+                del self._queue[: len(self._queue) - self._max_queue_size]
+            trigger = len(self._queue) >= self._batch_size
+        if trigger:
+            self._request_flush()
+
+    def _request_flush(self) -> None:
+        # With the background thread running, hand off (capture() never blocks
+        # on network I/O); without it (tests, single-shot scripts) flush inline.
+        if self._thread is not None:
+            self._flush_event.set()
+        else:
+            self.flush()
+
+    # ── Feature flags ─────────────────────────────────────────────────────────
+
+    def get_flag(
+        self, distinct_id: str, key: str, person_properties: dict | None = None
+    ) -> FlagValue | None:
+        if self._flags is None:
+            return None
+        return self._flags.get_flag(distinct_id, key, person_properties)
+
+    def is_flag_enabled(
+        self, distinct_id: str, key: str, person_properties: dict | None = None
+    ) -> bool:
+        if self._flags is None:
+            return False
+        return self._flags.is_flag_enabled(distinct_id, key, person_properties)
+
+    def get_flag_payload(
+        self, distinct_id: str, key: str, person_properties: dict | None = None
+    ) -> Any:
+        if self._flags is None:
+            return None
+        return self._flags.get_flag_payload(distinct_id, key, person_properties)
+
+    def reload_flags(self, distinct_id: str) -> None:
+        if self._flags is not None:
+            self._flags.reload_flags(distinct_id)
+
+    # ── Delivery ──────────────────────────────────────────────────────────────
+
+    def _send(self, batch: list[dict]) -> bool:
+        return transport.send_batch(
+            batch,
+            host=self._host,
+            api_key=self._api_key,
+            project=self._project,
+            gzip=self._gzip,
+        )
+
+    def flush(self) -> None:
+        with self._lock:
+            if not self._queue:
+                return
+            batch = self._queue
+            self._queue = []
+        if not self._send(batch):
+            with self._lock:
+                # Re-queue at the FRONT, bounded keeping the newest events.
+                self._queue = (batch + self._queue)[-self._max_queue_size:]
+
+    def _flush_loop(self) -> None:
+        while not self._closed:
+            self._flush_event.wait(timeout=self._flush_interval_s)
+            self._flush_event.clear()
+            if self._closed:
+                return
+            try:
+                self.flush()
+            except Exception:  # never kill the flush thread
+                pass
+
+    def close(self) -> None:
+        """Flush pending events and stop the background thread. Idempotent."""
+        if self._closed:
+            return
+        self._closed = True
+        self._flush_event.set()
+        try:
+            self.flush()
+        except Exception:
+            pass
+
+
+def create_client(api_key: str, **config: Any) -> Client:
+    return Client(api_key, **config)

azfive_capture-0.1.0/src/azfive_capture/flags.py

@@ -0,0 +1,132 @@
+"""Server-side feature flags: /v1/decide per distinct_id with a TTL cache and
+automatic, deduped ``az.flag_called`` exposure events.
+
+Servers have no session, so exposures dedup on ``(distinct_id, flag, value)``
+in a bounded LRU — the experiment pipeline only counts a person's FIRST
+exposure anyway, so the LRU merely caps event noise, not correctness.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections import OrderedDict
+from typing import Any, Callable
+
+from . import transport
+
+FlagValue = bool | str
+
+DECIDE_CACHE_TTL_S = 60.0
+DECIDE_CACHE_MAX = 10_000
+EXPOSURE_LRU_MAX = 50_000
+
+
+class _LRU:
+    """Tiny thread-safe bounded LRU used for decide caching + exposure dedup."""
+
+    def __init__(self, max_entries: int) -> None:
+        self._data: OrderedDict[str, Any] = OrderedDict()
+        self._max = max_entries
+        self._lock = threading.Lock()
+
+    def get(self, key: str) -> Any | None:
+        with self._lock:
+            if key not in self._data:
+                return None
+            self._data.move_to_end(key)
+            return self._data[key]
+
+    def put(self, key: str, value: Any) -> None:
+        with self._lock:
+            self._data[key] = value
+            self._data.move_to_end(key)
+            while len(self._data) > self._max:
+                self._data.popitem(last=False)
+
+    def contains(self, key: str) -> bool:
+        return self.get(key) is not None
+
+    def remove(self, key: str) -> None:
+        with self._lock:
+            self._data.pop(key, None)
+
+
+class FlagsManager:
+    def __init__(
+        self,
+        *,
+        host: str,
+        api_key: str,
+        project: str,
+        capture: Callable[..., None],
+        cache_ttl_s: float = DECIDE_CACHE_TTL_S,
+        now: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._host = host
+        self._api_key = api_key
+        self._project = project
+        self._capture = capture
+        self._ttl = cache_ttl_s
+        self._now = now
+        self._decide_cache = _LRU(DECIDE_CACHE_MAX)
+        self._exposures = _LRU(EXPOSURE_LRU_MAX)
+
+    # ── decide ────────────────────────────────────────────────────────────────
+
+    def _decide(self, distinct_id: str, person_properties: dict | None) -> dict:
+        # person_properties bypass the cache only when they change the request —
+        # cache key folds them in so overlays don't leak between calls.
+        cache_key = distinct_id if not person_properties else (
+            distinct_id + "|" + repr(sorted(person_properties.items()))
+        )
+        cached = self._decide_cache.get(cache_key)
+        if cached is not None and self._now() - cached["at"] < self._ttl:
+            return cached["doc"]
+        payload: dict = {"distinct_id": distinct_id, "project": self._project}
+        if person_properties:
+            payload["person_properties"] = person_properties
+        doc = transport.post_json(f"{self._host}/api/v1/decide", self._api_key, payload)
+        if doc is None:
+            # Network failure: serve stale if we have it, else empty. Never raise.
+            return cached["doc"] if cached is not None else {"flags": {}, "flagPayloads": {}}
+        self._decide_cache.put(cache_key, {"at": self._now(), "doc": doc})
+        return doc
+
+    def reload_flags(self, distinct_id: str) -> None:
+        """Bust one distinct_id's cached decide response."""
+        self._decide_cache.remove(distinct_id)
+
+    # ── getters ───────────────────────────────────────────────────────────────
+
+    def get_flag(
+        self, distinct_id: str, key: str, person_properties: dict | None = None
+    ) -> FlagValue | None:
+        doc = self._decide(distinct_id, person_properties)
+        value = (doc.get("flags") or {}).get(key)
+        self._report_exposure(distinct_id, key, value)
+        return value
+
+    def is_flag_enabled(
+        self, distinct_id: str, key: str, person_properties: dict | None = None
+    ) -> bool:
+        return bool(self.get_flag(distinct_id, key, person_properties))
+
+    def get_flag_payload(
+        self, distinct_id: str, key: str, person_properties: dict | None = None
+    ) -> Any:
+        # No exposure — payload reads follow a get_flag/is_flag_enabled call.
+        doc = self._decide(distinct_id, person_properties)
+        return (doc.get("flagPayloads") or {}).get(key)
+
+    def _report_exposure(self, distinct_id: str, key: str, value: FlagValue | None) -> None:
+        reported = False if value is None else value
+        dedupe = f"{distinct_id}:{key}:{reported!r}"
+        if self._exposures.contains(dedupe):
+            return
+        self._exposures.put(dedupe, True)
+        self._capture(
+            "az.flag_called",
+            {"$feature_flag": key, "$feature_flag_response": reported},
+            distinct_id=distinct_id,
+        )

azfive_capture-0.1.0/src/azfive_capture/transport.py

@@ -0,0 +1,78 @@
+"""HTTP transport: batch POST with optional gzip, stdlib-only.
+
+Endpoint selection mirrors the reference SDK: public tokens (``azfive_pub_…``)
+use the browser-safe ingest path, anything else the server path.  Delivery is
+best-effort — the client re-queues failed batches; this module never raises.
+"""
+
+from __future__ import annotations
+
+import gzip as _gzip
+import json
+import logging
+import urllib.error
+import urllib.request
+import uuid
+
+logger = logging.getLogger("azfive_capture")
+
+_TIMEOUT_S = 10.0
+
+
+def uuid4() -> str:
+    return str(uuid.uuid4())
+
+
+def ingest_path(api_key: str) -> str:
+    return "/api/v1/events/ingest" if api_key.startswith("azfive_pub_") else "/api/v1/events"
+
+
+def send_batch(
+    events: list[dict],
+    *,
+    host: str,
+    api_key: str,
+    project: str,
+    gzip: bool = False,
+) -> bool:
+    """POST one batch. Returns True when the server accepted the request."""
+    body = json.dumps({"events": events, "project": project}).encode()
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+    }
+    if gzip:
+        body = _gzip.compress(body)
+        headers["Content-Encoding"] = "gzip"
+    req = urllib.request.Request(
+        f"{host}{ingest_path(api_key)}", data=body, headers=headers, method="POST"
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=_TIMEOUT_S) as res:
+            return 200 <= res.status < 300
+    except urllib.error.HTTPError as exc:
+        logger.debug("azfive batch rejected: %s", exc.code)
+        return False
+    except Exception as exc:  # network errors — silent, caller re-queues
+        logger.debug("azfive batch failed: %s", exc)
+        return False
+
+
+def post_json(url: str, api_key: str, payload: dict) -> dict | None:
+    """POST JSON, return the decoded JSON response or None on any failure."""
+    body = json.dumps(payload).encode()
+    req = urllib.request.Request(
+        url,
+        data=body,
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=_TIMEOUT_S) as res:
+            return json.loads(res.read().decode())
+    except Exception as exc:
+        logger.debug("azfive decide failed: %s", exc)
+        return None

azfive_capture-0.1.0/tests/conftest.py

@@ -0,0 +1,104 @@
+import json
+import sys
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+VECTORS_DIR = Path(__file__).parent.parent.parent / "sdk-spec" / "vectors"
+
+
+def load_vectors(name: str) -> dict:
+    return json.loads((VECTORS_DIR / f"{name}.json").read_text())
+
+
+class MockAzFive:
+    """Tiny scriptable AzFive stub: records (path, headers, body) and replays
+    canned responses. ``fail_next`` forces a 500 on the next events POST."""
+
+    def __init__(self) -> None:
+        self.requests: list[dict] = []
+        self.decide_response: dict = load_vectors("decide-fixtures")["response_empty"]
+        self.fail_next = False
+
+        outer = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def do_POST(self):  # noqa: N802
+                length = int(self.headers.get("Content-Length", 0))
+                raw = self.rfile.read(length)
+                if self.headers.get("Content-Encoding") == "gzip":
+                    import gzip
+                    raw = gzip.decompress(raw)
+                body = json.loads(raw) if raw else {}
+                outer.requests.append({
+                    "path": self.path,
+                    "headers": dict(self.headers),
+                    "body": body,
+                })
+                if self.path.endswith("/decide"):
+                    payload = outer.decide_response
+                elif outer.fail_next:
+                    outer.fail_next = False
+                    self.send_response(500)
+                    self.end_headers()
+                    return
+                else:
+                    payload = {"accepted": len(body.get("events", [])), "rejected": 0}
+                data = json.dumps(payload).encode()
+                self.send_response(200)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(data)))
+                self.end_headers()
+                self.wfile.write(data)
+
+            def log_message(self, *a):  # silence
+                pass
+
+        self._server = HTTPServer(("127.0.0.1", 0), Handler)
+        self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
+        self._thread.start()
+
+    @property
+    def host(self) -> str:
+        return f"http://127.0.0.1:{self._server.server_port}"
+
+    def events_batches(self) -> list[list[str]]:
+        return [
+            [e["event"] for e in r["body"].get("events", [])]
+            for r in self.requests
+            if "/events" in r["path"]
+        ]
+
+    def close(self) -> None:
+        self._server.shutdown()
+
+
+@pytest.fixture
+def mock_server():
+    server = MockAzFive()
+    yield server
+    server.close()
+
+
+@pytest.fixture
+def frozen_client(monkeypatch):
+    """A client with frozen clock/uuid/identity per the envelope vectors."""
+    from azfive_capture import client as client_mod
+    from azfive_capture import transport as transport_mod
+
+    envelope = load_vectors("event-envelope")
+    monkeypatch.setattr(client_mod, "_now_iso", lambda: envelope["frozen_timestamp"])
+    monkeypatch.setattr(transport_mod, "uuid4", lambda: "u-1")
+    monkeypatch.setattr(client_mod.transport, "uuid4", lambda: "u-1")
+
+    c = client_mod.Client(
+        "azfive_test_key", host="http://unused.local",
+        disable_decide=True, start_flush_thread=False,
+    )
+    c._distinct_id = "anon-1"
+    c._device_id = "dev-1"
+    return c

azfive_capture-0.1.0/tests/test_batching.py

@@ -0,0 +1,98 @@
+"""Batching semantics — golden vectors + real HTTP against the mock server."""
+
+from conftest import load_vectors
+
+from azfive_capture.client import Client
+
+
+class ScriptedTransport:
+    """Records batches; returns scripted ok/fail per flush call."""
+
+    def __init__(self) -> None:
+        self.batches: list[list[str]] = []
+        self.results: list[bool] = []
+
+    def send(self, batch: list[dict]) -> bool:
+        self.batches.append([e["event"] for e in batch])
+        return self.results.pop(0) if self.results else True
+
+
+def _make_client(config: dict) -> tuple[Client, ScriptedTransport]:
+    c = Client(
+        "azfive_test", host="http://unused.local",
+        batch_size=config.get("batch_size", 10),
+        max_queue_size=config.get("max_queue_size", 1000),
+        disable_decide=True, start_flush_thread=False,
+    )
+    scripted = ScriptedTransport()
+    c._send = scripted.send  # type: ignore[method-assign]
+    return c, scripted
+
+
+def test_batching_vectors():
+    vectors = load_vectors("batching")
+    for case in vectors["cases"]:
+        client, transport = _make_client(case.get("config", {}))
+        for step in case["actions"]:
+            if step.startswith("capture "):
+                client.capture(step.split(" ", 1)[1])
+            elif step == "flush":
+                client.flush()
+            elif step == "flush(ok)":
+                transport.results.append(True)
+                client.flush()
+            elif step == "flush(fail)":
+                transport.results.append(False)
+                client.flush()
+            elif step == "opt_out":
+                client.opt_out_capturing()
+            elif step == "opt_in":
+                client.opt_in_capturing()
+            else:
+                raise AssertionError(f"unknown step {step}")
+        assert transport.batches == case["expected_batches"], case["name"]
+
+
+def test_real_http_delivery(mock_server):
+    client = Client(
+        "azfive_secret_abc", host=mock_server.host,
+        batch_size=2, disable_decide=True, start_flush_thread=False,
+    )
+    client.capture("e1")
+    client.capture("e2")  # triggers flush at batch_size
+    assert mock_server.events_batches() == [["e1", "e2"]]
+    req = mock_server.requests[0]
+    assert req["path"] == "/api/v1/events"  # secret key → server path
+    assert req["headers"]["Authorization"] == "Bearer azfive_secret_abc"
+    assert req["body"]["project"] == "default"
+
+
+def test_public_token_routes_to_ingest_path(mock_server):
+    client = Client(
+        "azfive_pub_abc", host=mock_server.host,
+        batch_size=1, disable_decide=True, start_flush_thread=False,
+    )
+    client.capture("e1")
+    assert mock_server.requests[0]["path"] == "/api/v1/events/ingest"
+
+
+def test_gzip_delivery(mock_server):
+    client = Client(
+        "azfive_secret_abc", host=mock_server.host, gzip=True,
+        batch_size=1, disable_decide=True, start_flush_thread=False,
+    )
+    client.capture("zipped")
+    req = mock_server.requests[0]
+    assert req["headers"].get("Content-Encoding") == "gzip"
+    assert req["body"]["events"][0]["event"] == "zipped"  # decompressed OK
+
+
+def test_close_flushes(mock_server):
+    client = Client(
+        "azfive_secret_abc", host=mock_server.host,
+        batch_size=100, disable_decide=True, start_flush_thread=False,
+    )
+    client.capture("tail")
+    client.close()
+    assert mock_server.events_batches() == [["tail"]]
+    client.close()  # idempotent

azfive_capture-0.1.0/tests/test_envelope.py

@@ -0,0 +1,104 @@
+"""Event envelope + property merge — golden vectors from sdk-spec/vectors/."""
+
+from conftest import load_vectors
+
+from azfive_capture.client import LIB_NAME, LIB_VERSION, merge_properties
+
+
+def _run_action(client, action):
+    method = action["method"]
+    if method == "capture":
+        client.capture(action["event"], action.get("properties") or {})
+    elif method == "identify":
+        client.identify(action["distinct_id"], set=action.get("set"), set_once=action.get("set_once"))
+    elif method == "alias":
+        client.alias(action["alias"])
+    elif method == "people.set":
+        client.people.set(action["properties"])
+    elif method == "people.set_once":
+        client.people.set_once(action["properties"])
+    elif method == "az.flag_called":
+        client.capture(
+            "az.flag_called",
+            {"$feature_flag": action["flag"], "$feature_flag_response": action["response"]},
+        )
+    else:
+        raise AssertionError(f"unknown action {method}")
+
+
+def test_event_envelope_vectors(frozen_client):
+    vectors = load_vectors("event-envelope")
+    ignore = set(vectors["ignore_property_keys"])
+    for case in vectors["cases"]:
+        # Each case assumes a fresh anonymous client.
+        frozen_client._queue.clear()
+        frozen_client._distinct_id = "anon-1"
+        frozen_client._device_id = "dev-1"
+        frozen_client._identified = False
+        frozen_client._super_props = {}
+        for setup in case.get("setup", []):
+            _run_action(frozen_client, setup)
+        frozen_client._queue.clear()  # setup events aren't asserted
+        _run_action(frozen_client, case["action"])
+        assert len(frozen_client._queue) == 1, case["name"]
+        actual = dict(frozen_client._queue[0])
+        expected = case["expected"]
+        actual["properties"] = {
+            k: v for k, v in actual["properties"].items()
+            if k not in ignore or k in expected["properties"]
+        }
+        assert actual == expected, case["name"]
+
+
+def test_lib_stamps_present(frozen_client):
+    frozen_client.capture("e")
+    props = frozen_client._queue[0]["properties"]
+    assert props["$lib"] == LIB_NAME == "azfive-python"
+    assert props["$lib_version"] == LIB_VERSION
+    assert props["$device_type"] == "Server"
+
+
+def test_property_merge_vectors(frozen_client):
+    vectors = load_vectors("property-merge")
+    for case in vectors["cases"]:
+        if "register_sequence" in case:
+            frozen_client._super_props = {}
+            for step in case["register_sequence"]:
+                if step["method"] == "register":
+                    frozen_client.register(step["props"])
+                elif step["method"] == "register_once":
+                    frozen_client.register_once(step["props"])
+                elif step["method"] == "unregister":
+                    frozen_client.unregister(step["key"])
+            assert frozen_client._super_props == case["expected_super"], case["name"]
+        elif "expected_reserved" in case:
+            frozen_client._super_props = dict(case.get("super") or {})
+            frozen_client._queue.clear()
+            frozen_client.capture("e", dict(case.get("event") or {}))
+            props = frozen_client._queue[0]["properties"]
+            assert props["$lib"] == LIB_NAME, case["name"]
+            assert props["$lib_version"] == LIB_VERSION, case["name"]
+            assert props["$device_id"] == "dev-1", case["name"]
+            frozen_client._super_props = {}
+        else:
+            merged = merge_properties(
+                case.get("static") or {}, case.get("session") or {},
+                case.get("super") or {}, case.get("event") or {}, {},
+            )
+            assert merged == case["expected"], case["name"]
+
+
+def test_reset_preserves_optout_and_device_id(frozen_client):
+    frozen_client.register({"team": "core"})
+    frozen_client.identify("ava@example.com")
+    frozen_client.opt_out_capturing()
+    device = frozen_client._device_id
+
+    frozen_client.reset()
+    assert frozen_client.get_distinct_id() != "ava@example.com"
+    assert frozen_client._super_props == {}
+    assert frozen_client.has_opted_out_capturing() is True
+    assert frozen_client._device_id == device
+
+    frozen_client.reset(reset_device_id=True)
+    assert frozen_client._device_id != device or frozen_client._device_id == "u-1"

azfive_capture-0.1.0/tests/test_flags.py

@@ -0,0 +1,135 @@
+"""Flags: decide client, TTL cache, exposure dedup — golden vectors."""
+
+from conftest import load_vectors
+
+from azfive_capture.flags import FlagsManager
+
+
+class FakeClock:
+    def __init__(self) -> None:
+        self.t = 0.0
+
+    def __call__(self) -> float:
+        return self.t
+
+
+def _manager(flags_doc: dict, captured: list, clock: FakeClock | None = None):
+    state = {"doc": {"flags": dict(flags_doc), "flagPayloads": {}}, "calls": 0}
+
+    def capture(event, properties, *, distinct_id):
+        captured.append({"event": event, "properties": properties, "distinct_id": distinct_id})
+
+    mgr = FlagsManager(
+        host="http://unused.local", api_key="k", project="default",
+        capture=capture, now=clock or FakeClock(),
+    )
+
+    def fake_decide(url, api_key, payload):
+        state["calls"] += 1
+        return state["doc"]
+
+    import azfive_capture.flags as flags_mod
+    original = flags_mod.transport.post_json
+    flags_mod.transport.post_json = fake_decide  # patched for the test process
+    mgr._restore = lambda: setattr(flags_mod.transport, "post_json", original)  # type: ignore[attr-defined]
+    return mgr, state
+
+
+def test_exposure_dedup_vectors():
+    vectors = load_vectors("exposure-dedup")
+    for case in vectors["cases"]:
+        captured: list = []
+        mgr, state = _manager(vectors["flags"], captured)
+        try:
+            distinct_id = "user-1"
+            for call in case["calls"]:
+                method = call["method"]
+                if method == "getFlag":
+                    result = mgr.get_flag(distinct_id, call["key"])
+                    if "expected_return" in case and case["expected_return"] is None:
+                        assert result is None, case["name"]
+                elif method == "isFlagEnabled":
+                    result = mgr.is_flag_enabled(distinct_id, call["key"])
+                    if "expect" in call:
+                        assert result is call["expect"], f"{case['name']}: {call['key']}"
+                elif method == "getFlagPayload":
+                    mgr.get_flag_payload(distinct_id, call["key"])
+                elif method == "_update_flag":
+                    state["doc"]["flags"][call["key"]] = call["value"]
+                    mgr.reload_flags(distinct_id)
+                elif method == "_new_scope":
+                    distinct_id = "user-2"  # server dedup scope = distinct_id
+                else:
+                    raise AssertionError(method)
+            if "expected_exposures" in case:
+                actual = [
+                    {"$feature_flag": c["properties"]["$feature_flag"],
+                     "$feature_flag_response": c["properties"]["$feature_flag_response"]}
+                    for c in captured
+                ]
+                assert actual == case["expected_exposures"], case["name"]
+        finally:
+            mgr._restore()  # type: ignore[attr-defined]
+
+
+def test_decide_ttl_cache():
+    clock = FakeClock()
+    captured: list = []
+    mgr, state = _manager({"f": True}, captured, clock)
+    try:
+        mgr.get_flag("u1", "f")
+        mgr.get_flag("u1", "f")
+        assert state["calls"] == 1  # cached
+        clock.t += 61
+        mgr.get_flag("u1", "f")
+        assert state["calls"] == 2  # TTL expired
+        mgr.reload_flags("u1")
+        mgr.get_flag("u1", "f")
+        assert state["calls"] == 3  # busted
+        mgr.get_flag("u2", "f")
+        assert state["calls"] == 4  # per-distinct_id cache
+    finally:
+        mgr._restore()  # type: ignore[attr-defined]
+
+
+def test_decide_request_shape(mock_server):
+    from azfive_capture import Client
+
+    fixtures = load_vectors("decide-fixtures")
+    mock_server.decide_response = fixtures["response_full"]
+    client = Client("azfive_secret_abc", host=mock_server.host, start_flush_thread=False)
+
+    assert client.get_flag("anon-1", "experiment") == "variant-b"
+    assert client.get_flag_payload("anon-1", "experiment") == {"cta": "Try it"}
+    assert client.is_flag_enabled("anon-1", "boolean-off") is False
+
+    decide_reqs = [r for r in mock_server.requests if r["path"].endswith("/decide")]
+    assert decide_reqs[0]["body"] == fixtures["request"]["body"]
+    assert decide_reqs[0]["headers"]["Authorization"] == "Bearer azfive_secret_abc"
+
+    # exposures were captured for getFlag/isFlagEnabled but not payload
+    client.flush()
+    exposure_events = [
+        e for r in mock_server.requests if "/events" in r["path"]
+        for e in r["body"]["events"] if e["event"] == "az.flag_called"
+    ]
+    responses = {(e["properties"]["$feature_flag"], e["properties"]["$feature_flag_response"])
+                 for e in exposure_events}
+    assert responses == {("experiment", "variant-b"), ("boolean-off", False)}
+
+
+def test_decide_failure_returns_stale_or_none():
+    captured: list = []
+    mgr, state = _manager({"f": True}, captured)
+    try:
+        assert mgr.get_flag("u1", "f") is True
+        state["doc"] = None  # network failure → post_json returns None
+
+        def failing(url, api_key, payload):
+            return None
+        import azfive_capture.flags as flags_mod
+        flags_mod.transport.post_json = failing
+        mgr._decide_cache.remove("u1")
+        assert mgr.get_flag("u1", "f") is None  # no stale entry → empty doc
+    finally:
+        mgr._restore()  # type: ignore[attr-defined]