@relyio/sdk 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @relyio/sdk
 
+## 0.8.0
+
+### Minor Changes
+
+- 5207d3f: **`liveChanges()` follows a dataset's published changes at RelyIO's live edge, with a publishable key.** It opens one WebSocket to the edge and yields each change as ids — `{ entryId, contentType, locale, kind, cursor, fresh }` — the same `FeedChange` `changes()` now yields. Where a socket cannot open (a network that blocks sockets, or Node 18 and 20, which have no global `WebSocket`) it asks the edge for changes about every fifteen seconds instead, and tries a socket again about once a minute. Hand it to `followChanges()`, which reconnects from the last change after a dropped connection — the edge drops every connection when it deploys — with a random, growing wait:
+
+  ```ts
+  import { createClient, followChanges } from '@relyio/sdk'
+
+  const relyio = createClient({ apiKey: 'rly_pub_…' })
+  const controller = new AbortController()
+  await followChanges(from => relyio.liveChanges({ ...from, types: ['post'] }), {
+    signal: controller.signal,
+    onChange: change =>
+      relyio.content(change.contentType).findById(change.entryId).fresh(change.fresh).execute(),
+    onResync: resync =>
+      refetchEverything(resync.cause === 'expired' ? resync.expired.fresh : undefined),
+  })
+  ```
+
+  **Refetch with `fresh`.** Every change `changes()` and `liveChanges()` deliver carries `fresh`, the feed's position at or after the change: the change's own cursor on `changes()`, the cursor of its batch at the edge. `findById()`, `query()` and `search()` take it as `.fresh(position)`, and a singleton's `fetch()` as `{ fresh }`; the read is sent with `?_fresh=…`, which the Content API accepts on every read its edge cache may keep and which changes nothing about the answer. Your reads go through that edge and through the browser's own cache, and a change can reach you a moment before its old answer has left them; a request naming a position nobody asked for before the change is one no cache holds an answer to, so it is answered after the change, and every visitor refetching for the same change shares that answer. Use `fresh`, not `cursor` — at the edge an earlier change of a batch carries the position before its batch as `cursor`. An expired cursor's `ChangesExpiredError` carries `fresh` too: the position the feed started again from, for refetching everything. The iterators' element type is now `FeedChange`, the document's `Change` plus `fresh`; `followChanges()` and `ChangeSource` take the change type as a parameter, so a source of plain `Change`s still follows as before.
+
+  `onExpired` and `signal` mean what they mean for `changes()`. Only a publishable key is sent to the edge: with any other key, `liveChanges()` sends nothing and ends with a `LiveEdgeError`. On a server, keep following `changes()` with a secret or preview key.
+
+  **Every other end is a `LiveEdgeError` that says what to do next**, and `followChanges()`'s default classifier reads it: `stop` for a refusal the same request would meet again (an unknown or revoked key, an origin the key does not list, a dataset it does not reach), `retry` for a dropped connection, and `back-off` when the project, or the visitor's address, already holds as many live connections as it may — a wait of at least a minute, longer each time it repeats, up to fifteen, without polling meanwhile. `FollowVerdict` gains `backOffMs` for that schedule, and `FOLLOW_BACK_OFF_MAX_MS` is its cap.
+
+  **Two new options.** `liveUrl` is the live edge; with the default `baseUrl` it is `https://live.relyio.com` and need not be set, and for any other `baseUrl` it must be. `webSocket` is the `WebSocket` class to open the socket with; omitted, the runtime's global one.
+
+  `ChangesExpiredError.reason` can now also be `ahead-of-head`, `foreign-cursor` or `too-far-behind`, the edge's reasons to refetch everything. A `followChanges()` source may now call `reached(cursor)` with a position it holds without a change, so a connection dropped before its first change reopens from there rather than re-reading everything.
+
 ## 0.7.0
 
 ### Minor Changes