embrasure-analytics 0.1.0__tar.gz

embrasure_analytics-0.1.0/.gitignore

@@ -0,0 +1,78 @@
+# Monorepo-wide ignore rules for local/generated artifacts.
+
+# OS/editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Local migration/deploy artifacts
+artifacts/
+.docker-context/
+tmp/cache-cost-scenarios/
+
+# Root/local env files (keep examples committed)
+.env
+.env.*
+.env_*
+.braintrust.json
+!.env.example
+!.env.*.example
+
+# Node / JS
+**/node_modules/
+**/.next/
+**/out/
+**/.turbo/
+**/.cache/
+**/*.tsbuildinfo
+
+# Rust / Tauri
+**/target/
+**/src-tauri/gen/schemas/
+apps/desktop/src-tauri/resources/runtime/*
+!apps/desktop/src-tauri/resources/runtime/.gitkeep
+
+# Python
+**/__pycache__/
+**/*.py[cod]
+**/.venv/
+**/.pytest_cache/
+**/.mypy_cache/
+**/.ruff_cache/
+**/.coverage
+**/.coverage.*
+**/htmlcov/
+**/dist/
+**/build/
+!apps/web/src/app/api/agent/context-graph/build/
+!apps/web/src/app/api/agent/context-graph/build/route.ts
+**/*.egg-info/
+
+# Vercel
+.vercel
+.gstack/
+.env*.local
+
+# Terraform
+**/.terraform/
+**/.terraform.lock.hcl.local
+**/terraform.tfstate
+infra/aws/lambda/*.zip
+**/terraform.tfstate.*
+**/*.tfplan
+**/*.tfvars
+!**/*.tfvars.example
+
+# Impeccable audit artifacts (local)
+.impeccable/
+
+# Playwright MCP session artifacts (local)
+.playwright-mcp/

embrasure_analytics-0.1.0/LICENSE

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

embrasure_analytics-0.1.0/NOTICE

@@ -0,0 +1,29 @@
+Prior art: PostHog/posthog-python, revision f6c4b05865974d0945499c33d548d1099f9945bb (7.51.0).
+https://github.com/PostHog/posthog-python/tree/f6c4b05865974d0945499c33d548d1099f9945bb
+
+The background batching, bounded queue, immutable enqueue, retry, daemon lifecycle,
+and weak fork/exit callback patterns are adapted from this implementation.
+Embrasure owns its native event contract, receipt validation, and delivery limits.
+The PostHog SDK is a test-only dependency; no PostHog services are contacted.
+
+Copyright (c) 2023 PostHog (part of Hiberly Inc)
+
+Copyright (c) 2013 Segment Inc. friends@segment.com
+
+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.

embrasure_analytics-0.1.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.5
+Name: embrasure-analytics
+Version: 0.1.0
+Summary: Python event collection SDK for Embrasure
+Project-URL: Homepage, https://embrasure.ai
+Project-URL: Repository, https://github.com/EmbrasureAI/embrasure
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: typing-extensions<5,>=4.12
+Description-Content-Type: text/markdown
+
+# Embrasure analytics for Python
+
+A typed Python 3.10+ SDK for the same native collection API used by
+`@embrasure/analytics` and `@embrasure/analytics/server`. One client can serve
+concurrent requests. Identity and groups are explicit on each event.
+
+Install the package:
+
+```sh
+pip install embrasure-analytics==0.1.0
+```
+
+From a source checkout:
+
+```sh
+pip install ./packages/analytics-python
+```
+
+```python
+import os
+from embrasure_analytics import Client
+
+analytics = Client(
+    os.environ["EMBRASURE_ANALYTICS_PROJECT_KEY"],
+    server_key=os.environ["EMBRASURE_ANALYTICS_SERVER_KEY"],
+    host="https://api.embrasure.ai/collect",
+)
+
+analytics.track(
+    "invoice_paid",
+    user_id="user_123",
+    id="invoice_paid:invoice_123",  # Reuse only for retries of this action.
+    properties={"amount": 42, "currency": "USD"},
+    groups={"company": "company_456"},
+)
+analytics.identify(
+    "user_123",
+    anonymous_id="browser_anonymous_id",  # Obtain from your browser integration.
+    traits={"plan": "pro"},
+    set_once={"signup_source": "pricing"},
+)
+analytics.group("company", "company_456", traits={"seats": 5})
+result = analytics.shutdown(timeout=30)
+# Inspect accepted, discarded, dropped, pending; acceptance precedes warehouse visibility.
+```
+
+`track(event, **fields)`, `identify(user_id, **fields)`, and
+`group(group_type, group_key, **fields)` return whether a message was queued.
+This is not a delivery receipt. Invalid messages return `False` and emit a
+count-only diagnostic; invalid client configuration raises `ValueError`.
+
+Common fields are `id`, `timestamp`, `anonymous_id`, `session_id`, `properties`,
+`context`, `traits`, `set_once`, and `groups`. Track and group also accept
+`user_id`. IDs are nonblank strings of at most 200 characters. Track requires a
+user or anonymous ID; identify requires a user ID. Group may omit actor identity.
+Custom event names cannot start with `$`. Unknown fields are rejected.
+
+IDs and timestamps default to a UUID and UTC time. Timestamps accept a
+timezone-aware `datetime` or ISO 8601 string and normalize to UTC. Properties
+must be JSON values with string object keys; NaN, infinity, objects, cycles,
+and excessive nesting are rejected. Serialization snapshots input immediately;
+mutating caller dictionaries afterwards cannot alter queued events or retries.
+Identify and group emit immutable messages. They do not establish a current
+user, session, or company on the client. Trait reconstruction and identity
+resolution happen in the analytics processor.
+
+## Authentication and lifecycle
+
+The public project key belongs in the body. A separate server credential goes
+only in the Authorization header, just like the Node server SDK. `server_key`
+is a required keyword: passing `None` explicitly chooses untrusted public-key
+collection, matching browser/PostHog submissions. Never put a secret in the
+project key. Analytics user IDs are attribution, not authenticated identity.
+
+Keep one client per application process. A daemon worker starts on the first
+valid event. Capture calls do no network I/O. HTTP connections are pooled;
+redirects are not followed, and transport retries do not multiply SDK retries.
+
+- `flush(timeout=10)` requests immediate delivery of work queued when called.
+  It respects backoff and returns pending work after a failed attempt, as Node
+  does. It can also return pending work if the total wait budget expires.
+- `shutdown(timeout=30)` stops new events and drains through retries within one
+  total wait budget. At the deadline, unsent events are counted as dropped.
+  An already admitted HTTP request can finish afterwards and is reported pending.
+  No new requests are admitted after shutdown stops the worker.
+- `destroy()` drops buffered work immediately, matching Node's destroy behavior.
+- A context manager calls shutdown on exit. Normal interpreter exit attempts a
+  two-second drain. SIGKILL, crashes, and platform termination can still lose data.
+- After a process fork, the child gets fresh locks, an empty queue, and a fresh
+  HTTP connection pool. Only the parent delivers its inherited buffered events.
+  Prefer creating clients in worker startup hooks with Gunicorn/preloaded apps.
+
+`FlushResult` is an immutable object with `accepted`, `discarded`, `dropped`, and
+`pending`. Method results report completions during that call; `statistics`
+reports cumulative counts in this process, including earlier background sends
+and local validation drops. Pending includes both queued and in-flight work.
+Concurrent flush results may overlap; use statistics or diagnostics for metrics.
+
+The optional `on_diagnostic(Diagnostic)` callback receives outcome, count, and a
+fixed reason, never event bodies or secrets. Callback exceptions are isolated.
+Callbacks may run on producer or worker threads, so keep them fast and
+thread-safe. Lifecycle calls from a worker callback cannot wait on that worker;
+shutdown/destroy in a callback drop remaining buffered work immediately.
+
+## Delivery contract
+
+Defaults deliberately match the JS/Node SDK:
+
+| Behavior | Limit/default |
+| --- | --- |
+| Queued plus in-flight events | 500 |
+| Flush interval / threshold | 5 seconds / 50 events |
+| Batch size including JSON envelope | 60 KiB, at most 50 events |
+| Event size including collector defaults | 32 KiB UTF-8 |
+| JSON depth / groups | 10 levels / 20 groups |
+| HTTP I/O timeout | 5 seconds per network phase |
+| Delivery attempts | 5 total per event |
+| Retry backoff | Exponential, plus jitter; Retry-After up to 5 minutes |
+
+`flush_at` (1–50), `max_queue_size` (1–500), `flush_interval` (at least 0.1s),
+and `request_timeout` are configurable. Retries cover network errors, 408, 429,
+5xx, and ambiguous/malformed success receipts. Other HTTP errors drop the batch.
+A valid success receipt must name `accepted` or `discarded` and acknowledge the
+exact submitted count. An HTTP 2xx alone does not count as success.
+
+The collector acknowledges native batches with HTTP 202 after sink acceptance;
+that does not prove warehouse processing. Discard mode is reported separately.
+The Flow writer deduplicates on workspace/project/environment/event ID, keeping
+the first stored value. This is best-effort, memory-buffered analytics; use a
+transactional outbox when an event must survive an application crash. There is
+no automatic exception/PII capture, browser persistence, replay, or flag client.
+
+## FastAPI, Django, and jobs
+
+For FastAPI, track normally on the request thread/event loop; offload blocking
+shutdown during application teardown:
+
+```python
+import asyncio
+import os
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from embrasure_analytics import Client
+
+
+@asynccontextmanager
+async def lifespan(app):
+    analytics = Client(
+        os.environ["EMBRASURE_ANALYTICS_PROJECT_KEY"],
+        server_key=os.environ["EMBRASURE_ANALYTICS_SERVER_KEY"],
+    )
+    app.state.analytics = analytics
+    try:
+        yield
+    finally:
+        await asyncio.to_thread(analytics.shutdown, timeout=10)
+
+
+app = FastAPI(lifespan=lifespan)
+# In a route: request.app.state.analytics.track("report_created", user_id=user.id)
+```
+
+For Django, initialize one client in each serving worker, then call
+`analytics.track("report_created", user_id=str(request.user.pk))` after successful
+work. Use the process server's worker-exit hook to call shutdown. Do not keep the
+current request's user on a module global. No framework dependency is installed.
+
+For scripts, jobs, and serverless invocations, use `with Client(...) as analytics`
+or explicitly call `shutdown(timeout=...)` within the platform's remaining time.
+Create a new client after shutdown; a shut-down client cannot be reused. The
+context manager's default drain budget is 30 seconds.
+
+## PostHog prior art and compatibility
+
+Reviewed and adapted from **PostHog Python 7.51.0**, source revision
+[`f6c4b05865974d0945499c33d548d1099f9945bb`](https://github.com/PostHog/posthog-python/tree/f6c4b05865974d0945499c33d548d1099f9945bb):
+
+- `posthog/client.py`: immutable enqueue, explicit lifecycle, weak fork/exit
+  hooks, and protection against waiting on the consumer from callbacks.
+- `posthog/consumer.py`: daemon batching by count/time/bytes, bounded delivery,
+  retry classification, and releasing queue capacity after completion.
+- `posthog/request.py` and `capture_v1.py`: pooled transport, Retry-After parsing,
+  and retry backoff. Embrasure handles retries at one layer and validates receipts.
+- Upstream `test/test_consumer.py`: shutdown admission, queue acknowledgement,
+  payload sizing, callback failures, and retry cases informed our tests.
+
+Upstream defaults allow much larger messages/queues and use a different wire
+format. We retain Embrasure's lower JS/Node limits, native messages and explicit
+receipt outcomes. HTTPX provides transport; PostHog is pinned as a **test-only**
+dependency. No runtime fork, monkey patch, PostHog account, or PostHog service is
+required. Upstream MIT attribution is included in [NOTICE](NOTICE).
+
+The real pinned PostHog Python SDK is also tested against the collector for
+capture, person set/set_once, groups, page events, and gzip. Tests found and
+fixed its requirement for HTTP **200** and its separate `$set_once` event.
+Native clients continue to use `/v1/batch` and HTTP 202. PostHog compatibility
+covers capture, person set/set_once, groups, page events, and gzip with the v0
+capture protocol. Feature flags, AI/error capture, alias, historical import, and
+the v1 capture protocol are outside this integration.
+
+## Verification
+
+The following commands and examples are for the Embrasure monorepo checkout;
+the public package does not include the collector or internal test fixtures.
+
+```sh
+uv sync --project apps/api --frozen --dev
+uv sync --project packages/analytics-python --frozen
+uv run --project packages/analytics-python --frozen pytest -q \
+  -c packages/analytics-python/pyproject.toml packages/analytics-python/tests
+uv run --project packages/analytics-python --frozen ruff check packages/analytics-python
+uv run --project packages/analytics-python --frozen mypy \
+  --config-file packages/analytics-python/pyproject.toml packages/analytics-python/src
+uv build --project packages/analytics-python
+```
+
+CI installs the built wheel and runs the tests on Python 3.10 and 3.14. The
+shared `packages/analytics/tests/native-contract.json` fixture also runs through
+the Node SDK and real collector. Unit tests exercise failures, concurrency,
+limits, lifecycle deadlines and actual POSIX forks. Integration tests exercise
+authenticated native HTTP, public attribution, rejected keys, real PostHog calls,
+and interpreter-exit delivery. A recording sink does not prove warehouse storage.
+
+For the full warehouse path, install the wheel in a clean environment and run
+[examples/warehouse_smoke.py](examples/warehouse_smoke.py) with a configured
+synthetic project and its **actual destination workspace**. The public
+`pk_collection_smoke` key is operator-configured in the internal workspace; it
+cannot select another workspace through SDK fields. The script checks live
+collector health, sends 66 originals, two altered retries and four ordering
+markers, and records the inputs, delivery counts and scoped verification SQL.
+Run that SQL against the destination warehouse through an authorized product
+session/MCP. Save its rows as JSON and verify them:
+
+```sh
+python packages/analytics-python/examples/warehouse_smoke.py \
+  --workspace <configured-smoke-workspace> --manifest /tmp/python-sdk-smoke.json
+python packages/analytics-python/examples/warehouse_smoke.py \
+  --manifest /tmp/python-sdk-smoke.json --verify-rows /tmp/warehouse-rows.json
+```
+
+Verification requires exactly 70 unique persisted rows, original properties
+surviving the changed retries, correct timestamps, identity, group/trait data,
+trust metadata, and Unicode/nested JSON. Read the full result page; acceptance
+alone cannot satisfy this check. No customer events or production configuration
+are changed by the smoke script.
+
+For a complete local run, start a dedicated copy of the private Flow repository's
+`tests/local/compose.yaml` fixture with its Kafka profile and dynamic ports (see
+that repository's `tests/local/README.md`). Then run the checked-in driver:
+
+```sh
+uv run --with ./packages/analytics-python/dist/embrasure_analytics-0.1.0-py3-none-any.whl \
+  packages/analytics-python/examples/local_warehouse_smoke.py \
+  --binary /path/to/embrasure-flow-internal/target/release/embrasure-flow \
+  --kafka 127.0.0.1:<kafka-port> \
+  --catalog-uri http://127.0.0.1:<rest-port> \
+  --s3-endpoint http://127.0.0.1:<minio-port> \
+  --artifacts /tmp/python-sdk-warehouse-new-run
+```
+
+This requires the API's local `.venv` and a new artifact directory. The driver
+uses a unique topic, consumer group and namespace, copies the binary for a
+stable run, uses the production analytics column mapping, and starts only its
+own collector/writer processes. It verifies trusted native events, altered
+retries, SIGKILL/restart with retained state, and five real PostHog messages via
+stock DuckDB `iceberg_scan`. The caller owns starting/stopping the disposable
+Docker services. Local and live end-to-end results are recorded in
+[VALIDATION.md](VALIDATION.md).

embrasure_analytics-0.1.0/README.md

@@ -0,0 +1,268 @@
+# Embrasure analytics for Python
+
+A typed Python 3.10+ SDK for the same native collection API used by
+`@embrasure/analytics` and `@embrasure/analytics/server`. One client can serve
+concurrent requests. Identity and groups are explicit on each event.
+
+Install the package:
+
+```sh
+pip install embrasure-analytics==0.1.0
+```
+
+From a source checkout:
+
+```sh
+pip install ./packages/analytics-python
+```
+
+```python
+import os
+from embrasure_analytics import Client
+
+analytics = Client(
+    os.environ["EMBRASURE_ANALYTICS_PROJECT_KEY"],
+    server_key=os.environ["EMBRASURE_ANALYTICS_SERVER_KEY"],
+    host="https://api.embrasure.ai/collect",
+)
+
+analytics.track(
+    "invoice_paid",
+    user_id="user_123",
+    id="invoice_paid:invoice_123",  # Reuse only for retries of this action.
+    properties={"amount": 42, "currency": "USD"},
+    groups={"company": "company_456"},
+)
+analytics.identify(
+    "user_123",
+    anonymous_id="browser_anonymous_id",  # Obtain from your browser integration.
+    traits={"plan": "pro"},
+    set_once={"signup_source": "pricing"},
+)
+analytics.group("company", "company_456", traits={"seats": 5})
+result = analytics.shutdown(timeout=30)
+# Inspect accepted, discarded, dropped, pending; acceptance precedes warehouse visibility.
+```
+
+`track(event, **fields)`, `identify(user_id, **fields)`, and
+`group(group_type, group_key, **fields)` return whether a message was queued.
+This is not a delivery receipt. Invalid messages return `False` and emit a
+count-only diagnostic; invalid client configuration raises `ValueError`.
+
+Common fields are `id`, `timestamp`, `anonymous_id`, `session_id`, `properties`,
+`context`, `traits`, `set_once`, and `groups`. Track and group also accept
+`user_id`. IDs are nonblank strings of at most 200 characters. Track requires a
+user or anonymous ID; identify requires a user ID. Group may omit actor identity.
+Custom event names cannot start with `$`. Unknown fields are rejected.
+
+IDs and timestamps default to a UUID and UTC time. Timestamps accept a
+timezone-aware `datetime` or ISO 8601 string and normalize to UTC. Properties
+must be JSON values with string object keys; NaN, infinity, objects, cycles,
+and excessive nesting are rejected. Serialization snapshots input immediately;
+mutating caller dictionaries afterwards cannot alter queued events or retries.
+Identify and group emit immutable messages. They do not establish a current
+user, session, or company on the client. Trait reconstruction and identity
+resolution happen in the analytics processor.
+
+## Authentication and lifecycle
+
+The public project key belongs in the body. A separate server credential goes
+only in the Authorization header, just like the Node server SDK. `server_key`
+is a required keyword: passing `None` explicitly chooses untrusted public-key
+collection, matching browser/PostHog submissions. Never put a secret in the
+project key. Analytics user IDs are attribution, not authenticated identity.
+
+Keep one client per application process. A daemon worker starts on the first
+valid event. Capture calls do no network I/O. HTTP connections are pooled;
+redirects are not followed, and transport retries do not multiply SDK retries.
+
+- `flush(timeout=10)` requests immediate delivery of work queued when called.
+  It respects backoff and returns pending work after a failed attempt, as Node
+  does. It can also return pending work if the total wait budget expires.
+- `shutdown(timeout=30)` stops new events and drains through retries within one
+  total wait budget. At the deadline, unsent events are counted as dropped.
+  An already admitted HTTP request can finish afterwards and is reported pending.
+  No new requests are admitted after shutdown stops the worker.
+- `destroy()` drops buffered work immediately, matching Node's destroy behavior.
+- A context manager calls shutdown on exit. Normal interpreter exit attempts a
+  two-second drain. SIGKILL, crashes, and platform termination can still lose data.
+- After a process fork, the child gets fresh locks, an empty queue, and a fresh
+  HTTP connection pool. Only the parent delivers its inherited buffered events.
+  Prefer creating clients in worker startup hooks with Gunicorn/preloaded apps.
+
+`FlushResult` is an immutable object with `accepted`, `discarded`, `dropped`, and
+`pending`. Method results report completions during that call; `statistics`
+reports cumulative counts in this process, including earlier background sends
+and local validation drops. Pending includes both queued and in-flight work.
+Concurrent flush results may overlap; use statistics or diagnostics for metrics.
+
+The optional `on_diagnostic(Diagnostic)` callback receives outcome, count, and a
+fixed reason, never event bodies or secrets. Callback exceptions are isolated.
+Callbacks may run on producer or worker threads, so keep them fast and
+thread-safe. Lifecycle calls from a worker callback cannot wait on that worker;
+shutdown/destroy in a callback drop remaining buffered work immediately.
+
+## Delivery contract
+
+Defaults deliberately match the JS/Node SDK:
+
+| Behavior | Limit/default |
+| --- | --- |
+| Queued plus in-flight events | 500 |
+| Flush interval / threshold | 5 seconds / 50 events |
+| Batch size including JSON envelope | 60 KiB, at most 50 events |
+| Event size including collector defaults | 32 KiB UTF-8 |
+| JSON depth / groups | 10 levels / 20 groups |
+| HTTP I/O timeout | 5 seconds per network phase |
+| Delivery attempts | 5 total per event |
+| Retry backoff | Exponential, plus jitter; Retry-After up to 5 minutes |
+
+`flush_at` (1–50), `max_queue_size` (1–500), `flush_interval` (at least 0.1s),
+and `request_timeout` are configurable. Retries cover network errors, 408, 429,
+5xx, and ambiguous/malformed success receipts. Other HTTP errors drop the batch.
+A valid success receipt must name `accepted` or `discarded` and acknowledge the
+exact submitted count. An HTTP 2xx alone does not count as success.
+
+The collector acknowledges native batches with HTTP 202 after sink acceptance;
+that does not prove warehouse processing. Discard mode is reported separately.
+The Flow writer deduplicates on workspace/project/environment/event ID, keeping
+the first stored value. This is best-effort, memory-buffered analytics; use a
+transactional outbox when an event must survive an application crash. There is
+no automatic exception/PII capture, browser persistence, replay, or flag client.
+
+## FastAPI, Django, and jobs
+
+For FastAPI, track normally on the request thread/event loop; offload blocking
+shutdown during application teardown:
+
+```python
+import asyncio
+import os
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from embrasure_analytics import Client
+
+
+@asynccontextmanager
+async def lifespan(app):
+    analytics = Client(
+        os.environ["EMBRASURE_ANALYTICS_PROJECT_KEY"],
+        server_key=os.environ["EMBRASURE_ANALYTICS_SERVER_KEY"],
+    )
+    app.state.analytics = analytics
+    try:
+        yield
+    finally:
+        await asyncio.to_thread(analytics.shutdown, timeout=10)
+
+
+app = FastAPI(lifespan=lifespan)
+# In a route: request.app.state.analytics.track("report_created", user_id=user.id)
+```
+
+For Django, initialize one client in each serving worker, then call
+`analytics.track("report_created", user_id=str(request.user.pk))` after successful
+work. Use the process server's worker-exit hook to call shutdown. Do not keep the
+current request's user on a module global. No framework dependency is installed.
+
+For scripts, jobs, and serverless invocations, use `with Client(...) as analytics`
+or explicitly call `shutdown(timeout=...)` within the platform's remaining time.
+Create a new client after shutdown; a shut-down client cannot be reused. The
+context manager's default drain budget is 30 seconds.
+
+## PostHog prior art and compatibility
+
+Reviewed and adapted from **PostHog Python 7.51.0**, source revision
+[`f6c4b05865974d0945499c33d548d1099f9945bb`](https://github.com/PostHog/posthog-python/tree/f6c4b05865974d0945499c33d548d1099f9945bb):
+
+- `posthog/client.py`: immutable enqueue, explicit lifecycle, weak fork/exit
+  hooks, and protection against waiting on the consumer from callbacks.
+- `posthog/consumer.py`: daemon batching by count/time/bytes, bounded delivery,
+  retry classification, and releasing queue capacity after completion.
+- `posthog/request.py` and `capture_v1.py`: pooled transport, Retry-After parsing,
+  and retry backoff. Embrasure handles retries at one layer and validates receipts.
+- Upstream `test/test_consumer.py`: shutdown admission, queue acknowledgement,
+  payload sizing, callback failures, and retry cases informed our tests.
+
+Upstream defaults allow much larger messages/queues and use a different wire
+format. We retain Embrasure's lower JS/Node limits, native messages and explicit
+receipt outcomes. HTTPX provides transport; PostHog is pinned as a **test-only**
+dependency. No runtime fork, monkey patch, PostHog account, or PostHog service is
+required. Upstream MIT attribution is included in [NOTICE](NOTICE).
+
+The real pinned PostHog Python SDK is also tested against the collector for
+capture, person set/set_once, groups, page events, and gzip. Tests found and
+fixed its requirement for HTTP **200** and its separate `$set_once` event.
+Native clients continue to use `/v1/batch` and HTTP 202. PostHog compatibility
+covers capture, person set/set_once, groups, page events, and gzip with the v0
+capture protocol. Feature flags, AI/error capture, alias, historical import, and
+the v1 capture protocol are outside this integration.
+
+## Verification
+
+The following commands and examples are for the Embrasure monorepo checkout;
+the public package does not include the collector or internal test fixtures.
+
+```sh
+uv sync --project apps/api --frozen --dev
+uv sync --project packages/analytics-python --frozen
+uv run --project packages/analytics-python --frozen pytest -q \
+  -c packages/analytics-python/pyproject.toml packages/analytics-python/tests
+uv run --project packages/analytics-python --frozen ruff check packages/analytics-python
+uv run --project packages/analytics-python --frozen mypy \
+  --config-file packages/analytics-python/pyproject.toml packages/analytics-python/src
+uv build --project packages/analytics-python
+```
+
+CI installs the built wheel and runs the tests on Python 3.10 and 3.14. The
+shared `packages/analytics/tests/native-contract.json` fixture also runs through
+the Node SDK and real collector. Unit tests exercise failures, concurrency,
+limits, lifecycle deadlines and actual POSIX forks. Integration tests exercise
+authenticated native HTTP, public attribution, rejected keys, real PostHog calls,
+and interpreter-exit delivery. A recording sink does not prove warehouse storage.
+
+For the full warehouse path, install the wheel in a clean environment and run
+[examples/warehouse_smoke.py](examples/warehouse_smoke.py) with a configured
+synthetic project and its **actual destination workspace**. The public
+`pk_collection_smoke` key is operator-configured in the internal workspace; it
+cannot select another workspace through SDK fields. The script checks live
+collector health, sends 66 originals, two altered retries and four ordering
+markers, and records the inputs, delivery counts and scoped verification SQL.
+Run that SQL against the destination warehouse through an authorized product
+session/MCP. Save its rows as JSON and verify them:
+
+```sh
+python packages/analytics-python/examples/warehouse_smoke.py \
+  --workspace <configured-smoke-workspace> --manifest /tmp/python-sdk-smoke.json
+python packages/analytics-python/examples/warehouse_smoke.py \
+  --manifest /tmp/python-sdk-smoke.json --verify-rows /tmp/warehouse-rows.json
+```
+
+Verification requires exactly 70 unique persisted rows, original properties
+surviving the changed retries, correct timestamps, identity, group/trait data,
+trust metadata, and Unicode/nested JSON. Read the full result page; acceptance
+alone cannot satisfy this check. No customer events or production configuration
+are changed by the smoke script.
+
+For a complete local run, start a dedicated copy of the private Flow repository's
+`tests/local/compose.yaml` fixture with its Kafka profile and dynamic ports (see
+that repository's `tests/local/README.md`). Then run the checked-in driver:
+
+```sh
+uv run --with ./packages/analytics-python/dist/embrasure_analytics-0.1.0-py3-none-any.whl \
+  packages/analytics-python/examples/local_warehouse_smoke.py \
+  --binary /path/to/embrasure-flow-internal/target/release/embrasure-flow \
+  --kafka 127.0.0.1:<kafka-port> \
+  --catalog-uri http://127.0.0.1:<rest-port> \
+  --s3-endpoint http://127.0.0.1:<minio-port> \
+  --artifacts /tmp/python-sdk-warehouse-new-run
+```
+
+This requires the API's local `.venv` and a new artifact directory. The driver
+uses a unique topic, consumer group and namespace, copies the binary for a
+stable run, uses the production analytics column mapping, and starts only its
+own collector/writer processes. It verifies trusted native events, altered
+retries, SIGKILL/restart with retained state, and five real PostHog messages via
+stock DuckDB `iceberg_scan`. The caller owns starting/stopping the disposable
+Docker services. Local and live end-to-end results are recorded in
+[VALIDATION.md](VALIDATION.md).

embrasure_analytics-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "embrasure-analytics"
+version = "0.1.0"
+description = "Python event collection SDK for Embrasure"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE", "NOTICE"]
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27,<1", "typing-extensions>=4.12,<5"]
+
+[project.urls]
+Homepage = "https://embrasure.ai"
+Repository = "https://github.com/EmbrasureAI/embrasure"
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/README.md", "/pyproject.toml", "/LICENSE", "/NOTICE"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/embrasure_analytics"]
+
+[dependency-groups]
+dev = ["pytest>=8,<10", "ruff>=0.12,<1", "mypy>=1.15,<2", "posthog==7.51.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["integration: real SDKs through the standalone collection API"]
+
+[tool.ruff]
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true

embrasure_analytics-0.1.0/src/embrasure_analytics/__init__.py

@@ -0,0 +1,7 @@
+"""Stateless server event collection for Embrasure."""
+
+from .client import Client
+from .types import Diagnostic, EventFields, FlushResult, Json, Properties
+
+__version__ = "0.1.0"
+__all__ = ["Client", "Diagnostic", "EventFields", "FlushResult", "Json", "Properties"]

embrasure_analytics-0.1.0/src/embrasure_analytics/client.py

@@ -0,0 +1,456 @@
+"""PostHog-style daemon delivery with Embrasure's native wire/receipt contract.
+
+See NOTICE and README for the pinned upstream implementation and differences.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import math
+import os
+import random
+import threading
+import time
+import weakref
+from collections import deque
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import timezone
+from email.utils import parsedate_to_datetime
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+from typing_extensions import Unpack
+
+from .event import encode, serialize, valid_id
+from .types import Diagnostic, EventFields, FlushResult, IdentifyFields
+
+
+@dataclass
+class _Item:
+    payload: bytes
+    sequence: int
+    queued_at: float
+    attempts: int = 0
+
+
+def _seconds(value: float, minimum: float = 0) -> float:
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, (int, float))
+        or not math.isfinite(value)
+        or value < minimum
+    ):
+        raise ValueError("Invalid timeout or interval")
+    return value
+
+
+def _retry_delay(attempt: int, after: str | None) -> float:
+    delay = 0.0
+    if after:
+        try:
+            delay = float(after)
+        except ValueError:
+            try:
+                date = parsedate_to_datetime(after)
+                if date.tzinfo is None:
+                    date = date.replace(tzinfo=timezone.utc)
+                delay = date.timestamp() - time.time()
+            except (ValueError, TypeError, OverflowError):
+                pass
+    if not math.isfinite(delay):
+        delay = 0.0
+    return float(
+        max(
+            min(300, max(0, delay)),
+            min(30, 2 ** (attempt - 1)) + random.random() * 0.25,
+        )
+    )
+
+
+class Client:
+    """Thread-safe, stateless per event; tracking never waits for network I/O.
+
+    Supply the server key for trusted collection. Explicit ``server_key=None``
+    enables public-key collection, with the same untrusted attribution as the
+    browser/PostHog SDKs. Never substitute a secret for the public project key.
+    """
+
+    def __init__(
+        self,
+        project_key: str,
+        *,
+        server_key: str | None,
+        host: str = "https://api.embrasure.ai/collect",
+        flush_interval: float = 5,
+        flush_at: int = 50,
+        max_queue_size: int = 500,
+        request_timeout: float = 5,
+        on_diagnostic: Callable[[Diagnostic], None] | None = None,
+    ) -> None:
+        parsed = urlsplit(host)
+        if (
+            parsed.scheme not in {"http", "https"}
+            or not parsed.hostname
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.query
+            or parsed.fragment
+            or any(c.isspace() or ord(c) < 32 for c in host)
+        ):
+            raise ValueError(
+                "Use an HTTP(S) host without credentials, query, or fragment"
+            )
+        try:
+            _ = parsed.port
+        except ValueError:
+            raise ValueError("Invalid host port") from None
+        if not valid_id(project_key):
+            raise ValueError("Invalid project key")
+        if server_key is not None and (
+            not isinstance(server_key, str)
+            or not server_key.strip()
+            or any(ord(c) < 33 or ord(c) > 126 for c in server_key)
+        ):
+            raise ValueError("Invalid server key")
+        if type(flush_at) is not int or not 1 <= flush_at <= 50:
+            raise ValueError("flush_at must be between 1 and 50")
+        if type(max_queue_size) is not int or not 1 <= max_queue_size <= 500:
+            raise ValueError("max_queue_size must be between 1 and 500")
+        self._endpoint = host.rstrip("/") + "/v1/batch"
+        self._prefix = b'{"project_key":' + encode(project_key) + b',"events":['
+        self._headers = {
+            "Content-Type": "application/json",
+            "User-Agent": "embrasure-analytics-python/0.1.0",
+        }
+        if server_key is not None:
+            self._headers["Authorization"] = "Bearer " + server_key
+        self._interval = _seconds(flush_interval, 0.1)
+        self._request_timeout = _seconds(request_timeout, 0.001)
+        self._flush_at = flush_at
+        self._capacity = max_queue_size
+        self._callback = on_diagnostic
+        self._accepting = True
+        self._reset_state()
+        # Weak callbacks avoid retaining unused clients for process lifetime.
+        ref = weakref.ref(self)
+
+        def on_exit() -> None:
+            client = ref()
+            if client is not None:
+                client.shutdown(timeout=2)
+
+        def after_fork() -> None:
+            client = ref()
+            if client is not None:
+                client._reset_state()
+
+        self._on_exit = on_exit
+        atexit.register(on_exit)
+        if hasattr(os, "register_at_fork"):
+            os.register_at_fork(after_in_child=after_fork)
+
+    def _reset_state(self) -> None:
+        # Never acquire inherited locks or reuse a parent's queue/HTTP pool.
+        # Only the parent may deliver its buffered events. Workers start lazily.
+        self._condition = threading.Condition()
+        self._queue: deque[_Item] = deque()
+        self._flight: list[_Item] = []
+        self._worker: threading.Thread | None = None
+        self._stopped = not self._accepting
+        self._sequence = self._force_until = 0
+        self._retry_at = 0.0
+        self._counts = [0, 0, 0]  # accepted, discarded, dropped
+
+    def track(self, event: str, **fields: Unpack[EventFields]) -> bool:
+        """Queue a custom event; return False if invalid, closed, or full."""
+        return self._enqueue("track", {**fields, "event": event})
+
+    def identify(self, user_id: str, **fields: Unpack[IdentifyFields]) -> bool:
+        """Emit a user/anonymous link and trait patch; no shared current user."""
+        return self._enqueue("identify", {**fields, "user_id": user_id})
+
+    def group(
+        self, group_type: str, group_key: str, **fields: Unpack[EventFields]
+    ) -> bool:
+        """Emit group traits; pass groups explicitly on subsequent track calls."""
+        return self._enqueue(
+            "group", {**fields, "group_type": group_type, "group_key": group_key}
+        )
+
+    def _diagnostic(self, diagnostic: Diagnostic) -> None:
+        try:
+            if self._callback is not None:
+                self._callback(diagnostic)
+        except Exception:
+            # No payloads, credentials, exception strings, or host logging setup.
+            pass
+
+    def _enqueue(self, kind: str, fields: dict[str, Any]) -> bool:
+        with self._condition:
+            if not self._accepting:
+                return False
+        try:
+            payload = serialize(kind, fields)
+        except (ValueError, TypeError, OverflowError, RecursionError, UnicodeError):
+            with self._condition:
+                self._counts[2] += 1
+            self._diagnostic(Diagnostic("dropped", 1, "invalid_event"))
+            return False
+        diagnostic = None
+        with self._condition:
+            if not self._accepting:
+                return False
+            if len(self._queue) + len(self._flight) >= self._capacity:
+                self._counts[2] += 1
+                diagnostic = Diagnostic("dropped", 1, "queue_full")
+            else:
+                self._sequence += 1
+                self._queue.append(_Item(payload, self._sequence, time.monotonic()))
+                if self._worker is None:
+                    self._worker = threading.Thread(
+                        target=self._run, name="embrasure-analytics", daemon=True
+                    )
+                    try:
+                        self._worker.start()
+                    except RuntimeError:
+                        # Telemetry must not break a request when the process
+                        # cannot allocate another thread.
+                        self._worker = None
+                        self._accepting = False
+                        self._stopped = True
+                        self._counts[2] += len(self._queue)
+                        diagnostic = Diagnostic(
+                            "dropped", len(self._queue), "worker_error"
+                        )
+                        self._queue.clear()
+                self._condition.notify_all()
+        if diagnostic:
+            self._diagnostic(diagnostic)
+            return False
+        return True
+
+    @property
+    def statistics(self) -> FlushResult:
+        """Lifetime counts for this process, including background delivery."""
+        with self._condition:
+            return self._result([0, 0, 0])
+
+    def _result(self, before: list[int]) -> FlushResult:
+        return FlushResult(
+            accepted=self._counts[0] - before[0],
+            discarded=self._counts[1] - before[1],
+            dropped=self._counts[2] - before[2],
+            pending=len(self._queue) + len(self._flight),
+        )
+
+    def flush(self, timeout: float = 10) -> FlushResult:
+        """Attempt current events; respect retry backoff and return pending work.
+
+        As in Node, this does not wait through a scheduled retry. Use shutdown
+        for a bounded drain through retries before process exit.
+        """
+        deadline = time.monotonic() + _seconds(timeout)
+        with self._condition:
+            before = self._counts.copy()
+            target = self._sequence
+            self._force_until = max(self._force_until, target)
+            self._condition.notify_all()
+            while not self._stopped and threading.current_thread() is not self._worker:
+                pending = any(i.sequence <= target for i in self._flight) or (
+                    self._queue and self._queue[0].sequence <= target
+                )
+                if not pending or (
+                    not self._flight and self._retry_at > time.monotonic()
+                ):
+                    break
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    break
+                self._condition.wait(remaining)
+            return self._result(before)
+
+    def shutdown(self, timeout: float = 30) -> FlushResult:
+        """Stop admitting events and drain through retries within a total budget.
+
+        On timeout, unsent events are dropped; an admitted HTTP request may
+        finish afterwards and is reported pending. Inspect the returned counts.
+        """
+        deadline = time.monotonic() + _seconds(timeout)
+        diagnostic = None
+        with self._condition:
+            before = self._counts.copy()
+            self._accepting = False
+            self._force_until = self._sequence
+            self._condition.notify_all()
+            # Lifecycle calls inside a diagnostic must never wait on the worker.
+            while (
+                (self._queue or self._flight)
+                and not self._stopped
+                and threading.current_thread() is not self._worker
+            ):
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    break
+                self._condition.wait(remaining)
+            self._stopped = True
+            if self._queue:
+                count = len(self._queue)
+                self._counts[2] += count
+                self._queue.clear()
+                diagnostic = Diagnostic("dropped", count, "shutdown_timeout")
+            self._condition.notify_all()
+            result = self._result(before)
+        if self._worker is not None and threading.current_thread() is not self._worker:
+            self._worker.join(max(0, deadline - time.monotonic()))
+        atexit.unregister(self._on_exit)
+        if diagnostic:
+            self._diagnostic(diagnostic)
+        return result
+
+    def destroy(self) -> FlushResult:
+        """Immediately stop and drop buffered work, matching Node destroy()."""
+        return self.shutdown(timeout=0)
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.shutdown()
+
+    def _make_http(self) -> httpx.Client:
+        # The SDK owns retries; the HTTPX transport does not retry automatically.
+        return httpx.Client(
+            timeout=self._request_timeout,
+            follow_redirects=False,
+            limits=httpx.Limits(max_connections=1, max_keepalive_connections=1),
+            headers=self._headers,
+        )
+
+    def _send(
+        self, http: httpx.Client, body: bytes, count: int
+    ) -> tuple[str, str | None]:
+        try:
+            with http.stream("POST", self._endpoint, content=body) as response:
+                if 200 <= response.status_code < 300:
+                    content = bytearray()
+                    started = time.monotonic()
+                    for chunk in response.iter_bytes(chunk_size=1024):
+                        content.extend(chunk)
+                        if (
+                            len(content) > 16 * 1024
+                            or time.monotonic() - started > self._request_timeout
+                        ):
+                            return "retry", None
+                    receipt = json.loads(content)
+                    if (
+                        isinstance(receipt, dict)
+                        and receipt.get("status") in ("accepted", "discarded")
+                        and type(receipt.get("received")) is int
+                        and receipt["received"] == count
+                    ):
+                        return str(receipt["status"]), None
+                    return "retry", None
+                if response.status_code in (408, 429) or response.status_code >= 500:
+                    return "retry", response.headers.get("Retry-After")
+                return "rejected", None
+        except (httpx.HTTPError, ValueError, UnicodeError):
+            # Ambiguous receipts retry the immutable original event IDs.
+            return "retry", None
+
+    def _run(self) -> None:
+        try:
+            with self._make_http() as http:
+                while True:
+                    with self._condition:
+                        while True:
+                            if self._stopped or (
+                                not self._accepting and not self._queue
+                            ):
+                                return
+                            if not self._queue:
+                                self._condition.wait()
+                                continue
+                            now = time.monotonic()
+                            due = self._queue[0].queued_at + self._interval
+                            if (
+                                len(self._queue) >= self._flush_at
+                                or self._queue[0].sequence <= self._force_until
+                            ):
+                                due = now
+                            delay = max(due, self._retry_at) - now
+                            if delay <= 0:
+                                break
+                            self._condition.wait(delay)
+                        # Drain the current queue when the threshold/interval fires.
+                        self._force_until = max(self._force_until, self._sequence)
+                        size = len(self._prefix) + 2
+                        batch: list[_Item] = []
+                        while self._queue and len(batch) < self._flush_at:
+                            extra = len(self._queue[0].payload) + bool(batch)
+                            if batch and size + extra > 60 * 1024:
+                                break
+                            item = self._queue.popleft()
+                            item.attempts += 1
+                            batch.append(item)
+                            size += extra
+                        self._flight = batch
+                    body = (
+                        self._prefix + b",".join(item.payload for item in batch) + b"]}"
+                    )
+                    outcome, after = self._send(http, body, len(batch))
+                    diagnostics = []
+                    with self._condition:
+                        self._flight = []
+                        if outcome in ("accepted", "discarded"):
+                            self._counts[0 if outcome == "accepted" else 1] += len(
+                                batch
+                            )
+                            diagnostics.append(
+                                Diagnostic(
+                                    "accepted"
+                                    if outcome == "accepted"
+                                    else "discarded",
+                                    len(batch),
+                                )
+                            )
+                        else:
+                            retry = (
+                                [i for i in batch if i.attempts < 5]
+                                if outcome == "retry" and not self._stopped
+                                else []
+                            )
+                            dropped = len(batch) - len(retry)
+                            if dropped:
+                                self._counts[2] += dropped
+                                reason = (
+                                    "retry_limit"
+                                    if outcome == "retry"
+                                    else "request_rejected"
+                                )
+                                diagnostics.append(
+                                    Diagnostic("dropped", dropped, reason)
+                                )
+                            if retry:
+                                self._queue.extendleft(reversed(retry))
+                                self._retry_at = time.monotonic() + _retry_delay(
+                                    retry[0].attempts, after
+                                )
+                                diagnostics.append(Diagnostic("retry", len(retry)))
+                        self._condition.notify_all()
+                    for diagnostic in diagnostics:
+                        self._diagnostic(diagnostic)
+        except Exception:
+            # Unexpected worker/transport setup failures must be observable and
+            # must never leave flush/shutdown waiting on a dead consumer.
+            with self._condition:
+                count = len(self._queue) + len(self._flight)
+                self._counts[2] += count
+                self._queue.clear()
+                self._flight = []
+                self._accepting = False
+                self._stopped = True
+                self._condition.notify_all()
+            self._diagnostic(Diagnostic("dropped", count, "worker_error"))

embrasure_analytics-0.1.0/src/embrasure_analytics/event.py

@@ -0,0 +1,102 @@
+"""Match the native JS SDK and CollectionEvent validation before enqueueing."""
+
+from __future__ import annotations
+
+import json
+import math
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+
+def valid_id(value: object) -> bool:
+    return isinstance(value, str) and bool(value.strip()) and len(value) <= 200
+
+
+def encode(value: object) -> bytes:
+    return json.dumps(
+        value, ensure_ascii=False, allow_nan=False, separators=(",", ":")
+    ).encode("utf-8")
+
+
+def validate_json(value: object, depth: int = 0) -> None:
+    if depth > 10:
+        raise ValueError("JSON exceeds 10 levels")
+    if value is None or type(value) in (bool, str, int):
+        return
+    if type(value) is float and math.isfinite(value):
+        return
+    if type(value) is list:
+        for item in value:
+            validate_json(item, depth + 1)
+        return
+    if type(value) is dict and all(type(key) is str for key in value):
+        for item in value.values():
+            validate_json(item, depth + 1)
+        return
+    raise ValueError("Expected JSON")
+
+
+def serialize(kind: str, fields: dict[str, Any]) -> bytes:
+    # Include collector defaults when sizing, so a near-limit message isn't
+    # rejected after the server expands its optional fields.
+    event: dict[str, Any] = dict.fromkeys(
+        ("event", "user_id", "anonymous_id", "session_id", "group_type", "group_key")
+    )
+    event.update(
+        {key: {} for key in ("groups", "properties", "context", "traits", "set_once")}
+    )
+    allowed = set(event) | {"id", "timestamp"}
+    if fields.keys() - allowed:
+        raise ValueError("Unknown event fields")
+    event.update(fields)
+    event["type"] = kind
+    event["id"] = fields.get("id", str(uuid4()))
+    timestamp = fields.get("timestamp", datetime.now(timezone.utc))
+    if isinstance(timestamp, str):
+        timestamp = datetime.fromisoformat(
+            timestamp.removesuffix("Z") + ("+00:00" if timestamp.endswith("Z") else "")
+        )
+    if not isinstance(timestamp, datetime) or timestamp.utcoffset() is None:
+        raise ValueError("Expected timezone-aware timestamp")
+    event["timestamp"] = (
+        timestamp.astimezone(timezone.utc)
+        .isoformat(timespec="microseconds")
+        .replace("+00:00", "Z")
+    )
+    if not valid_id(event["id"]):
+        raise ValueError("Invalid event ID")
+    for key in ("user_id", "anonymous_id", "session_id", "group_type", "group_key"):
+        if event[key] is not None and not valid_id(event[key]):
+            raise ValueError("Invalid identity")
+    if kind == "track" and (
+        not valid_id(event["event"]) or event["event"].startswith("$")
+    ):
+        raise ValueError("Invalid event name")
+    if kind != "track" and event["event"] is not None:
+        raise ValueError("Unexpected event name")
+    if kind != "group" and not (event["user_id"] or event["anonymous_id"]):
+        raise ValueError("Missing identity")
+    if kind == "identify" and not event["user_id"]:
+        raise ValueError("Missing user ID")
+    if kind == "group" and not (event["group_type"] and event["group_key"]):
+        raise ValueError("Missing group")
+    if kind != "group" and (
+        event["group_type"] is not None or event["group_key"] is not None
+    ):
+        raise ValueError("Unexpected group fields")
+    for key in ("properties", "context", "traits", "set_once"):
+        if type(event[key]) is not dict:
+            raise ValueError("Expected object")
+        validate_json(event[key])
+    groups = event["groups"]
+    if (
+        type(groups) is not dict
+        or len(groups) > 20
+        or any(not valid_id(k) or not valid_id(v) for k, v in groups.items())
+    ):
+        raise ValueError("Invalid groups")
+    payload = encode(event)
+    if len(payload) > 32 * 1024:
+        raise ValueError("Event exceeds 32 KiB")
+    return payload

embrasure_analytics-0.1.0/src/embrasure_analytics/types.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Literal
+
+from typing_extensions import TypedDict
+
+Json = None | bool | int | float | str | list["Json"] | dict[str, "Json"]
+Properties = dict[str, Json]
+
+
+class IdentifyFields(TypedDict, total=False):
+    id: str
+    timestamp: str | datetime
+    anonymous_id: str
+    session_id: str
+    properties: Properties
+    context: Properties
+    traits: Properties
+    set_once: Properties
+    groups: dict[str, str]
+
+
+class EventFields(IdentifyFields, total=False):
+    user_id: str
+
+
+@dataclass(frozen=True)
+class FlushResult:
+    """Outcomes during this call; pending includes queued and in-flight events."""
+
+    accepted: int = 0
+    discarded: int = 0
+    dropped: int = 0
+    pending: int = 0
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    type: Literal["accepted", "discarded", "dropped", "retry"]
+    count: int
+    reason: str | None = None