@relyio/sdk 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,198 @@
 # @relyio/sdk
 
+## 0.6.0
+
+### Minor Changes
+
+- af38235: `relyio.changesHead()` returns the changes feed's current position without waiting for a change. Take it before you read what you are going to follow, and start the feed from it, so a write that lands between your read and the feed's start is replayed rather than missed:
+
+  ```ts
+  const since = await relyio.changesHead()
+  const post = await relyio.content('post').findById(id).execute()
+  for await (const change of relyio.changes({ since, ids: [id] })) {
+    // …
+  }
+  ```
+
+  `RELYIO_RESYNC_EVENT` (`'relyio:resync'`) is the event a preview surface dispatches on `window` when the feed lost its place and it re-read everything, so anything on the page may be stale. Its `detail`, `RelyIOResyncDetail`, says why: `{ cause: 'expired', reason }` or `{ cause: 'no-cursor' }`. It is never dispatched as a `relyio:change`, so a listener that reads a change's ids never receives one without them.
+
+- 80cb307: `fetchOne()` and `fetchOneWithTag()` take the headers one read adds, and `findById()` has a matching `.headers()` step. A name the client already sends is replaced for that request only, so this reads an entry from another dataset your key can see without changing the client:
+
+  ```ts
+  const draft = await relyio.content('post').fetchOne('welcome', {
+    headers: { 'X-RelyIO-Dataset': 'staging' },
+  })
+  ```
+
+- 1fa0ba4: `followChanges()` follows the changes feed for as long as you need it, and reconnects for you. Hand it where the changes come from and what to do with each one:
+
+  ```ts
+  import { createClient, followChanges } from '@relyio/sdk'
+
+  const relyio = createClient({ apiKey: process.env.RELYIO_API_KEY! })
+  const controller = new AbortController()
+
+  const end = await followChanges(from => relyio.changes({ ...from, types: ['post'] }), {
+    signal: controller.signal,
+    onChange: change => refetch(change.contentType, change.entryId),
+    onResync: () => refetchEverything(),
+    onState: state => console.info(state.kind),
+  })
+  if (end.kind === 'stopped') console.error(end.error)
+  ```
+
+  - Changes are handed to `onChange` one at a time, in order, and the next is not taken until the one before it has settled.
+  - When the feed fails with something retrying can fix, it waits and reopens from the last change it delivered, so nothing is skipped. The wait starts at up to one second and doubles to at most thirty, shortened by a random amount of up to half so that many clients do not reconnect at the same instant, and it is never shorter than a `Retry-After` the service sent. A delivered change resets it.
+  - `onResync` is called when what you derived from the feed may be stale: the cursor could no longer be replayed, or the feed failed before any change arrived, so there was nothing to resume from. Re-read what you hold there.
+  - Anything retrying cannot fix, such as a revoked key, ends it with `{ kind: 'stopped', error }`. Aborting the signal ends it with `{ kind: 'aborted', since }`, where `since` is the cursor to start a later follow from. It never rejects.
+  - `onState` reports `following`, `reconnecting` (with the error and the wait), `resynced` and `stopped`. `classifyFollowFailure()` is the default decision between retrying and stopping, and `FOLLOW_RETRY_BASE_MS` and `FOLLOW_RETRY_MAX_MS` are the wait's bounds.
+  - The first argument can be any source of changes, not only `relyio.changes()`. A source you write can call the `opened()` it is handed once its connection is up; the next time that connection drops, the wait starts again from one second even though no change arrived.
+
+- 028739b: `createClient()` no longer throws when `apiKey` is missing or empty. The key is now required by each request instead: a client created without one sends nothing, and every read or write it makes rejects with `MissingApiKeyError` naming `apiKey`. A client created at the top of a module, such as `createClient({ apiKey: process.env.RELYIO_API_KEY! })`, can now be loaded by a build that has no keys set, such as `next build` in CI. Under `relyio dev` the sandbox's key is used, so `RELYIO_API_KEY` no longer needs to be set there either.
+
+  A key that is only whitespace is now refused the same way, before the request is sent. Before, it was sent and the API refused it.
+
+  ```ts
+  import { createClient, MissingApiKeyError } from '@relyio/sdk'
+
+  const relyio = createClient({ apiKey: process.env.RELYIO_API_KEY! }) // no longer throws when unset
+
+  try {
+    await relyio.content('post').findById('welcome').execute()
+  } catch (error) {
+    if (error instanceof MissingApiKeyError) console.error('Set RELYIO_API_KEY')
+  }
+  ```
+
+- 2f3e7e1: `isPublishableKey(apiKey)` says whether a key is a publishable key (`rly_pub_…`), the one kind of key that may sit in a browser. It reads the key's prefix only; whether the key is valid, active or allowed from the page's origin is still the API's answer. `PUBLISHABLE_KEY_PREFIX` is the prefix it checks.
+
+  ```ts
+  import { isPublishableKey } from '@relyio/sdk'
+
+  isPublishableKey(import.meta.env.VITE_RELYIO_PUBLISHABLE_KEY) // true
+  ```
+
+- 7719c0a: The list, search, similar and ad-hoc query reads take the headers one read adds, so each can read another dataset your key can see without changing the client: `content(type).query().headers(…)`, `search(q).headers(…)`, `similar(id).headers(…)`, and a fourth `{ headers }` argument to `query.execute()`.
+
+  ```ts
+  const drafts = await relyio
+    .search('welcome')
+    .across('*')
+    .headers({ 'X-RelyIO-Dataset': 'staging' })
+    .execute()
+  ```
+
+  `search()` gains `.sort(field, direction)`, which sends the route's `sort` array (relevance orders the results otherwise), and `similar()` gains `.across(contentTypes | '*')` to find similar entries across several content types or all of them.
+
+  **Aggregate metrics are now the expression the service reads.** `AggregateMetric` was `{ fn, field? }`, a shape `POST /v1/query` refuses on every request — its validator tests each metric against `<field>.<fn>` and read the object as `[object Object]`. It is now that string, e.g. `'id.count'` or `'price.avg'`, and `AggregateBlock` gains the `where` the service already applies before grouping (in the Query DSL's bare spelling, `{ price: { gte: 10 } }`):
+
+  ```ts
+  await relyio.query.aggregate('product', { count: 'id.count', avgPrice: 'price.avg' }, 'status')
+  ```
+
+- 1772f21: Entries are typed field by field. Once `relyio generate-types` has registered your schema — or you pass `schema:` — every field of an entry has the type a read returns, where it used to be `unknown`:
+
+  ```ts
+  const post = await relyio.content('post').fetchOne(id)
+
+  post?.title // string | undefined
+  post?.status // 'draft' | 'published' | undefined — an enum is the union of its options
+  post?.author // string | null | Author | undefined — the author's id, or the author once `include` names it
+  ```
+
+  | Field type                                      | Read as                                                                                                                                                                     |
+  | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+  | `shortText`, `longText`, `email`, `url`, `slug` | `string`                                                                                                                                                                    |
+  | `richText`                                      | `string` — the stored HTML                                                                                                                                                  |
+  | `integer`, `decimal`                            | `number`                                                                                                                                                                    |
+  | `boolean`                                       | `boolean`                                                                                                                                                                   |
+  | `enum`                                          | the union of its option values; an array of them with `multi: true`                                                                                                         |
+  | `date`, `dateTime`                              | `string` — `YYYY-MM-DD` and ISO 8601; the client does not convert them to `Date`                                                                                            |
+  | `reference`                                     | the target's id, or the target entry once `include` expands it; `null` after its target was deleted with `onTargetDelete: 'nullify'`; an array of either with `multi: true` |
+  | `tags`                                          | `string[]`                                                                                                                                                                  |
+  | `list`                                          | objects of its subfields, or `string[]` when it declares none                                                                                                               |
+  | `component(…)`                                  | an object of the component's fields                                                                                                                                         |
+
+  - Every field is optional: a read leaves out a field with no value — a draft, a `fields` projection, a locale with nothing to fall back to.
+  - A localized field is the value for the locale you read, like any other field.
+  - `where()` is typed by the same fields: each key is one of the content type's fields and each value one of that field's values — a list field matches one of its items, a reference the target's id, an array means "any of". With no schema, `where()` now accepts any field name; before, it accepted only `_metadata`.
+  - `search()` results are typed by the schema: every content type's entries until `.in('post')` or `.across(['post', 'page'])` narrows them, and `.in()` takes only your content types' names.
+  - `InferContentType`, `InferSingleton`, `InferAssetType` and `InferSettingsGroup` take the schema as an optional second argument — `InferContentType<typeof post, typeof schema>` — which is what types an expanded reference as its entry and a component as its fields. Without it, those two are typed as an entry or an object whose fields are not known.
+  - `defineComponent()` keeps its fields' types, as `defineContentType()` does.
+  - New types: `SchemaEntry`, `SchemaEntryOf`, `FieldValue`, `FieldValues`, `UnresolvedEntry`, `UnresolvedComponent`, `SearchEntry`, `SearchTypeName`, `WhereScalar` and `WhereFieldCondition`.
+
+  Code that relied on a field being `unknown` may now fail to compile where it passes a value the field cannot hold — `create({ price: 'free' })` for a `decimal`, `where({ status: 'archived' })` when `archived` is not an option. Nothing changes at runtime.
+
+- 88b004e: `create()` and `update()` take the headers one write adds, and a batch has a matching `.headers()` step. A name the client already sends is replaced for that request only, so this writes to another dataset your key can write without changing the client:
+
+  ```ts
+  await relyio.content('post').update(
+    'welcome',
+    { title: 'Hello' },
+    {
+      locale: 'de-DE',
+      headers: { 'X-RelyIO-Dataset': 'staging' },
+    },
+  )
+  ```
+
+  `ifMatch` and `idempotencyKey` still decide `If-Match` and `Idempotency-Key`, whatever the headers name.
+
+### Patch Changes
+
+- ec18021: `browser: { includeCredentials: false }` now keeps the browser's cookies off requests to another origin. It used to send them exactly as `true` does. In a web page the client now sends `credentials: 'same-origin'` for `false` and `credentials: 'include'` for `true` or when the option is left unset, which is still the default. Outside a web page (on a server, in an edge runtime or in a Web Worker) the client sets no `credentials` mode at all, as before. The RelyIO API authenticates with your API key and reads no cookie, so turning cookies off changes nothing it answers:
+
+  ```ts
+  const relyio = createClient({
+    apiKey: 'rly_pub_…',
+    browser: { includeCredentials: false },
+  })
+  ```
+
+- 88b004e: `REQUEST_INVALID`, `CONTENT_INVALID` and `REQUEST_TIMEOUT` refusals now keep the body the API sent on `error.context.response`, as every other refusal already did, so every message and `details` the API returned can be read — not only the first message the error class keeps. `InvalidPayloadError`, `ValidationError` and `TimeoutError` take an optional `context` as their last constructor argument, and a `REQUEST_TIMEOUT` refusal's `TimeoutError` now carries its status, `408`.
+- d99bece: A client from `withLocale()` now reads in its locale everywhere, not only through `content()` and `asset()`. These reads asked for the default locale, and now ask for the client's:
+
+  - `singleton(key)`: `fetch()`, `fetchWithTag()` and `exists()`
+  - `settings(group)`: `fetch()`, `fetchWithTag()` and `exists()`
+  - `search()`, `similar()` and `autocomplete()`
+  - `content(type).children(id)`
+  - `executeQuery(name, params)`
+  - the ad-hoc queries, `adhoc()` and every `query` method, which send it as the `locale` parameter
+
+  ```ts
+  const fr = relyio.withLocale('fr')
+
+  await fr.singleton('home').fetch() // French; before, the default locale
+  await fr.search('chaussures').execute() // French; before, the default locale
+  ```
+
+  A locale you name on the call still wins over the client's: `.locale('de')`, `fetch({ locale: 'de' })`, `children(id, { locale: 'de' })`, or a `locale` parameter (for `executeQuery()`, `locales` as well). `updateConfig({ locale })` now reaches these reads too. A client with no locale sends none, as before.
+
+  Version history (`versions()`, `version()`) and writes are unchanged.
+
+## 0.5.0
+
+### Minor Changes
+
+- c59912d: `client.sandbox` reports the `relyio dev` sandbox the client resolved, `client.project()` describes the project your key belongs to, and `@relyio/sdk` exports the `SandboxState`, `Project` and `RelyIOChangeDetail` types.
+
+  `client.project()` calls `GET /v1/project` and returns the organization, project, dataset and branch, each with its `id` and `name`, plus `studioUrl`, the address of the project's Studio. `dataset` is the one your requests read, which may be a sandbox rather than the project's default, so add it to a Studio link as `?dataset=`. `studioUrl` is `null` when the service has no Dashboard address configured.
+
+  `client.sandbox` is one of five states:
+
+  - `{ state: 'active', datasetId, branchId, expiresAt, source }` — the client is reading the sandbox. `source` is `'env'` under `relyio dev -- <command>` and `'file'` when it read `.relyio/dev.json`. `branchId` is `null` from the environment, which names no branch. `expiresAt` is `null` for a sandbox with no deadline.
+  - `{ state: 'expired', expiredAt }` or `{ state: 'unreadable', reason }` — a sandbox was found and ignored, so the client reads the dataset and key you configured. The console says so, as before.
+  - `{ state: 'absent' }` — no sandbox was found. A client created in the browser always reports this, because the browser cannot see the environment or the file.
+  - `{ state: 'disabled' }` — the client did not look, because you passed `dev: false`, or `NODE_ENV` is `production` and you did not pass `dev: true`.
+
+  It is plain JSON with no API key in it, so a Next.js server component can pass it to a client component as a prop:
+
+  ```tsx
+  <SandboxBadge sandbox={relyio.sandbox} />
+  ```
+
+  `RelyIOChangeDetail` is the `detail` a `RELYIO_CHANGE_EVENT` dispatch carries: the same `{ entryId, contentType, locale, kind, cursor }` as a `Change` from `relyio.changes()`.
+
 ## 0.4.0
 
 ### Minor Changes