openvibers/openvibe.sdk Commits

openvibe-sdk 0.42.0: an Events position is an opaque cursor only (#39)

OP OpenVibers committed 10 Oct 2026 · tag v0.42. · 0 files, +0 −0

Plan T7, ADR-042 decision 7: an Events position is an opaque cursor and nothing else. Every consumer already reads by cursor; this release removes the numeric position from the client, so Events can stop accepting it next (`after_seq`, `next_after_seq`/`latest_seq`, numeric checkpoints, bare-seq resume). **Breaking** for a caller that still passes a number.

- **`pull()` / `iterate()`:** take `after` only (a page's `next_cursor`, or `latest_cursor` for the head).
  - `afterSeq` throws a `TypeError` instead of silently reading from the start.
  - With no `after`, the page starts at the oldest retained event and no `after_seq` is sent. Before, `after_seq=0` was always sent, which is why Events cannot refuse it until every reader has this release.
  - `iterate()` ends on the page whose `next_cursor` equals `latest_cursor`, or on one that does not move the position. Comparing two cursors for equality parses neither.
- **Checkpoints:** `setCheckpoint(topic, cursor, { carrier })` takes a cursor string and rejects anything else; `getCheckpoint()` returns the cursor as stored, or null.
- **Realtime:** resumes from the cursor exactly as Events sent it, and dedupes by `event_id` (the last 512) instead of by position. The callback's `cursor` is what to save; `seq` is informational. A later step can therefore drop the per-event `seq` from Events without touching clients again.
- **`parseDelivery()`:** `seq: null` when a delivery carries none (it was `NaN`).
- **Mock Events:**
  - `after_seq` is a 400.
  - Pages carry no numeric fields.
  - Checkpoints hold cursors.
  - The realtime `id:` is the cursor, and a bare-number `Last-Event-ID` is ignored. That is how Events will behave.
- Types, README, CHANGELOG, STATUS, `SDK_VERSION`, browser bundle.

Tests:
- `events.test.js`:
  - pages without the numeric fields;
  - `afterSeq` throwing in `pull` and `iterate`;
  - the mock refusing `after_seq`;
  - `iterate` stopping at `latest_cursor` without an extra request (and by the unchanged cursor when there is none);
  - opaque checkpoints with a carrier, a number rejected;
  - retention gaps from cursors.
- `app-events.test.js`: per-app checkpoints with cursors.
- `realtime.test.js`:
  - a repeated `event_id` delivered once;
  - the reconnect handing back the opaque cursor.

`ov test`: 37 files reached, all green.