@relyio/sdk 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,121 @@
 # @relyio/sdk
 
+## 0.4.0
+
+### Minor Changes
+
+- 06baad9: `relyio.changes()` follows the content changes feed (`GET /v1/changes`) as an async iterable.
+
+  ```ts
+  const controller = new AbortController()
+
+  for await (const change of relyio.changes({ types: ['post'], signal: controller.signal })) {
+    // { entryId, contentType, locale, kind: 'published' | 'updated' | 'unpublished' | 'deleted', cursor }
+    await revalidate(change.contentType, change.entryId)
+  }
+  ```
+
+  - A change carries ids only. Refetch the entry through the ordinary read methods to see it.
+  - The API key decides what arrives: a published key sees publication changes, a preview key sees draft saves as well.
+  - Each request long-polls, so an idle feed costs one request every 25 seconds or so. When the service or your key is at its limit of held connections, the iterator waits for the `Retry-After` the service sends before asking again.
+  - Pass `since` (a change's `cursor`) to resume where you stopped. Without it, the feed starts at the present.
+  - A cursor too old to replay throws `ChangesExpiredError` (with a `reason`). Pass `onExpired: 'resync'` to start again from the present instead, or a function to be called when that happens — the place to refetch everything you hold.
+  - Aborting the `signal` ends the loop without throwing.
+
+  Also fixed: a request given its own `signal` no longer loses the client's timeout, and aborting it is no longer retried or reported as a `TimeoutError`.
+
+- f21099b: `createClient()` takes a `fetch` option, and `@relyio/sdk` exports `matchRoute`, `IMAGE_LADDER`, `snapToLadder` and `RELYIO_CHANGE_EVENT`.
+
+  `fetch` is the function every request to the RelyIO API is sent through. The client still builds each request and passes your function the same `RequestInit` it would pass the runtime's `fetch`, including on a retry, so a write's `Idempotency-Key` does not change between attempts. Use it to add what your framework reads off the request, such as Next.js cache tags:
+
+  ```ts
+  import { createClient } from '@relyio/sdk'
+
+  const relyio = createClient({
+    apiKey: process.env.RELYIO_API_KEY!,
+    fetch: (input, init) => fetch(input, { ...init, next: { tags: ['posts'] } }),
+  })
+  ```
+
+  Leave it out and the client uses the global `fetch`, as before. File bytes that an asset upload sends straight to a presigned storage URL do not go through it.
+
+  `matchRoute(url)` is the reverse of what the client does when it builds a URL. It returns the API route the URL names (`'/v1/{contentType}/{id}'`), its decoded path parameters and its query, or `null` for a URL that is not a RelyIO API route. If your `baseUrl` has a path of its own, pass it as `matchRoute(url, { baseUrl })`.
+
+  `snapToLadder(width)` rounds an image dimension to the sizes the RelyIO CDN renders: the nearest multiple of `IMAGE_LADDER.bucket` (100), from 100 up to `IMAGE_LADDER.maxDimension` (5000). The CDN snaps every requested width the same way, so snapping first means two widths that render the same image also share one URL and one cache entry.
+
+  `RELYIO_CHANGE_EVENT` (`'relyio:change'`) is the name of the DOM event a RelyIO preview surface dispatches on `window` when content on the page has changed. Listen for it by this constant rather than by the string: `@relyio/next`'s `<RelyIORefresh />` does.
+
+  The `cache` option still configures nothing: the client keeps no response cache of its own, so every call reaches `fetch`.
+
+- 745103e: `createClient()` is typed by your schema without a generic or a `schema:` option, once `relyio generate-types` has run.
+
+  `@relyio/sdk` now exports an empty `Register` interface. The `schema.ts` that `relyio generate-types` writes fills it in, and from then on:
+
+  ```ts
+  import { createClient } from '@relyio/sdk'
+
+  const relyio = createClient({ apiKey: process.env.RELYIO_API_KEY! })
+
+  relyio.content('article') // content type, singleton, settings group and query names autocomplete
+  ```
+
+  `schema.ts` only has to be part of your TypeScript program, which it is if your `tsconfig.json` includes it or anything imports from it. Passing `schema:` or an explicit generic works exactly as before, and either one takes precedence over the registered schema.
+
+  **If you have not run the generator,** `createClient({ apiKey })` returns `TypedRelyIOClient<undefined>`, the untyped client: every name is accepted and entries are typed as `BaseContent`. Previously the call resolved to `TypedRelyIOClient<SchemaDefinition<any, …>>`, a client that claimed a schema it did not have. Code that named that type explicitly needs to name `TypedRelyIOClient<undefined>` instead.
+
+  **Also fixed:** on a client typed by a schema, `settings()`, `asset()` and `withLocale()` accepted no argument at all, because the settings groups, asset types and locales are optional parts of a schema and their names resolved to `never`. They now accept the schema's names.
+
+- cf979dd: **Breaking:** `@relyio/sdk/react` is removed, and the package no longer declares `react` as a peer dependency. `relyioField` is added to `@relyio/sdk`.
+
+  The `@relyio/sdk/react` subpath exported nothing. It existed so that an import of it would resolve, and it carried an optional `react` peer and a React type dependency for that alone. It now fails to resolve with `ERR_PACKAGE_PATH_NOT_EXPORTED`.
+
+  **If you imported it:** delete the import. Nothing was exported from it, so nothing that used it needs a replacement. React hooks for RelyIO will ship as their own package, `@relyio/react`.
+
+  `relyioField(entry, field)` returns the attributes that tie a rendered element to the entry field it shows. Spread them onto that element:
+
+  ```tsx
+  import { relyioField } from '@relyio/sdk'
+
+  // `post` is an entry the client returned, e.g. from `relyio.content('post').fetchOne(id)`
+  ;<h1 {...relyioField(post, 'title')}>{post.title}</h1>
+  // → data-relyio-entry="6710f…" data-relyio-type="post" data-relyio-field="title"
+  //   data-relyio-locale="en-US" data-relyio-v="1"
+  ```
+
+  The entry id, content type and locale all come from the entry itself, so the element is tied to the locale its value was actually served in. With a typed schema, `field` autocompletes to the content type's field names and a misspelt name does not compile. Without one, any field name is accepted. The helper throws a `TypeError` when the entry has no `_metadata.id`, `_metadata.type` or `_metadata.locale`. Every entry the API returns has all three, so that only happens with an object that did not come from RelyIO.
+
+  The attribute set is fixed at these five. `data-relyio-v` is the version of the set, and any future change to the attributes will bump it.
+
+## 0.3.0
+
+### Minor Changes
+
+- a8ae363: **Breaking:** `schemaToJSON`, `viewToJSON` and `workflowToJSON` are removed from `@relyio/sdk` and `@relyio/sdk/schema`.
+
+  These converted a schema definition to JSON by stripping the internal `_tag` markers the `define*` helpers attach. Their docstrings described them as being "for the CLI", but the CLI never called them — it has always done the conversion itself, and the two implementations had drifted: the SDK's stripped a single level where the CLI's recurses. A nested content type, component or field kept its `_tag`, so anything built on these functions produced a payload `relyio deploy` would not have produced.
+
+  **If you were calling one of them:** you almost certainly do not need a replacement. `relyio deploy` and `relyio diff` read your schema module and perform the conversion themselves, so passing them a `defineSchema(...)` value is all that is required — as it was before.
+
+  If you need the JSON for something else, such as committing a snapshot or sending it to your own tooling, strip `_tag` **recursively**:
+
+  ```ts
+  function stripTags(value: unknown): unknown {
+    if (Array.isArray(value)) return value.map(stripTags)
+    if (value && typeof value === 'object') {
+      return Object.fromEntries(
+        Object.entries(value)
+          .filter(([key]) => key !== '_tag')
+          .map(([key, entry]) => [key, stripTags(entry)]),
+      )
+    }
+    return value
+  }
+  ```
+
+  That mirrors what the CLI does, so its output matches the payload `relyio deploy` sends. Note that it is a plain recursive walk: values that are not JSON to begin with, such as a `Date`, become `{}` — as they do on the deploy path today.
+
+  Everything you author with is unchanged. `defineSchema`, `defineContentType`, `defineSingleton`, `defineComponent`, `defineSettingsGroup`, `defineQuery`, `defineAssetType`, `defineLocale`, `defineRole`, `defineWorkflow` and `defineView` keep their signatures and their inferred types, and each now has a fixture asserted against the same validator the platform applies at deploy — so an authoring shape the platform would reject fails when we build the SDK rather than when you run `relyio deploy`.
+
 ## 0.2.1
 
 ### Patch Changes