Metadata-Version: 2.4
Name: bookcicle-eventing
Version: 2.0.0
Summary: Privacy-conscious Eventing by Bookcicle SDK
Author: Bookcicle
License-Expression: MIT
Project-URL: Repository, https://github.com/bookcicle/bookcicle-eventing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Eventing SDK — Python 3.9+

Install: `pip install bookcicle-eventing`.

```python
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](https://eventing.bookcicle.com/#guides-sdk), [configuration](https://eventing.bookcicle.com/configuration) and [scaling guide](https://eventing.bookcicle.com/scaling) 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](https://eventing.bookcicle.com/#guides-sdk).

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.

```python
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](https://eventing.bookcicle.com/configuration#test-environments).
