@sanity/client 5.4.2 → 5.4.3-dev.1

package/README.md

@@ -26,8 +26,8 @@ import {createClient} from '@sanity/client'
 export const client = createClient({
   projectId: 'your-project-id',
   dataset: 'your-dataset-name',
-  useCdn: false, // set to `true` to fetch from edge cache
-  apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
+  useCdn: true, // set to `false` to bypass the edge cache
+  apiVersion: '2023-05-03', // use current date (YYYY-MM-DD) to target the latest API version
   // token: process.env.SANITY_SECRET_TOKEN // Only if you want to update content with the client
 })
 
@@ -65,6 +65,7 @@ export async function updateDocumentTitle(_id, title) {
     - [UMD](#umd)
   - [Specifying API version](#specifying-api-version)
   - [Performing queries](#performing-queries)
+  - [Get started with Content Source Maps](#get-started-with-content-source-maps)
   - [Listening to queries](#listening-to-queries)
   - [Fetch a single document](#fetch-a-single-document)
   - [Fetch multiple documents in one go](#fetch-multiple-documents-in-one-go)
@@ -93,7 +94,9 @@ export async function updateDocumentTitle(_id, title) {
   - [Set client configuration](#set-client-configuration)
 - [Release new version](#release-new-version)
 - [License](#license)
-- [From `v4`](#from-v4)
+- [Migrate](#migrate)
+  - [From `v5`](#from-v5)
+  - [From `v4`](#from-v4)
 
 ## Requirements
 
@@ -119,7 +122,7 @@ pnpm install @sanity/client
 
 `const client = createClient(options)`
 
-Initializes a new Sanity Client. Required options are `projectId`, `dataset`, and `apiVersion`. Setting a value for `useCdn` is encouraged. Typically you want to have it as `false` in development to always fetch the freshest content and `true` in production environments so that content is fetched from the distributed cache. [You can learn more about the API CDN here][api-cdn].
+Initializes a new Sanity Client. Required options are `projectId`, `dataset`, and `apiVersion`. [We encourage setting `useCdn` to either `true` or `false`.](https://www.sanity.io/help/js-client-cdn-configuration) The default is `true`. If you're not sure which option to choose we recommend starting with `true` and revise later if you find that you require uncached content. [Our awesome Slack community can help guide you on how to avoid stale data tailored to your tech stack and architecture.](https://slack.sanity.io/)
 
 #### [ESM](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/)
 
@@ -129,8 +132,8 @@ import {createClient} from '@sanity/client'
 const client = createClient({
   projectId: 'your-project-id',
   dataset: 'your-dataset-name',
-  useCdn: false, // set to `true` to fetch from edge cache
-  apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
+  useCdn: true, // set to `false` to bypass the edge cache
+  apiVersion: '2023-05-03', // use current date (YYYY-MM-DD) to target the latest API version
 })
 
 const data = await client.fetch(`count(*)`)
@@ -145,8 +148,8 @@ const {createClient} = require('@sanity/client')
 const client = createClient({
   projectId: 'your-project-id',
   dataset: 'your-dataset-name',
-  useCdn: false, // set to `true` to fetch from edge cache
-  apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
+  useCdn: true, // set to `false` to bypass the edge cache
+  apiVersion: '2023-05-03', // use current date (YYYY-MM-DD) to target the latest API version
 })
 
 client
@@ -163,8 +166,8 @@ import {createClient, type ClientConfig} from '@sanity/client'
 const config: ClientConfig = {
   projectId: 'your-project-id',
   dataset: 'your-dataset-name',
-  useCdn: false, // set to `true` to fetch from edge cache
-  apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
+  useCdn: true, // set to `false` to bypass the edge cache
+  apiVersion: '2023-05-03', // use current date (YYYY-MM-DD) to target the latest API version
 }
 const client = createClient(config)
 
@@ -183,8 +186,8 @@ import {z} from 'zod'
 const client = createClient({
   projectId: 'your-project-id',
   dataset: 'your-dataset-name',
-  useCdn: false, // set to `true` to fetch from edge cache
-  apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
+  useCdn: true, // set to `false` to bypass the edge cache
+  apiVersion: '2023-05-03', // use current date (YYYY-MM-DD) to target the latest API version
 })
 
 const schema = z.number()
@@ -210,8 +213,8 @@ import {createClient} from '@sanity/client'
 const client = createClient({
   projectId: 'your-project-id',
   dataset: 'your-dataset-name',
-  useCdn: false, // set to `true` to fetch from edge cache
-  apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
+  useCdn: true, // set to `false` to bypass the edge cache
+  apiVersion: '2023-05-03', // use current date (YYYY-MM-DD) to target the latest API version
 })
 
 const data = await client.fetch<number>(`count(*)`)
@@ -238,8 +241,8 @@ import {createClient} from 'https://esm.sh/@sanity/client'
 const client = createClient({
   projectId: 'your-project-id',
   dataset: 'your-dataset-name',
-  useCdn: false, // set to `true` to fetch from edge cache
-  apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
+  useCdn: true, // set to `false` to bypass the edge cache
+  apiVersion: '2023-05-03', // use current date (YYYY-MM-DD) to target the latest API version
 })
 
 const data = await client.fetch<number>(`count(*)`)
@@ -271,8 +274,8 @@ export default async function handler(req: NextRequest) {
   const client = createClient({
     projectId: 'your-project-id',
     dataset: 'your-dataset-name',
-    useCdn: false, // set to `true` to fetch from edge cache
-    apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
+    useCdn: true, // set to `false` to bypass the edge cache
+    apiVersion: '2023-05-03', // use current date (YYYY-MM-DD) to target the latest API version
   })
 
   const count = await client.fetch<number>(`count(*)`)
@@ -302,8 +305,8 @@ Using [esm.sh] you can either load the client using a `<script type="module">` t
   const client = createClient({
     projectId: 'your-project-id',
     dataset: 'your-dataset-name',
-    useCdn: false, // set to `true` to fetch from edge cache
-    apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
+    useCdn: true, // set to `false` to bypass the edge cache
+    apiVersion: '2023-05-03', // use current date (YYYY-MM-DD) to target the latest API version
   })
 
   const data = await client.fetch(`count(*)`)
@@ -321,8 +324,8 @@ const {createClient} = await import('https://esm.sh/@sanity/client')
 const client = createClient({
   projectId: 'your-project-id',
   dataset: 'your-dataset-name',
-  useCdn: false, // set to `true` to fetch from edge cache
-  apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
+  useCdn: true, // set to `false` to bypass the edge cache
+  apiVersion: '2023-05-03', // use current date (YYYY-MM-DD) to target the latest API version
 })
 
 const data = await client.fetch(`count(*)`)
@@ -343,8 +346,8 @@ Loading the UMD script creates a `SanityClient` global that have the same export
   const client = createClient({
     projectId: 'your-project-id',
     dataset: 'your-dataset-name',
-    useCdn: false, // set to `true` to fetch from edge cache
-    apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
+    useCdn: true, // set to `false` to bypass the edge cache
+    apiVersion: '2023-05-03', // use current date (YYYY-MM-DD) to target the latest API version
   })
 
   client.fetch(`count(*)`).then((data) => console.log(`Number of documents: ${data}`))
@@ -364,8 +367,8 @@ The `require-unpkg` library lets you consume `npm` packages from `unpkg.com` sim
     const client = createClient({
       projectId: 'your-project-id',
       dataset: 'your-dataset-name',
-      useCdn: false, // set to `true` to fetch from edge cache
-      apiVersion: '2022-01-12', // use current date (YYYY-MM-DD) to target the latest API version
+      useCdn: true, // set to `false` to bypass the edge cache
+      apiVersion: '2023-05-03', // use current date (YYYY-MM-DD) to target the latest API version
     })
 
     const data = await client.fetch(`count(*)`)
@@ -402,6 +405,58 @@ client.fetch(query, params).then((bikes) => {
 
 Perform a query using the given parameters (if any).
 
+### Get started with Content Source Maps
+
+> **Note**
+>
+> [Content Source Maps][content-source-maps-intro] are available [as an API][content-source-maps] for select [Sanity enterprise customers][enterprise-cta]. [Contact our sales team for more information.][sales-cta]
+
+[Visual editing][visual-editing] is available in [`@sanity/preview-kit/client`][preview-kit-client]. It offers both a turn-key solution and a flexible API for custom experiences.
+
+This guide is for developers who want to build custom use cases beyond, or in addition to, [visual editing][visual-editing]. Read the [Content Source Maps introduction][content-source-maps-intro] before diving in, and keep the [Content Source Maps reference][content-source-maps] handy.
+
+Enabling Content Source Maps is a two-step process:
+
+1. Update your client configuration with `resultSourceMap`.
+
+   ```js
+   import {createClient} from '@sanity/client'
+
+   const client = createClient({
+     projectId: 'your-project-id',
+     dataset: 'your-dataset-name',
+     useCdn: true, // set to `false` to bypass the edge cache
+     apiVersion: '2023-05-03', // use current date (YYYY-MM-DD) to target the latest API version
+     resultSourceMap: true, // tells the API to start sending source maps, if available
+   })
+   ```
+
+2. On `client.fetch` calls add `{filterResponse: false}` to return the full response on queries.
+
+   ```js
+   // Before
+   // const result = await client.fetch(query, params)
+
+   // After adding `filterResponse: false`
+   const {result, resultSourceMap} = await client.fetch(query, params, {filterResponse: false})
+   // Build something cool with the source map
+   console.log(resultSourceMap)
+   ```
+
+Once enabled, the `resultSourceMap` property will always exist on the response, given your `apiVersion` is recent enough. If there is no source map, it will be an empty object. There's also a TypeScript definition for it:
+
+```ts
+import type {ContentSourceMapping} from '@sanity/client'
+
+const {result, resultSourceMap} = await client.fetch(query, params, {filterResponse: false})
+
+function useContentSourceMap(resultSourceMap: ContentSourceMapping): unknown {
+  // Sky's the limit
+}
+
+useContentSourceMap(resultSourceMap)
+```
+
 ### Listening to queries
 
 ```js
@@ -924,6 +979,23 @@ MIT © [Sanity.io](https://www.sanity.io/)
 
 # Migrate
 
+## From `v5`
+
+### The default `useCdn` is changed to `true`
+
+It was previously `false`. If you were relying on the default being `false` you can continue using the live API by setting it in the constructor:
+
+```diff
+import {createClient} from '@sanity/client'
+
+export const client = createClient({
+  projectId: 'your-project-id',
+  dataset: 'your-dataset-name',
+  apiVersion: '2023-03-12',
++ useCdn: false, // set to `true` to use the edge cache
+})
+```
+
 ## From `v4`
 
 ### No longer shipping `ES5`
@@ -1223,3 +1295,9 @@ await client.request<void>({uri: '/auth/logout', method: 'POST'})
 [groqd]: https://github.com/FormidableLabs/groqd#readme
 [AbortSignal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
 [AbortController]: https://developer.mozilla.org/en-US/docs/Web/API/AbortController
+[visual-editing]: https://www.sanity.io/docs/vercel-visual-editing?utm_source=github.com&utm_medium=referral&utm_campaign=may-vercel-launch
+[content-source-maps]: https://www.sanity.io/docs/content-source-maps?utm_source=github.com&utm_medium=referral&utm_campaign=may-vercel-launch
+[content-source-maps-intro]: https://www.sanity.io/blog/content-source-maps-announce?utm_source=github.com&utm_medium=referral&utm_campaign=may-vercel-launch
+[preview-kit-client]: https://github.com/sanity-io/preview-kit#sanitypreview-kitclient
+[sales-cta]: https://www.sanity.io/contact/sales?utm_source=github.com&utm_medium=referral&utm_campaign=may-vercel-launch
+[enterprise-cta]: https://www.sanity.io/enterprise?utm_source=github.com&utm_medium=referral&utm_campaign=may-vercel-launch

package/dist/index.browser.cjs

@@ -93,8 +93,18 @@ const printWarnings = {
     return res;
   }
 };
-function defineHttpRequest(envMiddleware) {
-  const request = getIt.getIt([...envMiddleware, printWarnings, middleware.jsonRequest(), middleware.jsonResponse(), middleware.progress(), httpError, middleware.observable({
+function defineHttpRequest(envMiddleware, _ref) {
+  let {
+    maxRetries = 5,
+    retryDelay
+  } = _ref;
+  const request = getIt.getIt([maxRetries > 0 ? middleware.retry({
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    retryDelay,
+    // This option is typed incorrectly in get-it.
+    maxRetries,
+    shouldRetry
+  }) : {}, ...envMiddleware, printWarnings, middleware.jsonRequest(), middleware.jsonResponse(), middleware.progress(), httpError, middleware.observable({
     implementation: rxjs.Observable
   })]);
   function httpRequest(options) {
@@ -107,6 +117,13 @@ function defineHttpRequest(envMiddleware) {
   httpRequest.defaultRequester = request;
   return httpRequest;
 }
+function shouldRetry(err, attempt, options) {
+  const isSafe = options.method === "GET" || options.method === "HEAD";
+  const isQuery = options.uri.startsWith("/data/query");
+  const isRetriableResponse = err.response && (err.response.statusCode === 429 || err.response.statusCode === 502 || err.response.statusCode === 503);
+  if ((isSafe || isQuery) && isRetriableResponse) return true;
+  return middleware.retry.shouldRetry(err, attempt, options);
+}
 const projectHeader = "X-Sanity-Project-ID";
 function requestOptions(config) {
   let overrides = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
@@ -203,12 +220,12 @@ const requestTag = tag => {
   }
   return tag;
 };
-const encodeQueryString = _ref => {
+const encodeQueryString = _ref2 => {
   let {
     query,
     params = {},
     options = {}
-  } = _ref;
+  } = _ref2;
   const searchParams = new URLSearchParams();
   const {
     tag,
@@ -817,6 +834,12 @@ function _requestObservable(client, httpRequest, options) {
       ...options.query
     };
   }
+  if (config.resultSourceMap) {
+    options.query = {
+      resultSourceMap: true,
+      ...options.query
+    };
+  }
   const reqOptions = requestOptions(config, Object.assign({}, options, {
     url: _getUrl(client, uri, useCdn)
   }));
@@ -993,10 +1016,10 @@ once(function () {
   }
   return console.warn(message.join(" "), ...args);
 });
-const printCdnWarning = createWarningPrinter(["You are not using the Sanity CDN. That means your data is always fresh, but the CDN is faster and", "cheaper. Think about it! For more info, see ".concat(generateHelpUrl("js-client-cdn-configuration"), " "), "To hide this warning, please set the `useCdn` option to either `true` or `false` when creating", "the client."]);
+const printCdnWarning = createWarningPrinter(["Since you haven't set a value for `useCdn`, we will deliver content using our", "global, edge-cached API-CDN. If you wish to have content delivered faster, set", "`useCdn: false` to use the Live API. Note: You may incur higher costs using the live API."]);
 const printBrowserTokenWarning = createWarningPrinter(["You have configured Sanity client to use a token in the browser. This may cause unintentional security issues.", "See ".concat(generateHelpUrl("js-client-browser-token"), " for more information and how to hide this warning.")]);
 const printNoApiVersionSpecifiedWarning = createWarningPrinter(["Using the Sanity client without specifying an API version is deprecated.", "See ".concat(generateHelpUrl("js-client-api-version"))]);
-const printNoDefaultExport = createWarningPrinter(["The default export of @sanity/client has been deprecated. Use the named export `createClient` instead"]);
+const printNoDefaultExport = createWarningPrinter(["The default export of @sanity/client has been deprecated. Use the named export `createClient` instead."]);
 const defaultCdnHost = "apicdn.sanity.io";
 const defaultConfig = {
   apiHost: "https://api.sanity.io",
@@ -1047,7 +1070,7 @@ const initConfig = (config, prevConfig) => {
   }
   newConfig.apiVersion = "".concat(newConfig.apiVersion).replace(/^v/, "");
   newConfig.isDefaultApi = newConfig.apiHost === defaultConfig.apiHost;
-  newConfig.useCdn = Boolean(newConfig.useCdn) && !newConfig.withCredentials;
+  newConfig.useCdn = newConfig.useCdn !== false && !newConfig.withCredentials;
   validateApiVersion(newConfig.apiVersion);
   const hostParts = newConfig.apiHost.split("://", 2);
   const protocol = hostParts[0];
@@ -1724,21 +1747,24 @@ const _SanityClient = class {
     return new Transaction(operations, this);
   }
   /**
-   * DEPRECATED: Perform an HTTP request against the Sanity API
+   * Perform a request against the Sanity API
+   * NOTE: Only use this for Sanity API endpoints, not for your own APIs!
    *
-   * @deprecated Use your own request library!
    * @param options - Request options
+   * @returns Promise resolving to the response body
    */
   request(options) {
     return rxjs.lastValueFrom(_request(this, __privateGet(this, _httpRequest2), options));
   }
   /**
-   * DEPRECATED: Perform an HTTP request a `/data` sub-endpoint
+   * Perform an HTTP request a `/data` sub-endpoint
+   * NOTE: Considered internal, thus marked as deprecated. Use `request` instead.
    *
-   * @deprecated Use your own request library!
+   * @deprecated - Use `request()` or your own HTTP library instead
    * @param endpoint - Endpoint to hit (mutate, query etc)
    * @param body - Request body
    * @param options - Request options
+   * @internal
    */
   dataRequest(endpoint, body, options) {
     return rxjs.lastValueFrom(_dataRequest(this, __privateGet(this, _httpRequest2), endpoint, body, options));
@@ -1765,9 +1791,12 @@ const _SanityClient = class {
 let SanityClient = _SanityClient;
 _clientConfig2 = new WeakMap();
 _httpRequest2 = new WeakMap();
-const httpRequest = defineHttpRequest(envMiddleware);
+const httpRequest = defineHttpRequest(envMiddleware, {});
 const requester = httpRequest.defaultRequester;
-const createClient = config => new SanityClient(httpRequest, config);
+const createClient = config => new SanityClient(defineHttpRequest(envMiddleware, {
+  maxRetries: config.maxRetries,
+  retryDelay: config.retryDelay
+}), config);
 function deprecatedCreateClient(config) {
   printNoDefaultExport();
   return new SanityClient(httpRequest, config);