Eventing SDK — Python 3.9+

Install: pip install bookcicle-eventing.

from eventing_sdk import EventingClient

events = EventingClient('https://events.example.com/events')
events.track({'name': 'checkout_completed', 'properties': {'product': 'book'}})
result = events.flush()
events.close()

Automatic batching: 25 events, first-event timer of 1 second (maximum age 5 seconds), 8192 UTF-8 bytes including the envelope. Three attempts per flush round with 200/400 ms backoff; retry 429/500/502/503/504 and network failures. Only HTTP 202 acknowledges ingestion. IDs and serialized bytes stay unchanged within a retry round.

Events are persisted before track succeeds. Transient failures stay queued and retry automatically after 1 second; restart resumes pending events. Permanent responses retain events and stop background retries until another track/flush. Use queue inspection and discard to handle poison events. Queue capacity is 1000; overflow rejects the new event without evicting older events. Close stops timers and tries a final flush; failed events remain persisted.

Recursive privacy filtering removes common PII/click identifiers by default. Opting into sensitive properties never permits token/authorization fields. Auth is obtained once per batch, never persisted, and refreshed for the next batch. Use HTTPS with /events, /public or /secure; redirects are never followed.

See the public SDK guide, configuration and scaling guide for configuration, persistence, behavioral guarantees and publishing setup. SDKs are MIT licensed; the ingestion runtime retains its separate commercial license.

Per-event session override (next SDK release)

Each client generates a UUID and stores it in context.sid when sid and context.sid are absent. An explicit sid takes precedence. Stored events keep their session ID across retries and queue recovery. New client instances use a new generated ID. Client-supplied IDs remain untrusted; the service also enforces a shared anonymous quota. See the SDK guide.

Share a client only within one endpoint, verified tenant and authentication identity. Auth is resolved per batch, so different credentials need separate clients/queues. For a server sharing one service identity across users, pass the request's non-secret analytics session ID in each track call. The override affects only that event; it does not change the client's default SID. Keep the same SID and event ID on recovery, and do not use tokens, authentication cookies or personal data as IDs. An authenticated service quota still uses the verified auth-layer identity.

events.track({'name': 'page_view', 'sid': 'opaque-session-a'})
events.track({'name': 'page_view', 'sid': 'opaque-session-b'})

Omit event_id to generate a random UUID before enqueueing, or supply your durable outbox's opaque ID. Explicit IDs must be 1–128 UTF-8 bytes without controls or surrounding whitespace. Invalid IDs reject; they are never silently replaced. Retry attempts within a round reuse identical HTTP bytes. A later recovery round may rebuild its envelope with a new batch ID; queued event IDs and snapshots stay unchanged. See the shared SDK contract for deduplication and retry scope.

Test environments

Set the client configuration environment to test and explicitly configure your isolated test endpoint. All SDKs accept dev, test and prod (default), with identical delivery semantics. Queues are bound to the endpoint, environment and default namespace; conflicting path/database reuse rejects before recovery. Drain nonempty legacy queues with the previous SDK or explicitly migrate verified snapshots before upgrading. See the test environment guide.