everydeck 0.3.0__tar.gz → 0.3.2__tar.gz

{everydeck-0.3.0 → everydeck-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: everydeck
-Version: 0.3.0
+Version: 0.3.2
 Summary: everydeck Python SDK: bounded buffer, background sender, flush on shutdown, reported data gaps
 License-Expression: MIT
 Project-URL: Homepage, https://everydeck.ai
@@ -40,7 +40,7 @@ everydeck.signal("job.created", operation_id)
 - `signal()`, `error()` and `log()` never block and never raise: they enqueue into a bounded in-memory buffer; a background thread sends batches (at most 50 events, 64 KiB, gzip-compressed).
 - Retries only on 429, 5xx, timeout and network errors; `Retry-After` is honoured; final rejections are dropped and counted, never reported as sent.
 - A buffer overflow is reported as a `gap` event, so everydeck shows a known data gap instead of silence.
-- `heartbeat_interval` sends `everydeck.sdk.heartbeat` from the sender thread. Give each component a stable `instance_id` (for example `"api"`, `"cv-worker"`).
+- `heartbeat_interval` sends `everydeck.sdk.heartbeat` from the sender thread. Give each component a stable `instance_id` (for example `"api"`, `"worker"`).
 - `release_key="auto"` derives the version from the deployment commit (`EVERYDECK_RELEASE_KEY`, `GITHUB_SHA`, `VERCEL_GIT_COMMIT_SHA`, `RENDER_GIT_COMMIT`, …) or local git.
 - `everydeck.verify.verify_everydeck_request` checks everydeck's signature on bridge calls.
 - Read bridge (0.3.0): `everydeck.read_route.EverydeckReadBridge(endpoint, key, db)` is the ready-made route. It fetches its read scope from everydeck (`GET <endpoint>/v1/read-scope` with the bridge key) and uses it only with everydeck's signature; no read-scope file, no read role, no views. `db` is the connection the app already has: `PsycopgReadOnly(conninfo)` runs every query in `BEGIN READ ONLY`, `SupabaseReadOnly(client)` reads through the app's Supabase client with `select()` only (GET requests, which PostgREST runs read-only; only tables in schemas the Supabase API exposes).

{everydeck-0.3.0 → everydeck-0.3.2}/README.md

@@ -24,7 +24,7 @@ everydeck.signal("job.created", operation_id)
 - `signal()`, `error()` and `log()` never block and never raise: they enqueue into a bounded in-memory buffer; a background thread sends batches (at most 50 events, 64 KiB, gzip-compressed).
 - Retries only on 429, 5xx, timeout and network errors; `Retry-After` is honoured; final rejections are dropped and counted, never reported as sent.
 - A buffer overflow is reported as a `gap` event, so everydeck shows a known data gap instead of silence.
-- `heartbeat_interval` sends `everydeck.sdk.heartbeat` from the sender thread. Give each component a stable `instance_id` (for example `"api"`, `"cv-worker"`).
+- `heartbeat_interval` sends `everydeck.sdk.heartbeat` from the sender thread. Give each component a stable `instance_id` (for example `"api"`, `"worker"`).
 - `release_key="auto"` derives the version from the deployment commit (`EVERYDECK_RELEASE_KEY`, `GITHUB_SHA`, `VERCEL_GIT_COMMIT_SHA`, `RENDER_GIT_COMMIT`, …) or local git.
 - `everydeck.verify.verify_everydeck_request` checks everydeck's signature on bridge calls.
 - Read bridge (0.3.0): `everydeck.read_route.EverydeckReadBridge(endpoint, key, db)` is the ready-made route. It fetches its read scope from everydeck (`GET <endpoint>/v1/read-scope` with the bridge key) and uses it only with everydeck's signature; no read-scope file, no read role, no views. `db` is the connection the app already has: `PsycopgReadOnly(conninfo)` runs every query in `BEGIN READ ONLY`, `SupabaseReadOnly(client)` reads through the app's Supabase client with `select()` only (GET requests, which PostgREST runs read-only; only tables in schemas the Supabase API exposes).

{everydeck-0.3.0 → everydeck-0.3.2}/everydeck/__init__.py

@@ -1,32 +1,32 @@
-"""everydeck Python SDK (R0, Transportvertrag 1.0-r0).
-
-Zusagen (docs/05, belegt in P2a und tests/):
-- `signal()/error()/log()` blockieren nie und werfen nie: O(1) Enqueue in einen begrenzten Speicherpuffer. Kein Datei- oder Netz-IO im Aufrufer.
-- Ein Sender-Thread überträgt Batches (max. 50 Ereignisse, 64 KiB). Drei getrennte Ergebnisse je Batch:
-  angenommen (202) · erneut versuchen (429, 5xx, Timeout, Netz) · endgültig abgewiesen (400/401/403/409/413/422).
-  Abgewiesene Batches zählen nie als gesendet; 401/403 pausieren den Sender (auth_pause_seconds) und melden eine Warnung.
-- B30 Schnitt D (0.1.1): Batches gehen gzip-komprimiert (`compress=False` schaltet es ab), `Retry-After` bei 429/503 wird befolgt,
-  Wiederholungen mit vollem Zufallsanteil (`full_jitter`); `stats`: batches_compressed, bytes_raw, bytes_sent, retry_after_waits – wie das TypeScript-SDK.
-- B30 Schnitt E (0.1.2): `everydeck.verify.verify_everydeck_request` prüft die Signatur von everydeck an Brücken (5-Minuten-Fenster, request_id einmalig); `ReadBridge` prüft selbst (`signatures="required"`).
-- B33 (0.1.5): `error(..., exc=e)` schickt zu bis zu 5 Frames im Code der App die Code-Zeilen mit (Fundzeile und je 5 davor und danach, je höchstens 200 Zeichen, bereinigt wie Fehlermeldungen); gelesen im Sender-Thread, nie im Aufruf; `Everydeck(..., source_context=False)` schaltet es ab. `error.context_status` sagt, ob Zeilen dabei sind oder warum nicht.
-- B34b (0.1.6): `error(..., response={code, message})` wie im TS-SDK (Code nur als Kennung, Meldung bereinigt, 300 Zeichen); `answer_of(exc)` liest beides aus Attributen der Ausnahme (z. B. postgrest `APIError.code`/`.message`), nie aus ihrem Text.
-- B32 (0.1.4): `signal`, `error` und `log` nehmen `object_type`/`object_ref` wie das TS-SDK (`objectType`/`objectRef`).
-- B31 (0.1.3): `Everydeck.error(..., exc=e)` sendet die Stack-Frames der Ausnahme (`error.frames`, innerste zuerst) – oder fertige `frames=[…]`; `ReadBridge(match=psycopg_match(conn))` liefert die Nachrichten eines Gesprächs auf Abruf (`GET /everydeck/read/messages/{type}/{ref}`).
-- Der Sender-Thread endet nie unbemerkt: jede Ausnahme wird gezählt, gemeldet und die Schleife fortgesetzt.
-- Pufferüberlauf wird als Ereignis `gap` (buffer_overflow) gemeldet: eine *erkennbare* Datenlücke.
-- Optionaler Spool (JSONL, begrenzte Größe) läuft in einem eigenen Thread, der als einziger die Datei anfasst: Schreibvorgänge und
-  Bestätigungen (angenommene/abgewiesene Ereignisse) kommen über zwei begrenzte Warteschlangen im RAM (`max_spool_queue`) und werden im
-  Spool-Thread gemeinsam ausgewertet – eine Bestätigung, die vor dem Schreiben eintrifft, verhindert das Schreiben, statt eine Waise zu
-  hinterlassen. Weder Aufrufer noch Sender halten während Datei-IO eine Sperre. Fehler (voll, nicht beschreibbar) werden gezählt und
-  gemeldet, betreffen aber weder Kundenrequests noch den Sender. Beim Start werden unbeschädigte Spool-Zeilen nachgeliefert (`gap`
-  restart_recovered); beschädigte Zeilen (abgebrochener Schreibvorgang) werden gezählt und verworfen. Ohne Spool bleibt ein SIGKILL unsichtbar.
-  Laufen die Warteschlangen über (Spool-Thread hängt an langsamem Datenträger), werden die ältesten Einträge verworfen und gezählt
-  (`spool_queue_dropped`, `spool_ack_dropped`); Folge einer verworfenen Bestätigung ist höchstens eine erneute Zustellung bereits angenommener
-  Ereignisse nach einem Neustart (everydeck dedupliziert je event_id), nie ein Verlust.
-- Lebenszeichen (R1): mit `heartbeat_interval` sendet der Sender-Thread alle n Sekunden ein Signal `everydeck.sdk.heartbeat`
-  (operation_id `everydeck.sdk:<instance_id>`, Felder instance_id/interval_seconds/pid). Ausbleibende Lebenszeichen sind für everydeck eine
-  Überwachungslücke, kein bewiesener Ausfall der App.
-- Das SDK kennt keine Datenbank von everydeck und entscheidet keine Engine-Urteile.
+"""everydeck Python SDK (transport contract 1.0-r0).
+
+Guarantees:
+- `signal()/error()/log()` never block and never raise: O(1) enqueue into a bounded in-memory buffer. No file or network IO in the caller.
+- A sender thread transmits batches (max. 50 events, 64 KiB). Three separate outcomes per batch:
+  accepted (202) · retry (429, 5xx, timeout, network) · finally rejected (400/401/403/409/413/422).
+  Rejected batches never count as sent; 401/403 pause the sender (auth_pause_seconds) and report a warning.
+- Batches are sent gzip-compressed (`compress=False` turns it off), `Retry-After` on 429/503 is honored,
+  retries use full jitter (`full_jitter`); `stats`: batches_compressed, bytes_raw, bytes_sent, retry_after_waits, as in the TypeScript SDK.
+- `everydeck.verify.verify_everydeck_request` checks everydeck's signature at bridges (5-minute window, request_id used once); `ReadBridge` checks it itself (`signatures="required"`).
+- `error(..., exc=e)` sends the code lines for up to 5 frames in the app's code (the error line and 5 before and after, at most 200 characters each, scrubbed like error messages); read in the sender thread, never in the call; `Everydeck(..., source_context=False)` turns it off. `error.context_status` says whether lines are included or why not.
+- `error(..., response={code, message})` as in the TS SDK (code only as an identifier, message scrubbed, 300 characters); `answer_of(exc)` reads both from attributes of the exception (e.g. postgrest `APIError.code`/`.message`), never from its text.
+- `signal`, `error` and `log` take `object_type`/`object_ref` like the TS SDK (`objectType`/`objectRef`).
+- `Everydeck.error(..., exc=e)` sends the exception's stack frames (`error.frames`, innermost first), or ready-made `frames=[…]`; `ReadBridge(match=psycopg_match(conn))` delivers the messages of one conversation on demand (`GET /everydeck/read/messages/{type}/{ref}`).
+- The sender thread never ends silently: every exception is counted, reported, and the loop continues.
+- Buffer overflow is reported as a `gap` event (buffer_overflow): a *detectable* data gap.
+- An optional spool (JSONL, bounded size) runs in its own thread, which is the only one touching the file: writes and
+  acknowledgements (accepted/rejected events) arrive through two bounded in-memory queues (`max_spool_queue`) and are evaluated
+  together in the spool thread; an acknowledgement that arrives before the write prevents the write instead of leaving an orphan
+  behind. Neither caller nor sender holds a lock during file IO. Errors (full, not writable) are counted and
+  reported but affect neither customer requests nor the sender. On start, intact spool lines are replayed (`gap`
+  restart_recovered); corrupt lines (interrupted write) are counted and discarded. Without a spool a SIGKILL stays invisible.
+  If the queues overflow (spool thread stuck on a slow disk), the oldest entries are discarded and counted
+  (`spool_queue_dropped`, `spool_ack_dropped`); a discarded acknowledgement can at most cause already accepted events to be
+  delivered again after a restart (everydeck deduplicates by event_id), never a loss.
+- Heartbeats: with `heartbeat_interval` the sender thread sends a signal `everydeck.sdk.heartbeat` every n seconds
+  (operation_id `everydeck.sdk:<instance_id>`, fields instance_id/interval_seconds/pid). Missing heartbeats are a
+  monitoring gap for everydeck, not a proven outage of the app.
+- The SDK knows no everydeck database and makes no engine verdicts.
 """
 from __future__ import annotations
 
@@ -51,7 +51,7 @@ from typing import Any, Callable, Literal
 __all__ = ["Everydeck", "AfterCommit", "SCHEMA_VERSION", "BATCH_MAX", "error_class_of", "scrub_text", "answer_of"]
 
 SCHEMA_VERSION = "1.3-r0"
-# B23: Herkunft jedes Ereignisses – ein Server-Schlüssel meldet immer die Plattform `server`
+# origin of every event: a server key always reports the platform `server`
 CLIENT = {"platform": "server", "runtime": "python"}
 BATCH_MAX = 50
 BATCH_MAX_BYTES = 64 * 1024
@@ -70,9 +70,9 @@ _COMMIT_ENV = ("GITHUB_SHA", "VERCEL_GIT_COMMIT_SHA", "RENDER_GIT_COMMIT", "CF_P
 
 
 def resolve_release_key(env: dict[str, str] | None = None, cwd: str | None = None) -> str:
-    """B15/C5: automatische Versionskennung – gleiche Regel wie @everydeck/sdk resolveReleaseKey und everydeck-agent version.
+    """Automatic release key: same rule as @everydeck/sdk resolveReleaseKey and everydeck-agent version.
 
-    EVERYDECK_RELEASE_KEY (außer "auto") > Commit aus CI/Hosting (git:<sha12>) > lokales Git (git:<sha12>[+dirty.<hash8>]) > "unknown".
+    EVERYDECK_RELEASE_KEY (except "auto") > commit from CI/hosting (git:<sha12>) > local Git (git:<sha12>[+dirty.<hash8>]) > "unknown".
     """
     import hashlib
     import re
@@ -113,13 +113,13 @@ def _dumps(v: Any) -> str:
 
 
 def full_jitter(failures: int, cap: float, rnd: Callable[[], float] = random.random) -> float:
-    """B30 Schnitt D: Backoff mit vollem Zufallsanteil („full jitter"): gleichverteilt in [0, min(cap, 0.5 s · 2^n)] – wie das TypeScript-SDK."""
+    """Backoff with full jitter: uniform in [0, min(cap, 0.5 s · 2^n)], as in the TypeScript SDK."""
     ceiling = min(cap, 0.5 * 2 ** max(0, min(6, failures)))
     return rnd() * ceiling
 
 
 def parse_retry_after(value: str | None, now: float | None = None) -> float | None:
-    """`Retry-After` als Sekunden oder HTTP-Datum → Sekunden, begrenzt auf eine Stunde; None, wenn fehlt oder unlesbar."""
+    """`Retry-After` as seconds or HTTP date → seconds, capped at one hour; None when missing or unreadable."""
     if not value:
         return None
     v = value.strip()
@@ -164,7 +164,7 @@ class Everydeck:
         self.credential = credential or ""
         self.release_key = resolve_release_key() if not release_key or release_key == "auto" else release_key
         self.manifest_digest = manifest_digest or ""
-        # B15/C7: Prüflauf der Einrichtung (nur Verifikationsskripte)
+        # setup check run (verification scripts only)
         self.probe_id = probe_id
         self.max_buffer = max_buffer
         self.flush_interval = flush_interval
@@ -175,18 +175,18 @@ class Everydeck:
         self.max_spool_queue = max(1, int(max_spool_queue))
         self.auth_pause_seconds = auth_pause_seconds
         self.max_send_backoff = max_send_backoff
-        # B30 Schnitt D: Batches gzip-komprimiert senden (Standard an); everydeck nimmt Content-Encoding: gzip an
+        # send batches gzip-compressed (on by default); everydeck accepts Content-Encoding: gzip
         self.compress = compress
-        # B33: Code-Zeilen zu den Frames im Code der App (Standard an); Dateien liest der Sender-Thread, zwischengespeichert je Pfad
+        # code lines for frames in the app's code (on by default); the sender thread reads the files, cached per path
         self.source_context = source_context
         self._source_cache: dict[str, list[str] | None] = {}
         self._warn_cb = on_warning or (lambda m: _log.warning(m))
         self.enabled = enabled
-        # B36: fehlt Adresse oder Schlüssel (z. B. nach einem Update mit neuen Variablennamen), schaltet das SDK ab – aber laut, nie still
+        # if address or key is missing (e.g. after an update with new variable names), the SDK turns itself off, loudly, never silently
         if self.enabled and (not self.endpoint or not self.credential or not self.manifest_digest):
             self.enabled = False
             missing = "no endpoint" if not self.endpoint else "no key" if not self.credential else "no manifest digest"
-            self._warn_cb(f"everydeck: disabled: {missing} – nothing is sent to everydeck until the app passes endpoint, key and manifest digest")
+            self._warn_cb(f"everydeck: disabled: {missing}; nothing is sent to everydeck until the app passes endpoint, key and manifest digest")
         self.heartbeat_interval = heartbeat_interval
         self.instance_id = instance_id or f"{socket.gethostname()[:40]}-{os.getpid()}-{uuid.uuid4().hex[:6]}"
         self._next_heartbeat = 0.0
@@ -198,10 +198,10 @@ class Everydeck:
         self._unreported_loss = 0
         self._paused_until = 0.0
         self._consecutive_failures = 0
-        self._spool_q: deque[dict[str, Any]] = deque()          # ausstehende Schreibvorgänge (begrenzt)
-        self._spool_acks: dict[str, None] = {}                  # ausstehende Bestätigungen, geordnet (begrenzt)
-        self._spool_q_lock = threading.Lock()   # nur Warteschlangen (Aufrufer, Sender, Spool-Thread), nie während Datei-IO gehalten
-        self._spool_lock = threading.Lock()     # Datei; nur Spool-Thread (und Wiederherstellung im Konstruktor)
+        self._spool_q: deque[dict[str, Any]] = deque()          # pending writes (bounded)
+        self._spool_acks: dict[str, None] = {}                  # pending acknowledgements, ordered (bounded)
+        self._spool_q_lock = threading.Lock()   # queues only (caller, sender, spool thread), never held during file IO
+        self._spool_lock = threading.Lock()     # file; spool thread only (and recovery in the constructor)
         self._spool_ack_overflow_warned = False
         self._spool_wake = threading.Event()
         self._spool_disabled = False
@@ -212,7 +212,7 @@ class Everydeck:
             "auth_failures": 0, "last_rejection": None, "sender_errors": 0,
             "spool_errors": 0, "spool_corrupt_lines": 0, "spool_dropped": 0, "spool_queue_dropped": 0, "spool_ack_dropped": 0,
             "replayed_from_spool": 0, "spool_disabled": False, "heartbeats": 0,
-            "batches_compressed": 0, "bytes_raw": 0, "bytes_sent": 0, "retry_after_waits": 0,   # B30 Schnitt D
+            "batches_compressed": 0, "bytes_raw": 0, "bytes_sent": 0, "retry_after_waits": 0,
         }
         if not enabled:
             return
@@ -236,18 +236,18 @@ class Everydeck:
 
                 _signal.signal(sig, handler)
 
-    # ---------------- API (nie blockierend, nie werfend) ----------------
+    # ---------------- API (never blocking, never raising) ----------------
     def signal(self, name: str, operation_id: str, *, attempt_id: str | None = None, subject_ref: str | None = None,
                account_ref: str | None = None, fields: dict[str, Any] | None = None, request_id: str | None = None,
                business_key: str | None = None, object_type: str | None = None, object_ref: str | None = None) -> str | None:
-        """B32 (0.1.4): `object_type`/`object_ref` nennen das Objekt des Ergebnisses (wie `objectType`/`objectRef` im TS-SDK)."""
+        """`object_type`/`object_ref` name the object of the outcome (like `objectType`/`objectRef` in the TS SDK)."""
         return self._enq({"kind": "signal", "name": name, "operation_id": str(operation_id),
                           **_opt(attempt_id=attempt_id, subject_ref=subject_ref, account_ref=account_ref, fields=fields,
                                  request_id=request_id, business_key=business_key, object_type=object_type, object_ref=object_ref)})
 
     def heartbeat(self, interval_seconds: float, *, job: str | None = None) -> str | None:
-        """Lebenszeichen auf Abruf. Mit `job` (1.9-r0, `jobs[].id` im Manifest): dieser Job ist gelaufen – am Ende jedes erfolgreichen Laufs
-        senden; everydeck meldet einen Job, der zwei Takte schweigt. Ohne `job`: diese Prozessinstanz läuft (wie `heartbeat_interval`)."""
+        """Heartbeat on demand. With `job` (1.9-r0, `jobs[].id` in the manifest): this job has run; send it at the end of every successful run;
+        everydeck reports a job that stays silent for two intervals. Without `job`: this process instance is running (like `heartbeat_interval`)."""
         import re as _re
         if job is not None and not _re.fullmatch(r"[a-z][a-z0-9_.-]{0,63}", job):
             _log.warning("everydeck: heartbeat job id rejected: %r", job)
@@ -262,12 +262,12 @@ class Everydeck:
               fields: dict[str, Any] | None = None, http: dict[str, Any] | None = None, request_id: str | None = None,
               frames: list[dict[str, Any]] | None = None, exc: BaseException | None = None, object_type: str | None = None,
               object_ref: str | None = None, response: dict[str, Any] | None = None) -> str | None:
-        """B31: mit `exc` (die abgefangene Ausnahme) bildet das SDK die Stack-Frames selbst – innerste zuerst, höchstens 20,
-        Datei als die letzten zwei Pfadteile wie im Browser-SDK; `frames` übergibt sie fertig ({function, file?, line?})."""
+        """With `exc` (the caught exception) the SDK builds the stack frames itself: innermost first, at most 20,
+        file as the last two path parts as in the browser SDK; `frames` passes them ready-made ({function, file?, line?})."""
         err: dict[str, Any] = {"class": error_class}
         if message:
             err["message"] = str(message)[:1024]
-        # 1.4-r0 (B33b, B34b): Fehlercode und Meldung aus der Antwort, die die App bekam – wie im TS-SDK (Code nur als Kennung, Meldung bereinigt, 300 Zeichen)
+        # 1.4-r0: error code and message from the response the app received, as in the TS SDK (code only as an identifier, message scrubbed, 300 characters)
         if response:
             ans: dict[str, Any] = {}
             code = response.get("code"); msg = response.get("message")
@@ -279,7 +279,7 @@ class Everydeck:
                 err["response"] = ans
         fr = frames if frames is not None else (_frames_of(exc) if exc is not None else None)
         if fr:
-            keep_abs = frames is None and self.source_context   # der volle Pfad bleibt nur bis zum Sender-Thread (Code-Zeilen), er wird nie gesendet
+            keep_abs = frames is None and self.source_context   # the full path only lives until the sender thread (code lines); it is never sent
             err["frames"] = [{"function": str(f.get("function") or "anonymous")[:128], **({"file": str(f["file"])[:240]} if f.get("file") else {}), **({"line": int(f["line"])} if f.get("line") else {}),
                               **({"in_app": bool(f["in_app"])} if isinstance(f.get("in_app"), bool) else {}), **({"_abs": f["_abs"]} if keep_abs and f.get("_abs") else {})} for f in fr[:20]]
             if not self.source_context:
@@ -296,8 +296,8 @@ class Everydeck:
     def identify(self, subject_ref: str, *, account_ref: str | None = None, display_name: str | None = None,
                  email: str | None = None, login_method: str | None = None, provider_user_id: str | None = None,
                  org_name: str | None = None) -> str | None:
-        """Identitätsquelle (Manifest 1.1 `people`): freigegebene Stammdaten einer Person. everydeck speichert nur die im freigegebenen
-        Manifest genannten Felder; alle anderen werden verworfen und gezählt. Kein Vorgang, keine Regel. Nur serverseitig sinnvoll."""
+        """Identity source (manifest 1.1 `people`): approved master data of a person. everydeck stores only the fields named in the approved
+        manifest; all others are discarded and counted. No operation, no rule. Only meaningful on the server side."""
         fields: dict[str, Any] = {k: str(v)[:256] for k, v in {"display_name": display_name, "email": email, "login_method": login_method,
                                                               "provider_user_id": provider_user_id, "org_name": org_name}.items() if v is not None}
         self.stats["identities"] = self.stats.get("identities", 0) + 1
@@ -310,7 +310,7 @@ class Everydeck:
                           **_opt(fields=fields, operation_id=operation_id, request_id=request_id, object_type=object_type, object_ref=object_ref)})
 
     def flush(self, timeout: float | None = None) -> bool:
-        """Wartet, bis der Puffer geleert ist. False bei Ablauf des Budgets (z. B. everydeck nicht erreichbar)."""
+        """Waits until the buffer is empty. False when the budget runs out (e.g. everydeck not reachable)."""
         if not self.enabled:
             return True
         deadline = None if timeout is None else time.monotonic() + timeout
@@ -321,7 +321,7 @@ class Everydeck:
                 return True
             if deadline is not None and time.monotonic() >= deadline:
                 return False
-            self._paused_until = 0.0  # ein expliziter Flush hebt die Auth-Pause auf (ein Versuch)
+            self._paused_until = 0.0  # an explicit flush lifts the auth pause (one attempt)
             self._wake.set()
             time.sleep(0.02)
 
@@ -336,7 +336,7 @@ class Everydeck:
         self._spool_wake.set()
         st = getattr(self, "_st", None)
         if st is not None and st is not threading.current_thread():
-            st.join(max(0.0, deadline - time.monotonic()))  # ausstehende Spool-Bestätigungen noch anwenden (begrenzt)
+            st.join(max(0.0, deadline - time.monotonic()))  # still apply pending spool acknowledgements (bounded)
         return ok
 
     # ---------------- Enqueue ----------------
@@ -354,8 +354,8 @@ class Everydeck:
             spool = bool(self.spool_path) and not self._spool_disabled
             spool_dropped = 0
             if spool:
-                # Reihenfolge ist Absicht: erst Schreibauftrag, dann Sendepuffer. Der Sender kann ein Ereignis erst nach diesem
-                # Schritt sehen; der Spool-Thread sieht deshalb eine Bestätigung nie ohne den zugehörigen Schreibauftrag.
+                # The order is intentional: write job first, then send buffer. The sender can only see an event after this
+                # step; the spool thread therefore never sees an acknowledgement without its write job.
                 with self._spool_q_lock:
                     if len(self._spool_q) >= self.max_spool_queue:
                         self._spool_q.popleft()
@@ -375,11 +375,11 @@ class Everydeck:
             if wake:
                 self._wake.set()
             return ev["event_id"]
-        except Exception as e:  # Kundenrequest darf nie scheitern
+        except Exception as e:  # a customer request must never fail
             self._warn(f"everydeck: enqueue failed: {e!r}")
             return None
 
-    # ---------------- Sender-Thread ----------------
+    # ---------------- Sender thread ----------------
     def _run(self) -> None:
         while True:
             try:
@@ -390,13 +390,13 @@ class Everydeck:
                     self._send_pending()
                 if self._stop.is_set() and not self._q:
                     break
-            except Exception as e:  # Thread endet nie unbemerkt
+            except Exception as e:  # the thread never ends silently
                 self.stats["sender_errors"] += 1
                 self._warn(f"everydeck: sender error (continuing): {e!r}")
                 time.sleep(full_jitter(self._consecutive_failures, self.max_send_backoff))
 
     def _maybe_heartbeat(self) -> None:
-        """Lebenszeichen im Sender-Thread; läuft über denselben Puffer wie alle Ereignisse (kein Sonderweg, keine Garantie)."""
+        """Heartbeat in the sender thread; goes through the same buffer as all events (no special path, no guarantee)."""
         if not self.heartbeat_interval or self._stop.is_set():
             return
         now = time.monotonic()
@@ -438,8 +438,8 @@ class Everydeck:
         return self._source_cache.get(path)
 
     def _with_source_context(self, ev: dict[str, Any]) -> dict[str, Any]:
-        """B33: Code-Zeilen zu höchstens 5 Frames im Code der App; das Ereignis bleibt unter EVENT_MAX_BYTES (was nicht passt: partial).
-        Der volle Pfad (`_abs`) verlässt das SDK nie. Kopie – das Original im Puffer und im Spool bleibt unverändert."""
+        """Code lines for at most 5 frames in the app's code; the event stays below EVENT_MAX_BYTES (what does not fit: partial).
+        The full path (`_abs`) never leaves the SDK. Works on a copy; the original in the buffer and in the spool stays unchanged."""
         err = ev.get("error") if isinstance(ev.get("error"), dict) else None
         if not err or not err.get("frames"):
             return ev
@@ -484,7 +484,7 @@ class Everydeck:
                     return
                 items = self._take_batch()
                 self._inflight = True
-            items = [self._with_source_context(it) for it in items]   # B33: Datei-IO außerhalb der Sperre, auf Kopien (der Spool-Thread liest die Originale)
+            items = [self._with_source_context(it) for it in items]   # file IO outside the lock, on copies (the spool thread reads the originals)
             try:
                 outcome, detail = self._post(items)
             except Exception as e:
@@ -494,7 +494,7 @@ class Everydeck:
             ack: set[str] | None = None
             warn: str | None = None
             stop_after = False
-            with self._lock:   # nur Zähler und Zustand; Datei-IO und Callbacks laufen außerhalb dieser Sperre
+            with self._lock:   # counters and state only; file IO and callbacks run outside this lock
                 if outcome == "accepted":
                     self.stats["accepted"] += len(items)
                     self.stats["batches_accepted"] += 1
@@ -504,7 +504,7 @@ class Everydeck:
                     self.stats["batches_rejected"] += 1
                     self.stats["dropped_rejected"] += len(items)
                     self.stats["last_rejection"] = detail
-                    ack = {i["event_id"] for i in items}  # kein erneuter Versuch, auch nicht nach Neustart
+                    ack = {i["event_id"] for i in items}  # no retry, not even after a restart
                     code = int(detail.get("status", 0)) if isinstance(detail, dict) else 0
                     if code in _AUTH:
                         self.stats["auth_failures"] += 1
@@ -518,7 +518,7 @@ class Everydeck:
                     self.stats["retries"] += 1
                     self._consecutive_failures += 1
                     self._requeue(items)
-                    # B30 Schnitt D: Retry-After von everydeck (429 Budget/Kontingent, 503 Schutz) wird befolgt, sonst Backoff mit vollem Zufallsanteil
+                    # Retry-After from everydeck (429 budget/quota, 503 protection) is honored, otherwise backoff with full jitter
                     retry_after = detail.get("retry_after") if isinstance(detail, dict) else None
                     if retry_after is not None:
                         self.stats["retry_after_waits"] += 1
@@ -527,7 +527,7 @@ class Everydeck:
                         self._paused_until = time.monotonic() + full_jitter(self._consecutive_failures, self.max_send_backoff)
                     stop_after = True
             if ack:
-                self._spool_enqueue_ack(ack)   # vor dem Ende von inflight: flush() sieht erst danach „leer“, close() wartet auf den Spool
+                self._spool_enqueue_ack(ack)   # before inflight ends: flush() only sees "empty" afterwards, close() waits for the spool
             with self._lock:
                 self._inflight = False
             if warn:
@@ -536,12 +536,12 @@ class Everydeck:
                 return
 
     def _post(self, items: list[dict[str, Any]]) -> tuple[Outcome, Any]:
-        """Genau ein Zustellversuch. Wiederholungen steuert der Sender (Backoff bis max_send_backoff)."""
+        """Exactly one delivery attempt. The sender controls retries (backoff up to max_send_backoff)."""
         body = _dumps({"schema_version": SCHEMA_VERSION, "batch_id": str(uuid.uuid4()), "release_key": self.release_key,
                        "manifest_digest": self.manifest_digest, **({"probe_id": self.probe_id} if self.probe_id else {}), "events": items}).encode()
         headers = {"Content-Type": "application/json", "Authorization": "Bearer " + self.credential}
         self.stats["bytes_raw"] += len(body)
-        if self.compress:   # B30 Schnitt D
+        if self.compress:
             body = gzip.compress(body, compresslevel=6, mtime=0)
             headers["Content-Encoding"] = "gzip"
             self.stats["batches_compressed"] += 1
@@ -563,9 +563,9 @@ class Everydeck:
         except Exception as e:
             return "retry", {"error": repr(e)[:200]}
 
-    # ---------------- Spool-Thread (dauerhafter Hinweis) ----------------
+    # ---------------- Spool thread (durable record) ----------------
     def _spool_open(self, mode: str):
-        return open(self.spool_path, mode, encoding="utf-8")  # separat, damit Tests Fehler injizieren können
+        return open(self.spool_path, mode, encoding="utf-8")  # separate so tests can inject errors
 
     def _spool_run(self) -> None:
         while True:
@@ -583,7 +583,7 @@ class Everydeck:
                 self._spool_fail(e)
 
     def _spool_enqueue_ack(self, ids: set[str]) -> None:
-        """Vom Sender: Ereignisse sind endgültig erledigt (angenommen oder abgewiesen). Nur Warteschlange, kein Datei-IO."""
+        """From the sender: events are finally done (accepted or rejected). Queue only, no file IO."""
         if not self.spool_path or self._spool_disabled:
             return
         over = 0
@@ -592,7 +592,7 @@ class Everydeck:
                 self._spool_acks[i] = None
             over = len(self._spool_acks) - self.max_spool_queue
             if over > 0:
-                for k in list(self._spool_acks)[:over]:   # älteste zuerst; die Schreibaufträge dazu sind ebenfalls die ältesten
+                for k in list(self._spool_acks)[:over]:   # oldest first; their write jobs are the oldest as well
                     del self._spool_acks[k]
                 self.stats["spool_ack_dropped"] += over
         if over > 0 and not self._spool_ack_overflow_warned:
@@ -601,7 +601,7 @@ class Everydeck:
         self._spool_wake.set()
 
     def _spool_cycle(self) -> None:
-        """Ein Durchlauf: Schreibaufträge und Bestätigungen gemeinsam betrachten. Bestätigt und noch nicht geschrieben → gar nicht schreiben."""
+        """One pass: look at write jobs and acknowledgements together. Acknowledged and not yet written → do not write at all."""
         with self._spool_q_lock:
             writes = list(self._spool_q)
             self._spool_q.clear()
@@ -617,12 +617,12 @@ class Everydeck:
         if writes:
             self._spool_write(writes)
         if acks:
-            self._spool_ack(acks)   # Bestätigungen ohne Zeile (Nachlieferungs-/Lückenereignisse, verworfene Schreibaufträge) verfallen hier
+            self._spool_ack(acks)   # acknowledgements without a line (replay/gap events, discarded write jobs) expire here
 
     def _spool_write(self, batch: list[dict[str, Any]]) -> None:
         with self._spool_lock:
-            # Bis zum Limit auffüllen (ganze Zeilen), den Rest verwerfen und den Spool schließen – unabhängig davon, wie viele
-            # Ereignisse ein Zyklus zufällig einsammelt.
+            # Fill up to the limit (whole lines), discard the rest and close the spool, regardless of how many
+            # events a cycle happens to collect.
             lines: list[str] = []
             size = 0
             dropped = 0
@@ -659,7 +659,7 @@ class Everydeck:
             self._warn(f"everydeck: spool unavailable ({e!r}); spool disabled, delivery continues in memory only")
 
     def _spool_ack(self, ids: set[str]) -> None:
-        """Nur Spool-Thread: bestätigte Zeilen entfernen (atomares Zurückschreiben)."""
+        """Spool thread only: remove acknowledged lines (atomic rewrite)."""
         if not self.spool_path or self._spool_disabled:
             return
         try:
@@ -674,7 +674,7 @@ class Everydeck:
                     f.writelines(keep)
                     f.flush()
                     os.fsync(f.fileno())
-                os.replace(tmp, self.spool_path)  # atomar: kein halb geschriebener Spool
+                os.replace(tmp, self.spool_path)  # atomic: no half-written spool
                 self._spool_bytes = sum(len(l.encode("utf-8")) for l in keep)
         except Exception as e:
             self._spool_fail(e)
@@ -705,7 +705,7 @@ class Everydeck:
                 self.stats["replayed_from_spool"] += 1
             self._q.append({"event_id": str(uuid.uuid4()), "occurred_at": _now(), "kind": "gap", "name": "everydeck.sdk.recovered",
                             "gap": {"cause": "restart_recovered", "replayed": len(replay), "dropped": dropped}})
-            with self._spool_lock:  # Spool auf die nachgelieferten, gültigen Zeilen zurückschreiben
+            with self._spool_lock:  # rewrite the spool to the replayed, valid lines
                 tmp = self.spool_path + ".tmp"
                 with open(tmp, "w", encoding="utf-8") as f:
                     f.writelines(_dumps(ev) + "\n" for ev in replay)
@@ -731,7 +731,7 @@ def _safe_id(line: str) -> str | None:
 
 
 class AfterCommit:
-    """Ergebnisbeleg = Commit (P1-Befund): Signale erst nach erfolgreichem Commit senden."""
+    """Outcome evidence = commit: send signals only after a successful commit."""
 
     def __init__(self) -> None:
         self._fns: list[Callable[[], Any]] = []
@@ -755,8 +755,8 @@ _ANSWER_CODE = re.compile(r"^[A-Za-z0-9_.:-]{1,64}$")
 
 
 def answer_of(exc: BaseException | None) -> dict[str, Any] | None:
-    """B34b: Fehlercode und Meldung, die eine Ausnahme als eigene Attribute trägt (z. B. postgrest APIError: `code`, `message`) – für
-    `error(..., response=answer_of(exc))`. Nur Attribute, kein Lesen im Text der Ausnahme; ohne beide Attribute None."""
+    """Error code and message an exception carries as its own attributes (e.g. postgrest APIError: `code`, `message`), for
+    `error(..., response=answer_of(exc))`. Attributes only, no parsing of the exception text; None without both attributes."""
     if exc is None:
         return None
     code = getattr(exc, "code", None); msg = getattr(exc, "message", None)
@@ -765,7 +765,7 @@ def answer_of(exc: BaseException | None) -> dict[str, Any] | None:
 
 
 def error_class_of(exc: BaseException | type | str) -> str:
-    """B31: stabile Fehlerklasse aus dem Namen einer Ausnahme – Abkürzungen bleiben zusammen: APIError → api_error, HTTPException → http_exception, TypeError → type_error."""
+    """Stable error class from an exception name; acronyms stay together: APIError → api_error, HTTPException → http_exception, TypeError → type_error."""
     import re as _re
     name = exc if isinstance(exc, str) else (exc.__name__ if isinstance(exc, type) else type(exc).__name__)
     s = _re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", name); s = _re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s)
@@ -775,7 +775,7 @@ def error_class_of(exc: BaseException | type | str) -> str:
 
 
 def _library_roots() -> tuple[str, ...]:
-    """Standardbibliothek und installierte Pakete – kein Code der App (B33)"""
+    """Standard library and installed packages: not the app's code"""
     import sysconfig
     roots = {sysconfig.get_paths().get(k) for k in ("stdlib", "platstdlib", "purelib", "platlib")}
     return tuple(os.path.realpath(r) + os.sep for r in roots if r)
@@ -796,8 +796,8 @@ def _in_app(path: str) -> bool:
 
 
 def _frames_of(exc: BaseException) -> list[dict[str, Any]]:
-    """Stack-Frames einer Ausnahme, innerste zuerst (wie ein JS-Stack), Datei = die letzten zwei Pfadteile; `in_app` und der volle Pfad
-    (`_abs`, nur intern für die Code-Zeilen, B33)"""
+    """Stack frames of an exception, innermost first (like a JS stack), file = the last two path parts; `in_app` and the full path
+    (`_abs`, internal only, for the code lines)"""
     import traceback
     out: list[dict[str, Any]] = []
     for fs in reversed(traceback.extract_tb(exc.__traceback__)):
@@ -808,7 +808,7 @@ def _frames_of(exc: BaseException) -> list[dict[str, Any]]:
     return out
 
 
-# ── B33: Code-Zeilen und Bereinigung – dieselbe Regel wie @everydeck/sdk (TS) und everydeck (packages/contracts scrubText); die Paritätsprüfung vergleicht sie ──
+# ── Code lines and scrubbing: the same rule as @everydeck/sdk (TS) and everydeck's scrubText; a parity check compares them ──
 CONTEXT_FRAMES = 5
 CONTEXT_LINES = 5
 CONTEXT_LINE_MAX = 200
@@ -827,7 +827,7 @@ _EMAIL = re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")
 
 
 def scrub_text(text: str) -> str:
-    """Geheimnisse, Bearer-Token und E-Mail-Adressen entfernen (Fehlermeldung oder Code-Zeile)"""
+    """Remove secrets, bearer tokens and e-mail addresses (error message or code line)"""
     out = _BEARER.sub("Bearer [redacted]", str(text))
     for rx in _SECRET_PATTERNS:
         out = rx.sub("[redacted]", out)
@@ -836,7 +836,7 @@ def scrub_text(text: str) -> str:
 
 
 def _context_of(lines: list[str], line: int) -> dict[str, Any] | None:
-    """Fundzeile und je CONTEXT_LINES davor und danach; None, wenn die Zeile nicht in der Datei liegt (nichts raten)"""
+    """The error line and CONTEXT_LINES before and after; None when the line is not in the file (no guessing)"""
     if line < 1 or line > len(lines):
         return None
     cut = lambda x: scrub_text(x[:CONTEXT_LINE_MAX])[:CONTEXT_LINE_MAX]

{everydeck-0.3.0 → everydeck-0.3.2}/everydeck/read_bridge.py

@@ -1,8 +1,8 @@
-"""Die allgemeine Lese-Brücke (B29 Abnahme, docs/04 „Lese-Bridge“) – Python-Fassung des TypeScript-SDKs (read-bridge.ts), gleiches Verhalten.
+"""The general read bridge: Python version of the TypeScript SDK (read-bridge.ts), same behavior.
 
-Ein Endpunkt je deklarierter Tabelle, nur deklarierte Spalten, mit Cursor. Der Agent schreibt keine Brücke je App: er holt den Lese-Umfang
-(`everydeck/everydeck-read-scope.json`, aus dem Befund abgeleitet) und gibt eine Funktion `rows(table, columns, keys, after, limit)` mit, die Zeilen aus
-der Datenbank der App liest – über eine eigene Leserolle (nur SELECT). `psycopg_rows(conn)` ist die fertige Fassung für psycopg (2 oder 3).
+One endpoint per declared table, only declared columns, with a cursor. The agent writes no bridge per app: it takes the read scope
+(`everydeck/everydeck-read-scope.json`, derived from the app map) and passes a function `rows(table, columns, keys, after, limit)` that reads rows from
+the app's database through a dedicated reader role (SELECT only). `psycopg_rows(conn)` is the ready-made version for psycopg (2 or 3).
 
     bridge = ReadBridge(scope=json.load(open("everydeck/everydeck-read-scope.json")), token=os.environ["EVERYDECK_READ_BRIDGE_TOKEN"], rows=psycopg_rows(conn))
     # FastAPI:  @app.api_route("/everydeck/read/{rest:path}", methods=["GET", "POST", "PUT", "PATCH", "DELETE"])
@@ -10,9 +10,9 @@ der Datenbank der App liest – über eine eigene Leserolle (nur SELECT). `psyco
     #               status, body = bridge.handle(request.method, request.url.path, dict(request.query_params), request.headers.get("authorization"))
     #               return JSONResponse(body, status_code=status)
 
-Vertrag: GET /everydeck/read/capabilities · GET /everydeck/read/objects/{type}?cursor&limit · GET /everydeck/read/people?cursor&limit; eigener Bearer-Schlüssel;
-jedes Schreibverb wird abgewiesen; Seiten ≤ 200; Kennungen als Text (mehrere Schlüsselspalten mit „|“); Zeitstempel ISO-8601; Objektwerte
-als JSON-Text; kein Wert länger als 256 Zeichen. Beziehungen werden wie Objektarten geliefert (type = relations[].id).
+Contract: GET /everydeck/read/capabilities · GET /everydeck/read/objects/{type}?cursor&limit · GET /everydeck/read/people?cursor&limit; own Bearer key;
+every write verb is rejected; pages ≤ 200; identifiers as text (several key columns joined with "|"); timestamps ISO-8601; object values
+as JSON text; no value longer than 256 characters. Relations are delivered like object types (type = relations[].id).
 """
 from __future__ import annotations
 
@@ -28,7 +28,7 @@ from typing import Any, Callable, Iterable, Mapping, Sequence
 
 PAGE_MAX = 200
 VALUE_MAX = 256
-# rows(table, columns, keys, after, limit[, changed]) – changed = {"column", "since"}: nur Geändertes, stabil nach (Änderungsspalte, Schlüssel); Cursor dann [Änderungszeit, …Schlüssel] (B30 Schnitt A)
+# rows(table, columns, keys, after, limit[, changed]); changed = {"column", "since"}: only changed rows, stable by (change column, keys); cursor is then [change time, …keys]
 Rows = Callable[..., Iterable[Mapping[str, Any]]]
 
 
@@ -84,7 +84,7 @@ GRANT_MAX_SECONDS = 300
 
 
 def sign_everydeck_grant(keys: Iterable[str], grant: Mapping[str, Any]) -> dict[str, str]:
-    """Gegenstück (everydeck und Tests): Query-Parameter einer Freigabe – grant = base64url(JSON), grant_sig = v1=<hex> je Schlüssel."""
+    """Counterpart (everydeck and tests): query parameters of a grant; grant = base64url(JSON), grant_sig = v1=<hex> per key."""
     g = base64.urlsafe_b64encode(json.dumps(grant, separators=(",", ":")).encode()).decode().rstrip("=")
     sigs = []
     for k in keys:
@@ -100,8 +100,8 @@ def _is_name(x: Any) -> bool:
 
 
 def grant_of(keys: Iterable[str], query: Mapping[str, str] | None, typ: str, ref: str) -> dict[str, Any] | str:
-    """B46 Punkt 3: Freigabe prüfen – Signatur mit einem gültigen Schlüssel, genau dieses Gespräch, Grund, nicht abgelaufen, Nachrichtentabelle vollständig.
-    Gibt das Gespräch ({messages, attachments}) zurück oder den Grund der Ablehnung."""
+    """Check a grant: signature with a valid key, exactly this conversation, a reason, not expired, message table complete.
+    Returns the conversation ({messages, attachments}) or the reason for rejection."""
     q = query or {}; g = q.get("grant"); sig = q.get("grant_sig")
     if not g or not sig:
         return "grant missing"
@@ -131,12 +131,12 @@ class ReadBridge:
                  deleted: Callable[[str, Sequence[str], str, int], Sequence[Mapping[str, Any]]] | None = None,
                  signatures: str = "required", keys: Sequence[str] | None = None, seen: Callable[[str, float], bool] | None = None,
                  match: Callable[..., Iterable[Mapping[str, Any]]] | None = None) -> None:
-        # B31 Schnitt A: match(table, columns, where_column, values, order, after, limit) → Zeilen eines Gesprächs (psycopg_match); ohne match keine Gespräche
+        # match(table, columns, where_column, values, order, after, limit) → rows of one conversation (psycopg_match); without match no conversations
         self.match = match
-        # B30 Schnitt A: one(table, columns, keys, ref) → eine Zeile; deleted(table, keys, since, limit) → [{ref, deleted_at}] (Löschungen, die die App kennt)
+        # one(table, columns, keys, ref) → one row; deleted(table, keys, since, limit) → [{ref, deleted_at}] (deletions the app knows about)
         self.one = one; self.deleted = deleted
-        # B30 Schnitt E: everydeck signiert jeden Aufruf – "required" (Standard) lehnt unsignierte ab, "optional" nimmt den Bearer ohne Signatur (ältere everydeck-Stände), "off" prüft nur den Bearer;
-        # keys = gültige Schlüssel (Standard: token; während eines Tauschs der neue und der alte), seen = Replay-Schutz über mehrere Instanzen
+        # everydeck signs every call: "required" (default) rejects unsigned calls, "optional" accepts the Bearer without a signature (everydeck instances that do not sign yet), "off" checks only the Bearer;
+        # keys = valid keys (default: token; during a rotation the new and the old one), seen = replay protection across several instances
         if signatures not in ("required", "optional", "off"): raise ValueError("signatures must be required, optional or off")
         self.signatures = signatures; self.keys = list(keys) if keys else [token]; self.seen = seen
         self.scope = scope
@@ -144,7 +144,7 @@ class ReadBridge:
         self.rows = rows
         self.app = app
         self.page_limit = min(PAGE_MAX, max(1, page_limit))
-        self._rights = rights   # fest, oder eine Funktion, die beim ersten Aufruf prüft (psycopg_rights) – nie behauptet
+        self._rights = rights   # fixed, or a function that checks on the first call (psycopg_rights); never just claimed
         self._rights_cache: dict[str, Any] | None = None
         self.types: dict[str, dict[str, Any]] = {}
         for o in scope.get("objects", []):
@@ -161,7 +161,7 @@ class ReadBridge:
         return self._rights_cache
 
     def capabilities(self) -> dict[str, Any]:
-        # B30 Schnitt A: je Objektart, ob changed_since geht (Änderungsspalte im Umfang), und ob der Einzelabruf geht
+        # per object type whether changed_since works (change column in the scope), and whether fetching one object works
         objects = [{"type": o["type"], "fields": [f["name"] for f in o["fields"]], **({"statuses": list(o["statuses"])} if o.get("statuses") else {}), "changed_since": bool(o.get("changed"))} for o in self.scope.get("objects", [])]
         objects += [{"type": r["id"], "fields": [f["name"] for f in r["fields"]], "changed_since": False} for r in self.scope.get("relations", [])]
         people = self.scope.get("people")
@@ -179,7 +179,7 @@ class ReadBridge:
 
     def handle(self, method: str, path: str, query: Mapping[str, str] | None = None, authorization: str | None = None,
                headers: Mapping[str, str] | None = None, body: bytes | str | None = None, url: str | None = None) -> tuple[int, Any]:
-        # headers/url/body (B30 Schnitt E): Kopfzeilen und Pfad mit Query, wie die App sie sieht – für die Signaturprüfung; FastAPI: request.headers, str(request.url), await request.body()
+        # headers/url/body: headers and path with query as the app sees them, for the signature check; FastAPI: request.headers, str(request.url), await request.body()
         full = url if url is not None else (path + ("?" + "&".join(f"{k}={v}" for k, v in (query or {}).items()) if query else ""))
         path = path.split("?", 1)[0]
         if not path.startswith("/everydeck/read/"):
@@ -192,8 +192,8 @@ class ReadBridge:
             if not v.ok:
                 return 401, {"error": f"signature rejected: {v.reason}"}
         elif self.signatures == "required":
-            return 401, {"error": "signature required (X-Everydeck-Signature missing) – everydeck signs every call since B30; use signatures=\"optional\" for older everydeck instances"}
-        elif not hmac.compare_digest((authorization or "").encode(), f"Bearer {self.token}".encode()):   # zeitkonstant
+            return 401, {"error": "signature required (X-Everydeck-Signature missing): everydeck signs every call; use signatures=\"optional\" only for everydeck instances that do not sign calls yet"}
+        elif not hmac.compare_digest((authorization or "").encode(), f"Bearer {self.token}".encode()):   # constant time
             return 401, {"error": "read key invalid"}
         if method.upper() != "GET":
             return 405, {"error": "read only"}
@@ -212,7 +212,7 @@ class ReadBridge:
             rows = list(self.rows(p["table"], cols, [p["ref"]], after, limit + 1))
             kept = rows[:limit]
 
-            def name_of(r):   # B35 Punkt 3: Anzeigename nach der Regel der App – erste Stufe mit Inhalt, Teile mit dem Trennzeichen der App (wie read-bridge.ts)
+            def name_of(r):   # display name by the app's rule: first step with content, parts joined with the app's separator (as in read-bridge.ts)
                 for st in steps:
                     parts = [x for x in ("" if r.get(c) is None else _text(r[c]).strip() for c in st["columns"]) if x]
                     if parts:
@@ -220,11 +220,11 @@ class ReadBridge:
                 return None
             items = [{"subject_ref": _text(r[p["ref"]])[:128], **{f: (None if r.get(c) is None else _text(r[c])[:VALUE_MAX]) for f, c in p["fields"].items()}, **({"display_name": name_of(r)} if steps and "display_name" in p["fields"] else {})} for r in kept]
             return 200, {"as_of": as_of, "items": items, "next_cursor": _b64([_text(kept[-1][p["ref"]])]) if len(rows) > limit else None}
-        if path.startswith("/everydeck/read/messages/") and path[len("/everydeck/read/messages/"):].count("/") == 1:   # B31 Schnitt A: Nachrichten eines Gesprächs, nur auf Abruf
+        if path.startswith("/everydeck/read/messages/") and path[len("/everydeck/read/messages/"):].count("/") == 1:   # messages of one conversation, on demand only
             typ, ref = path[len("/everydeck/read/messages/"):].split("/", 1)
             if self.match is None:
                 return 404, {"error": "this bridge reads no conversations"}
-            # B46 Punkt 3: nur mit der Freigabe von everydeck für genau dieses Gespräch (geöffnet mit Grund); Tabelle und Spalten stehen nur in ihr
+            # only with everydeck's grant for exactly this conversation (opened with a reason); table and columns are only in the grant
             conv = grant_of(self.keys, query, typ, ref)
             if isinstance(conv, str):
                 return 403, {"error": f"a conversation is read only when a moderator opens it with a reason in everydeck ({conv})"}
@@ -244,7 +244,7 @@ class ReadBridge:
                       "text": "\n".join(_text(r[c]) for c in m["text"] if r.get(c) is not None)[:4000], **({"attachments": att[ids[i]]} if att.get(ids[i]) else {})} for i, r in enumerate(kept)]
             return 200, {"type": typ, "ref": ref[:128], "as_of": as_of, "items": items, "next_cursor": _b64([_iso(kept[-1][m["time"]]) or "", *(_text(kept[-1][k]) for k in m["ref"])]) if len(rows) > limit else None}
         rest = path[len("/everydeck/read/objects/"):] if path.startswith("/everydeck/read/objects/") else None
-        if rest is not None and rest.count("/") == 1:   # B30 Schnitt A: Einzelabruf GET /everydeck/read/objects/{type}/{ref}
+        if rest is not None and rest.count("/") == 1:   # fetch one object: GET /everydeck/read/objects/{type}/{ref}
             typ, ref_raw = rest.split("/", 1)
             x = self.types.get(typ)
             if not x:
@@ -267,7 +267,7 @@ class ReadBridge:
             if bad:
                 return 400, {"error": "bad cursor"}
             since_raw = (query or {}).get("changed_since")
-            if since_raw is not None:   # B30 Schnitt A: nur Geändertes seit since, stabil nach (Änderungsspalte, Schlüssel); dazu Gelöschtes, wo die App es kennt
+            if since_raw is not None:   # only rows changed since `since`, stable by (change column, keys); plus deletions where the app knows them
                 if not x["changed"]:
                     return 400, {"error": f"changed_since is not supported for {typ}: no column the database sets on every change"}
                 since = _iso(since_raw)
@@ -306,7 +306,7 @@ class ReadBridge:
 
 
 def _iso(v: Any) -> str | None:
-    """Zeitstempel als ISO-8601 (UTC, Z) oder None"""
+    """Timestamp as ISO-8601 (UTC, Z) or None"""
     if v is None:
         return None
     if isinstance(v, _dt.datetime):
@@ -325,18 +325,18 @@ def _ident(name: str) -> str:
 
 
 def read_view_name(table: str) -> str:
-    """Name der Sicht im Schema der Leserolle (everydeck’s SQL legt sie an): Tabelle, außerhalb von public `<schema>__<tabelle>`."""
+    """Name of the view in the reader role's schema (everydeck's SQL creates it): the table name, outside public `<schema>__<table>`."""
     return table.replace(".", "__", 1) if "." in table else table
 
 
 def psycopg_rows(conn: Any, schema: str | None = None) -> Rows:
-    """`rows` für psycopg 2/3: Keyset-Cursor über die Schlüsselspalten, nur die genannten Spalten; die Verbindung gehört der Leserolle.
-    `schema`: die Sichten der Leserolle (z. B. everydeck_read) statt der Tabellen – so greifen die Zeilenrechte der App nicht für den Leser."""
+    """`rows` for psycopg 2/3: keyset cursor over the key columns, only the given columns; the connection belongs to the reader role.
+    `schema`: the reader role's views (e.g. everydeck_read) instead of the tables, so the app's row-level policies do not apply to the reader."""
     def rows(table: str, columns: Sequence[str], keys: Sequence[str], after: Sequence[str] | None, limit: int, changed: Mapping[str, str] | None = None) -> list[dict[str, Any]]:
         src = f"{_ident(schema)}.{_ident(read_view_name(table))}" if schema else _ident(table)
         lim = f"LIMIT {max(1, min(PAGE_MAX + 1, int(limit)))}"
         cur = conn.cursor()
-        if changed:   # B30 Schnitt A: nur Geändertes seit since, stabil nach (Änderungsspalte, Schlüssel); Cursor = [Änderungszeit, …Schlüssel]
+        if changed:   # only rows changed since `since`, stable by (change column, keys); cursor = [change time, …keys]
             order = [changed["column"], *keys]; params: list[Any] = [changed["since"]]
             where = f" WHERE {_ident(changed['column'])} >= %s"
             if after and len(after) == len(order):
@@ -352,7 +352,7 @@ def psycopg_rows(conn: Any, schema: str | None = None) -> Rows:
 
 
 def psycopg_one(conn: Any, schema: str | None = None) -> Callable[[str, Sequence[str], Sequence[str], Sequence[str]], Mapping[str, Any] | None]:
-    """B30 Schnitt A: `one` für psycopg – genau eine Zeile nach ihren Schlüsselwerten."""
+    """`one` for psycopg: exactly one row by its key values."""
     def one(table: str, columns: Sequence[str], keys: Sequence[str], ref: Sequence[str]) -> Mapping[str, Any] | None:
         src = f"{_ident(schema)}.{_ident(read_view_name(table))}" if schema else _ident(table)
         cur = conn.cursor()
@@ -365,7 +365,7 @@ def psycopg_one(conn: Any, schema: str | None = None) -> Callable[[str, Sequence
 
 
 def psycopg_match(conn: Any, schema: str | None = None) -> Callable[..., list[dict[str, Any]]]:
-    """B31 Schnitt A: `match` für psycopg – Zeilen mit where_column = ANY(values), Keyset-Cursor über order (Nachrichten eines Gesprächs)."""
+    """`match` for psycopg: rows with where_column = ANY(values), keyset cursor over order (messages of one conversation)."""
     def match(table: str, columns: Sequence[str], where_column: str, values: Sequence[str], order: Sequence[str], after: Sequence[str] | None, limit: int) -> list[dict[str, Any]]:
         src = f"{_ident(schema)}.{_ident(read_view_name(table))}" if schema else _ident(table)
         params: list[Any] = [list(values)]; cond = f"{_ident(where_column)}::text = ANY(%s)"
@@ -380,7 +380,7 @@ def psycopg_match(conn: Any, schema: str | None = None) -> Callable[..., list[di
 
 
 def scope_tables(scope: Mapping[str, Any]) -> list[str]:
-    """Alle Tabellen des Umfangs (Objekte, Beziehungen, Gespräche, Personen)."""
+    """All tables of the scope (objects, relations, conversations, people)."""
     out: list[str] = []
     convs = [t for c in (scope.get("conversations") or []) for t in [c["table"], c["messages"]["table"], *([c["attachments"]["table"]] if c.get("attachments") else [])]]
     for t in [o["table"] for o in scope.get("objects", [])] + [r["table"] for r in scope.get("relations", [])] + convs + ([scope["people"]["table"]] if scope.get("people") else []):
@@ -397,22 +397,22 @@ EXPOSURE_SQL = """SELECT
 
 
 def psycopg_rights(conn: Any, scope: Mapping[str, Any], view_schema: str | None = None) -> Callable[[], dict[str, Any]]:
-    """Rechte der Rolle prüfen, nicht behaupten: Superuser (pg_roles.rolsuper) und INSERT/UPDATE/DELETE je Tabelle des Umfangs (has_table_privilege);
-    mit `view_schema` (Sichten der Leserolle, z. B. everydeck_read) zusätzlich, ob das Schema über die Supabase-API (pgrst.db_schemas) oder für anon/authenticated/PUBLIC erreichbar ist."""
+    """Check the role's rights instead of claiming them: superuser (pg_roles.rolsuper) and INSERT/UPDATE/DELETE per scope table (has_table_privilege);
+    with `view_schema` (the reader role's views, e.g. everydeck_read) also whether the schema is reachable through the Supabase API (pgrst.db_schemas) or for anon/authenticated/PUBLIC."""
     def check() -> dict[str, Any]:
         cur = conn.cursor()
         cur.execute("SELECT current_user::text, (SELECT rolsuper FROM pg_roles WHERE rolname = current_user)")
         role, superuser = cur.fetchone()
         writable = []
         for t in scope_tables(scope):
-            # über den Katalog (pg_class), nicht über den Namen: has_table_privilege(name) verlangt USAGE auf dem Schema – eine Leserolle hat das nicht
+            # via the catalog (pg_class), not by name: has_table_privilege(name) requires USAGE on the schema, which a reader role does not have
             schema, name = t.split(".", 1) if "." in t else ("public", t)
             cur.execute("SELECT (has_table_privilege(current_user, c.oid, 'INSERT') OR has_table_privilege(current_user, c.oid, 'UPDATE') OR has_table_privilege(current_user, c.oid, 'DELETE')) FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = %s AND c.relname = %s", [schema, name])
             row = cur.fetchone()
             if row and row[0]:
                 writable.append(t)
         out = {"role": role, "superuser": bool(superuser), "writable": writable, "select_only": not superuser and not writable, "checked_at": _dt.datetime.now(_dt.timezone.utc).isoformat().replace("+00:00", "Z")}
-        if view_schema:   # die Sichten laufen als Eigentümer (keine Zeilenrechte der App): niemand außer der Leserolle darf an das Schema
+        if view_schema:   # the views run as their owner (no app row-level policies): nobody but the reader role may access the schema
             cur.execute(EXPOSURE_SQL, {"s": view_schema})
             api, anon, authenticated, pub = cur.fetchone()
             out["exposed"] = [n for n, v in (("supabase api", api), ("anon", anon), ("authenticated", authenticated), ("public", pub)) if v]

{everydeck-0.3.0 → everydeck-0.3.2}/everydeck/read_route.py

@@ -1,8 +1,8 @@
-"""B46 (Entscheidung E2): die Lese-Brücke als fertige Route – Python-Fassung von @everydeck/sdk/read-bridge, gleiches Verhalten.
+"""The read bridge as a ready-made route: Python version of @everydeck/sdk/read-bridge, same behavior.
 
-Die App bindet sie mit der Verbindung ein, die sie schon hat; keine Leserolle, keine Sichten, keine Datei mit dem Lese-Umfang im Repo:
+The app mounts it with the connection it already has; no reader role, no views, no read scope file in the repo:
 
-    from everydeck.read_route import EverydeckReadBridge, SupabaseReadOnly   # oder PsycopgReadOnly(os.environ["DATABASE_URL"])
+    from everydeck.read_route import EverydeckReadBridge, SupabaseReadOnly   # or PsycopgReadOnly(os.environ["DATABASE_URL"])
     bridge = EverydeckReadBridge(os.environ["EVERYDECK_URL"], os.environ["EVERYDECK_READ_BRIDGE_TOKEN"], SupabaseReadOnly(supabase_admin))
     @app.api_route("/everydeck/read/{rest:path}", methods=["GET", "POST", "PUT", "PATCH", "DELETE"], include_in_schema=False)
     async def everydeck_read(rest: str, request: Request):
@@ -10,13 +10,13 @@ Die App bindet sie mit der Verbindung ein, die sie schon hat; keine Leserolle, k
                                                request.headers.get("authorization"), request.headers, await request.body(), str(request.url))
         return JSONResponse(body, status_code=status)
 
-- Den Lese-Umfang holt die Route bei everydeck (GET <endpoint>/v1/read-scope mit dem Brückenschlüssel als Bearer) und nutzt ihn nur mit gültiger
-  Signatur (HMAC-SHA256 mit demselben Schlüssel über "EVERYDECK-SCOPE-V1\\n" + payload); sonst liest sie nichts (503).
-- PsycopgReadOnly: jede Abfrage in einer eigenen Transaktion BEGIN READ ONLY auf der Verbindung der App – die Datenbank lehnt darin jedes Schreiben ab.
-  Die Rechte werden geprüft: Rolle, Superuser, rolbypassrls, current_setting('transaction_read_only').
-- SupabaseReadOnly: der Supabase-Client der App (PostgREST). Die Route ruft nur select() auf, also nur GET-Anfragen; PostgREST führt GET-Anfragen
-  in einer Nur-Lesen-Transaktion aus. Erreichbar sind nur Tabellen in Schemas, die die Supabase-API freigibt.
-Keine Abhängigkeiten außer der Standardbibliothek; psycopg bzw. supabase bringt die App mit.
+- The route fetches the read scope from everydeck (GET <endpoint>/v1/read-scope with the bridge key as Bearer) and uses it only with a valid
+  signature (HMAC-SHA256 with the same key over "EVERYDECK-SCOPE-V1\\n" + payload); otherwise it reads nothing (503).
+- PsycopgReadOnly: every query runs in its own BEGIN READ ONLY transaction on the app's connection; the database rejects any write inside it.
+  The rights are checked: role, superuser, rolbypassrls, current_setting('transaction_read_only').
+- SupabaseReadOnly: the app's Supabase client (PostgREST). The route only calls select(), so only GET requests; PostgREST runs GET requests
+  in a read-only transaction. Only tables in schemas exposed by the Supabase API are reachable.
+No dependencies beyond the standard library; the app brings psycopg or supabase itself.
 """
 from __future__ import annotations
 
@@ -63,7 +63,7 @@ def verify_scope_signature(keys: Iterable[str], payload: str, signature: str | N
 
 
 class PsycopgReadOnly:
-    """Die Verbindung der App über psycopg 3: `PsycopgReadOnly(conninfo)` oder `PsycopgReadOnly(connect=lambda: …)`; jede Abfrage in BEGIN READ ONLY … COMMIT."""
+    """The app's connection via psycopg 3: `PsycopgReadOnly(conninfo)` or `PsycopgReadOnly(connect=lambda: …)`; every query in BEGIN READ ONLY … COMMIT."""
 
     def __init__(self, conninfo: str | None = None, *, connect: Callable[[], Any] | None = None) -> None:
         if conninfo is None and connect is None:
@@ -87,7 +87,7 @@ class PsycopgReadOnly:
                 try:
                     conn.cursor().execute("ROLLBACK")
                 except Exception:
-                    self._conn = None   # Verbindung kaputt: beim nächsten Aufruf neu
+                    self._conn = None   # connection broken: reconnect on the next call
                 raise
 
     def rows(self, *a: Any, **k: Any) -> list[dict[str, Any]]:
@@ -110,12 +110,12 @@ class PsycopgReadOnly:
 
 
 def _quote(v: str) -> str:
-    """Wert in einem PostgREST-Filter (or=…): in doppelten Anführungszeichen, \\ und \" maskiert"""
+    """Value in a PostgREST filter (or=…): in double quotes, with \\ and \" escaped"""
     return '"' + str(v).replace("\\", "\\\\").replace('"', '\\"') + '"'
 
 
 class SupabaseReadOnly:
-    """Der Supabase-Client der App (supabase-py, PostgREST): nur select(), also nur GET-Anfragen – PostgREST führt sie in einer Nur-Lesen-Transaktion aus."""
+    """The app's Supabase client (supabase-py, PostgREST): only select(), so only GET requests; PostgREST runs them in a read-only transaction."""
 
     def __init__(self, client: Any) -> None:
         self.client = client
@@ -163,21 +163,21 @@ class SupabaseReadOnly:
         return list(q.limit(max(1, min(PAGE_MAX + 1, int(limit)))).execute().data or [])
 
     def rights(self, scope: Mapping[str, Any]) -> dict[str, Any]:
-        # Über PostgREST lässt sich die Rolle nicht per SQL prüfen; fest steht der Weg: nur GET (select), von PostgREST nur lesend ausgeführt.
+        # The role cannot be checked by SQL through PostgREST; the path is fixed: only GET (select), run read-only by PostgREST.
         return {"role": "supabase api (postgrest)", "select_only": False, "read_only_transaction": True, "checked_at": _dt.datetime.now(_dt.timezone.utc).isoformat().replace("+00:00", "Z")}
 
 
 def _default_fetch(url: str, headers: Mapping[str, str]) -> tuple[int, str]:
     req = urllib.request.Request(url, headers=dict(headers), method="GET")
     try:
-        with urllib.request.urlopen(req, timeout=10) as r:   # noqa: S310 – Adresse von everydeck aus der Umgebung der App
+        with urllib.request.urlopen(req, timeout=10) as r:   # noqa: S310 (everydeck address from the app's environment)
             return r.status, r.read().decode()
     except urllib.error.HTTPError as e:
         return e.code, ""
 
 
 class EverydeckReadBridge:
-    """Die fertige Lese-Brücke: Lese-Umfang signiert von everydeck, Lesen über `db` (PsycopgReadOnly oder SupabaseReadOnly)."""
+    """The ready-made read bridge: read scope signed by everydeck, reads through `db` (PsycopgReadOnly or SupabaseReadOnly)."""
 
     def __init__(self, endpoint: str | None, key: str | None, db: Any, *, previous_key: str | None = None, app: str | None = None, scope_ttl: float = 60.0,
                  seen: Callable[[str, float], bool] | None = None, fetch: Callable[[str, Mapping[str, str]], tuple[int, str]] | None = None) -> None:

{everydeck-0.3.0 → everydeck-0.3.2}/everydeck/verify.py

@@ -1,13 +1,13 @@
-"""B30 Schnitt E – Prüfhilfe für Brücken: everydeck signiert jeden Aufruf an eine Lese- oder App-Brücke (wie Stripe).
+"""Verification helper for bridges: everydeck signs every call to a read or app bridge (like Stripe).
 
-Kopfzeilen: X-Everydeck-Timestamp (Unix-Sekunden), X-Everydeck-Request-Id (UUID), X-Everydeck-Signature (v1=<hex>[,v1=<hex>] – eine je gültigem Schlüssel).
-Signatur = HMAC-SHA256(Schlüssel, "EVERYDECK-V1\\n" + METHOD + "\\n" + Pfad ab /everydeck/ mit Query + "\\n" + Zeitstempel + "\\n" + request_id + "\\n" + SHA-256(Körper) hex).
-Die App lehnt ab, wenn der Zeitstempel mehr als 5 Minuten abweicht oder die request_id in dieser Zeit schon gesehen wurde.
-B31 Abnahme (A8): Die request_id der Signatur (X-Everydeck-Request-Id) ist je HTTP-Aufruf neu, auch wenn everydeck denselben Auftrag wiederholt – der
-Replay-Schutz trifft nur eine wörtlich wiederholte Anfrage. Die Idempotenz einer Aktion trägt `request_id` im Körper und `Idempotency-Key`;
-eine Wiederholung beantwortet die Tür mit dem festgehaltenen Ergebnis, nie mit 401.
+Headers: X-Everydeck-Timestamp (Unix seconds), X-Everydeck-Request-Id (UUID), X-Everydeck-Signature (v1=<hex>[,v1=<hex>], one per valid key).
+Signature = HMAC-SHA256(key, "EVERYDECK-V1\\n" + METHOD + "\\n" + path from /everydeck/ with query + "\\n" + timestamp + "\\n" + request_id + "\\n" + SHA-256(body) hex).
+The app rejects the call when the timestamp is off by more than 5 minutes or the request_id was already seen within that window.
+The signature's request_id (X-Everydeck-Request-Id) is new for every HTTP call, even when everydeck retries the same job; replay
+protection only catches a literally repeated request. Idempotency of an action is carried by `request_id` in the body and `Idempotency-Key`;
+the bridge route answers a retry with the recorded result, never with 401.
 
-Eine Zeile in der Tür der App (FastAPI):
+One line in the app's bridge route (FastAPI):
     v = verify_everydeck_request(request.method, str(request.url), request.headers, await request.body(), keys=[os.environ["EVERYDECK_BRIDGE_KEY"]])
     if not v.ok: raise HTTPException(401)
 """
@@ -42,7 +42,7 @@ def signature_for(key: str, canonical: str) -> str:
 
 
 class MemorySeen:
-    """Replay-Speicher je Prozess: request_id → Zeitstempel, aufgeräumt nach dem Fenster (mehrere Instanzen: eigene Prüfung, z. B. Redis/Postgres)."""
+    """Per-process replay store: request_id → timestamp, pruned after the window (several instances: use your own check, e.g. Redis/Postgres)."""
 
     def __init__(self, window_seconds: int = SIGNATURE_WINDOW_SECONDS, now: Callable[[], float] = time.time) -> None:
         self._m: dict[str, float] = {}; self._lock = threading.Lock(); self.window = window_seconds; self.now = now
@@ -109,7 +109,7 @@ def verify_everydeck_request(method: str, url_or_path: str, headers: Mapping[str
 
 
 def sign_everydeck_request(keys: Iterable[str], method: str, url_or_path: str, body: bytes | str | None = None, request_id: str | None = None, now: float | None = None) -> dict[str, str]:
-    """Gegenstück für Tests und Prüfskripte der App: Kopfzeilen, wie everydeck sie schickt (erster Schlüssel aktuell, weitere vorige). Im Produkt signiert nur everydeck."""
+    """Counterpart for the app's tests and check scripts: headers as everydeck sends them (first key current, further keys previous). In production only everydeck signs."""
     import uuid
     timestamp = int((time.time() if now is None else now))
     rid = request_id or str(uuid.uuid4())

{everydeck-0.3.0 → everydeck-0.3.2}/everydeck.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: everydeck
-Version: 0.3.0
+Version: 0.3.2
 Summary: everydeck Python SDK: bounded buffer, background sender, flush on shutdown, reported data gaps
 License-Expression: MIT
 Project-URL: Homepage, https://everydeck.ai
@@ -40,7 +40,7 @@ everydeck.signal("job.created", operation_id)
 - `signal()`, `error()` and `log()` never block and never raise: they enqueue into a bounded in-memory buffer; a background thread sends batches (at most 50 events, 64 KiB, gzip-compressed).
 - Retries only on 429, 5xx, timeout and network errors; `Retry-After` is honoured; final rejections are dropped and counted, never reported as sent.
 - A buffer overflow is reported as a `gap` event, so everydeck shows a known data gap instead of silence.
-- `heartbeat_interval` sends `everydeck.sdk.heartbeat` from the sender thread. Give each component a stable `instance_id` (for example `"api"`, `"cv-worker"`).
+- `heartbeat_interval` sends `everydeck.sdk.heartbeat` from the sender thread. Give each component a stable `instance_id` (for example `"api"`, `"worker"`).
 - `release_key="auto"` derives the version from the deployment commit (`EVERYDECK_RELEASE_KEY`, `GITHUB_SHA`, `VERCEL_GIT_COMMIT_SHA`, `RENDER_GIT_COMMIT`, …) or local git.
 - `everydeck.verify.verify_everydeck_request` checks everydeck's signature on bridge calls.
 - Read bridge (0.3.0): `everydeck.read_route.EverydeckReadBridge(endpoint, key, db)` is the ready-made route. It fetches its read scope from everydeck (`GET <endpoint>/v1/read-scope` with the bridge key) and uses it only with everydeck's signature; no read-scope file, no read role, no views. `db` is the connection the app already has: `PsycopgReadOnly(conninfo)` runs every query in `BEGIN READ ONLY`, `SupabaseReadOnly(client)` reads through the app's Supabase client with `select()` only (GET requests, which PostgREST runs read-only; only tables in schemas the Supabase API exposes).

{everydeck-0.3.0 → everydeck-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "everydeck"
-version = "0.3.0"
+version = "0.3.2"
 description = "everydeck Python SDK: bounded buffer, background sender, flush on shutdown, reported data gaps"
 readme = "README.md"
 license = "MIT"