@sanity/client 0.0.0-dev.0

package/src/data/transaction.ts

@@ -0,0 +1,358 @@
+import type {Observable} from 'rxjs'
+
+import type {ObservableSanityClient, SanityClient} from '../SanityClient'
+import type {
+  Any,
+  BaseMutationOptions,
+  IdentifiedSanityDocumentStub,
+  MultipleMutationResult,
+  Mutation,
+  PatchOperations,
+  SanityDocument,
+  SanityDocumentStub,
+  SingleMutationResult,
+  TransactionAllDocumentIdsMutationOptions,
+  TransactionAllDocumentsMutationOptions,
+  TransactionFirstDocumentIdMutationOptions,
+  TransactionFirstDocumentMutationOptions,
+} from '../types'
+import * as validators from '../validators'
+import {ObservablePatch, Patch} from './patch'
+
+/** @public */
+export type PatchBuilder = (patch: Patch) => Patch
+/** @public */
+export type ObservablePatchBuilder = (patch: ObservablePatch) => ObservablePatch
+
+const defaultMutateOptions = {returnDocuments: false}
+
+/** @internal */
+export class BaseTransaction {
+  protected operations: Mutation[]
+  protected trxId?: string
+  constructor(operations: Mutation[] = [], transactionId?: string) {
+    this.operations = operations
+    this.trxId = transactionId
+  }
+  /**
+   * Creates a new Sanity document. If `_id` is provided and already exists, the mutation will fail. If no `_id` is given, one will automatically be generated by the database.
+   * The operation is added to the current transaction, ready to be commited by `commit()`
+   *
+   * @param doc - Document to create. Requires a `_type` property.
+   */
+  create<R extends Record<string, Any> = Record<string, Any>>(doc: SanityDocumentStub<R>): this {
+    validators.validateObject('create', doc)
+    return this._add({create: doc})
+  }
+
+  /**
+   * Creates a new Sanity document. If a document with the same `_id` already exists, the create operation will be ignored.
+   * The operation is added to the current transaction, ready to be commited by `commit()`
+   *
+   * @param doc - Document to create if it does not already exist. Requires `_id` and `_type` properties.
+   */
+  createIfNotExists<R extends Record<string, Any> = Record<string, Any>>(
+    doc: IdentifiedSanityDocumentStub<R>
+  ): this {
+    const op = 'createIfNotExists'
+    validators.validateObject(op, doc)
+    validators.requireDocumentId(op, doc)
+    return this._add({[op]: doc})
+  }
+
+  /**
+   * Creates a new Sanity document, or replaces an existing one if the same `_id` is already used.
+   * The operation is added to the current transaction, ready to be commited by `commit()`
+   *
+   * @param doc - Document to create or replace. Requires `_id` and `_type` properties.
+   */
+  createOrReplace<R extends Record<string, Any> = Record<string, Any>>(
+    doc: IdentifiedSanityDocumentStub<R>
+  ): this {
+    const op = 'createOrReplace'
+    validators.validateObject(op, doc)
+    validators.requireDocumentId(op, doc)
+    return this._add({[op]: doc})
+  }
+
+  /**
+   * Deletes the document with the given document ID
+   * The operation is added to the current transaction, ready to be commited by `commit()`
+   *
+   * @param documentId - Document ID to delete
+   */
+  delete(documentId: string): this {
+    validators.validateDocumentId('delete', documentId)
+    return this._add({delete: {id: documentId}})
+  }
+
+  /**
+   * Gets the current transaction ID, if any
+   */
+  transactionId(): string | undefined
+  /**
+   * Set the ID of this transaction.
+   *
+   * @param id - Transaction ID
+   */
+  transactionId(id: string): this
+  transactionId(id?: string): this | string | undefined {
+    if (!id) {
+      return this.trxId
+    }
+
+    this.trxId = id
+    return this
+  }
+
+  /**
+   * Return a plain JSON representation of the transaction
+   */
+  serialize(): Mutation[] {
+    return [...this.operations]
+  }
+
+  /**
+   * Return a plain JSON representation of the transaction
+   */
+  toJSON(): Mutation[] {
+    return this.serialize()
+  }
+
+  /**
+   * Clears the transaction of all operations
+   */
+  reset(): this {
+    this.operations = []
+    return this
+  }
+
+  protected _add(mut: Mutation): this {
+    this.operations.push(mut)
+    return this
+  }
+}
+
+/** @public */
+export class Transaction extends BaseTransaction {
+  #client?: SanityClient
+  constructor(operations?: Mutation[], client?: SanityClient, transactionId?: string) {
+    super(operations, transactionId)
+    this.#client = client
+  }
+
+  /**
+   * Clones the transaction
+   */
+  clone(): Transaction {
+    return new Transaction([...this.operations], this.#client, this.trxId)
+  }
+
+  /**
+   * Commit the transaction, returning a promise that resolves to the first mutated document
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit<R extends Record<string, Any>>(
+    options: TransactionFirstDocumentMutationOptions
+  ): Promise<SanityDocument<R>>
+  /**
+   * Commit the transaction, returning a promise that resolves to an array of the mutated documents
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit<R extends Record<string, Any>>(
+    options: TransactionAllDocumentsMutationOptions
+  ): Promise<SanityDocument<R>[]>
+  /**
+   * Commit the transaction, returning a promise that resolves to a mutation result object
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit(options: TransactionFirstDocumentIdMutationOptions): Promise<SingleMutationResult>
+  /**
+   * Commit the transaction, returning a promise that resolves to a mutation result object
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit(options: TransactionAllDocumentIdsMutationOptions): Promise<MultipleMutationResult>
+  /**
+   * Commit the transaction, returning a promise that resolves to a mutation result object
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit(options?: BaseMutationOptions): Promise<MultipleMutationResult>
+  commit<R extends Record<string, Any> = Record<string, Any>>(
+    options?:
+      | TransactionFirstDocumentMutationOptions
+      | TransactionAllDocumentsMutationOptions
+      | TransactionFirstDocumentIdMutationOptions
+      | TransactionAllDocumentIdsMutationOptions
+      | BaseMutationOptions
+  ): Promise<
+    SanityDocument<R> | SanityDocument<R>[] | SingleMutationResult | MultipleMutationResult
+  > {
+    if (!this.#client) {
+      throw new Error(
+        'No `client` passed to transaction, either provide one or pass the ' +
+          'transaction to a clients `mutate()` method'
+      )
+    }
+
+    return this.#client.mutate<R>(
+      this.serialize() as Any,
+      Object.assign({transactionId: this.trxId}, defaultMutateOptions, options || {})
+    )
+  }
+
+  /**
+   * Performs a patch on the given document ID. Can either be a builder function or an object of patch operations.
+   * The operation is added to the current transaction, ready to be commited by `commit()`
+   *
+   * @param documentId - Document ID to perform the patch operation on
+   * @param patchOps - Operations to perform, or a builder function
+   */
+  patch(documentId: string, patchOps?: PatchBuilder | PatchOperations): this
+  /**
+   * Adds the given patch instance to the transaction.
+   * The operation is added to the current transaction, ready to be commited by `commit()`
+   *
+   * @param patch - Patch to execute
+   */
+  patch(patch: Patch): this
+  patch(patchOrDocumentId: Patch | string, patchOps?: PatchBuilder | PatchOperations): this {
+    const isBuilder = typeof patchOps === 'function'
+    const isPatch = typeof patchOrDocumentId !== 'string' && patchOrDocumentId instanceof Patch
+
+    // transaction.patch(client.patch('documentId').inc({visits: 1}))
+    if (isPatch) {
+      return this._add({patch: patchOrDocumentId.serialize()})
+    }
+
+    // patch => patch.inc({visits: 1}).set({foo: 'bar'})
+    if (isBuilder) {
+      const patch = patchOps(new Patch(patchOrDocumentId, {}, this.#client))
+      if (!(patch instanceof Patch)) {
+        throw new Error('function passed to `patch()` must return the patch')
+      }
+
+      return this._add({patch: patch.serialize()})
+    }
+
+    return this._add({patch: {id: patchOrDocumentId, ...patchOps}})
+  }
+}
+
+/** @public */
+export class ObservableTransaction extends BaseTransaction {
+  #client?: ObservableSanityClient
+  constructor(operations?: Mutation[], client?: ObservableSanityClient, transactionId?: string) {
+    super(operations, transactionId)
+    this.#client = client
+  }
+
+  /**
+   * Clones the transaction
+   */
+  clone(): ObservableTransaction {
+    return new ObservableTransaction([...this.operations], this.#client, this.trxId)
+  }
+
+  /**
+   * Commit the transaction, returning an observable that produces the first mutated document
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit<R extends Record<string, Any>>(
+    options: TransactionFirstDocumentMutationOptions
+  ): Observable<SanityDocument<R>>
+  /**
+   * Commit the transaction, returning an observable that produces an array of the mutated documents
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit<R extends Record<string, Any>>(
+    options: TransactionAllDocumentsMutationOptions
+  ): Observable<SanityDocument<R>[]>
+  /**
+   * Commit the transaction, returning an observable that produces a mutation result object
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit(options: TransactionFirstDocumentIdMutationOptions): Observable<SingleMutationResult>
+  /**
+   * Commit the transaction, returning an observable that produces a mutation result object
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit(options: TransactionAllDocumentIdsMutationOptions): Observable<MultipleMutationResult>
+  /**
+   * Commit the transaction, returning an observable that produces a mutation result object
+   *
+   * @param options - Options for the mutation operation
+   */
+  commit(options?: BaseMutationOptions): Observable<MultipleMutationResult>
+  commit<R extends Record<string, Any> = Record<string, Any>>(
+    options?:
+      | TransactionFirstDocumentMutationOptions
+      | TransactionAllDocumentsMutationOptions
+      | TransactionFirstDocumentIdMutationOptions
+      | TransactionAllDocumentIdsMutationOptions
+      | BaseMutationOptions
+  ): Observable<
+    SanityDocument<R> | SanityDocument<R>[] | SingleMutationResult | MultipleMutationResult
+  > {
+    if (!this.#client) {
+      throw new Error(
+        'No `client` passed to transaction, either provide one or pass the ' +
+          'transaction to a clients `mutate()` method'
+      )
+    }
+
+    return this.#client.mutate<R>(
+      this.serialize() as Any,
+      Object.assign({transactionId: this.trxId}, defaultMutateOptions, options || {})
+    )
+  }
+
+  /**
+   * Performs a patch on the given document ID. Can either be a builder function or an object of patch operations.
+   * The operation is added to the current transaction, ready to be commited by `commit()`
+   *
+   * @param documentId - Document ID to perform the patch operation on
+   * @param patchOps - Operations to perform, or a builder function
+   */
+  patch(documentId: string, patchOps?: ObservablePatchBuilder | PatchOperations): this
+  /**
+   * Adds the given patch instance to the transaction.
+   * The operation is added to the current transaction, ready to be commited by `commit()`
+   *
+   * @param patch - ObservablePatch to execute
+   */
+  patch(patch: ObservablePatch): this
+  patch(
+    patchOrDocumentId: ObservablePatch | string,
+    patchOps?: ObservablePatchBuilder | PatchOperations
+  ): this {
+    const isBuilder = typeof patchOps === 'function'
+    const isPatch =
+      typeof patchOrDocumentId !== 'string' && patchOrDocumentId instanceof ObservablePatch
+
+    // transaction.patch(client.patch('documentId').inc({visits: 1}))
+    if (isPatch) {
+      return this._add({patch: patchOrDocumentId.serialize()})
+    }
+
+    // patch => patch.inc({visits: 1}).set({foo: 'bar'})
+    if (isBuilder) {
+      const patch = patchOps(new ObservablePatch(patchOrDocumentId, {}, this.#client))
+      if (!(patch instanceof ObservablePatch)) {
+        throw new Error('function passed to `patch()` must return the patch')
+      }
+
+      return this._add({patch: patch.serialize()})
+    }
+
+    return this._add({patch: {id: patchOrDocumentId, ...patchOps}})
+  }
+}

package/src/datasets/DatasetsClient.ts

@@ -0,0 +1,115 @@
+import {lastValueFrom, type Observable} from 'rxjs'
+
+import {_request} from '../data/dataMethods'
+import type {ObservableSanityClient, SanityClient} from '../SanityClient'
+import type {DatasetAclMode, DatasetResponse, DatasetsResponse, HttpRequest} from '../types'
+import * as validate from '../validators'
+
+/** @internal */
+export class ObservableDatasetsClient {
+  #client: ObservableSanityClient
+  #httpRequest: HttpRequest
+  constructor(client: ObservableSanityClient, httpRequest: HttpRequest) {
+    this.#client = client
+    this.#httpRequest = httpRequest
+  }
+
+  /**
+   * Create a new dataset with the given name
+   *
+   * @param name - Name of the dataset to create
+   * @param options - Options for the dataset
+   */
+  create(name: string, options?: {aclMode?: DatasetAclMode}): Observable<DatasetResponse> {
+    return _modify<DatasetResponse>(this.#client, this.#httpRequest, 'PUT', name, options)
+  }
+
+  /**
+   * Edit a dataset with the given name
+   *
+   * @param name - Name of the dataset to edit
+   * @param options - New options for the dataset
+   */
+  edit(name: string, options?: {aclMode?: DatasetAclMode}): Observable<DatasetResponse> {
+    return _modify<DatasetResponse>(this.#client, this.#httpRequest, 'PATCH', name, options)
+  }
+
+  /**
+   * Delete a dataset with the given name
+   *
+   * @param name - Name of the dataset to delete
+   */
+  delete(name: string): Observable<{deleted: true}> {
+    return _modify<{deleted: true}>(this.#client, this.#httpRequest, 'DELETE', name)
+  }
+
+  /**
+   * Fetch a list of datasets for the configured project
+   */
+  list(): Observable<DatasetsResponse> {
+    return _request<DatasetsResponse>(this.#client, this.#httpRequest, {uri: '/datasets'})
+  }
+}
+
+/** @internal */
+export class DatasetsClient {
+  #client: SanityClient
+  #httpRequest: HttpRequest
+  constructor(client: SanityClient, httpRequest: HttpRequest) {
+    this.#client = client
+    this.#httpRequest = httpRequest
+  }
+
+  /**
+   * Create a new dataset with the given name
+   *
+   * @param name - Name of the dataset to create
+   * @param options - Options for the dataset
+   */
+  create(name: string, options?: {aclMode?: DatasetAclMode}): Promise<DatasetResponse> {
+    return lastValueFrom(
+      _modify<DatasetResponse>(this.#client, this.#httpRequest, 'PUT', name, options)
+    )
+  }
+
+  /**
+   * Edit a dataset with the given name
+   *
+   * @param name - Name of the dataset to edit
+   * @param options - New options for the dataset
+   */
+  edit(name: string, options?: {aclMode?: DatasetAclMode}): Promise<DatasetResponse> {
+    return lastValueFrom(
+      _modify<DatasetResponse>(this.#client, this.#httpRequest, 'PATCH', name, options)
+    )
+  }
+
+  /**
+   * Delete a dataset with the given name
+   *
+   * @param name - Name of the dataset to delete
+   */
+  delete(name: string): Promise<{deleted: true}> {
+    return lastValueFrom(_modify<{deleted: true}>(this.#client, this.#httpRequest, 'DELETE', name))
+  }
+
+  /**
+   * Fetch a list of datasets for the configured project
+   */
+  list(): Promise<DatasetsResponse> {
+    return lastValueFrom(
+      _request<DatasetsResponse>(this.#client, this.#httpRequest, {uri: '/datasets'})
+    )
+  }
+}
+
+function _modify<R = unknown>(
+  client: SanityClient | ObservableSanityClient,
+  httpRequest: HttpRequest,
+  method: 'DELETE' | 'PATCH' | 'PUT',
+  name: string,
+  options?: {aclMode?: DatasetAclMode}
+) {
+  validate.dataset(name)
+  return _request<R>(client, httpRequest, {method, uri: `/datasets/${name}`, body: options})
+}

package/src/generateHelpUrl.ts

@@ -0,0 +1,5 @@
+const BASE_URL = 'https://www.sanity.io/help/'
+
+export function generateHelpUrl(slug: string) {
+  return BASE_URL + slug
+}

package/src/http/browserMiddleware.ts

@@ -0,0 +1 @@
+export default []

package/src/http/errors.ts

@@ -0,0 +1,68 @@
+import type {Any, ErrorProps} from '../types'
+
+/** @public */
+export class ClientError extends Error {
+  response: ErrorProps['response']
+  statusCode: ErrorProps['statusCode'] = 400
+  responseBody: ErrorProps['responseBody']
+  details: ErrorProps['details']
+
+  constructor(res: Any) {
+    const props = extractErrorProps(res)
+    super(props.message)
+    Object.assign(this, props)
+  }
+}
+
+/** @public */
+export class ServerError extends Error {
+  response: ErrorProps['response']
+  statusCode: ErrorProps['statusCode'] = 500
+  responseBody: ErrorProps['responseBody']
+  details: ErrorProps['details']
+
+  constructor(res: Any) {
+    const props = extractErrorProps(res)
+    super(props.message)
+    Object.assign(this, props)
+  }
+}
+
+function extractErrorProps(res: Any): ErrorProps {
+  const body = res.body
+  const props = {
+    response: res,
+    statusCode: res.statusCode,
+    responseBody: stringifyBody(body, res),
+    message: '',
+    details: undefined as Any,
+  }
+
+  // API/Boom style errors ({statusCode, error, message})
+  if (body.error && body.message) {
+    props.message = `${body.error} - ${body.message}`
+    return props
+  }
+
+  // Query/database errors ({error: {description, other, arb, props}})
+  if (body.error && body.error.description) {
+    props.message = body.error.description
+    props.details = body.error
+    return props
+  }
+
+  // Other, more arbitrary errors
+  props.message = body.error || body.message || httpErrorMessage(res)
+  return props
+}
+
+function httpErrorMessage(res: Any) {
+  const statusMessage = res.statusMessage ? ` ${res.statusMessage}` : ''
+  return `${res.method}-request to ${res.url} resulted in HTTP ${res.statusCode}${statusMessage}`
+}
+
+function stringifyBody(body: Any, res: Any) {
+  const contentType = (res.headers['content-type'] || '').toLowerCase()
+  const isJson = contentType.indexOf('application/json') !== -1
+  return isJson ? JSON.stringify(body, null, 2) : body
+}

package/src/http/nodeMiddleware.ts

@@ -0,0 +1,11 @@
+import {debug, headers, retry} from 'get-it/middleware'
+
+import {name, version} from '../../package.json'
+
+const middleware = [
+  debug({verbose: true, namespace: 'sanity:client'}),
+  headers({'User-Agent': `${name} ${version}`}),
+  retry({maxRetries: 3}),
+]
+
+export default middleware

package/src/http/request.ts

@@ -0,0 +1,48 @@
+import {getIt, type Middlewares} from 'get-it'
+import {jsonRequest, jsonResponse, observable, progress} from 'get-it/middleware'
+import {Observable} from 'rxjs'
+
+import type {Any, HttpRequest, RequestOptions} from '../types'
+import {ClientError, ServerError} from './errors'
+
+const httpError = {
+  onResponse: (res: Any) => {
+    if (res.statusCode >= 500) {
+      throw new ServerError(res)
+    } else if (res.statusCode >= 400) {
+      throw new ClientError(res)
+    }
+
+    return res
+  },
+}
+
+const printWarnings = {
+  onResponse: (res: Any) => {
+    const warn = res.headers['x-sanity-warning']
+    const warnings = Array.isArray(warn) ? warn : [warn]
+    warnings.filter(Boolean).forEach((msg) => console.warn(msg)) // eslint-disable-line no-console
+    return res
+  },
+}
+
+/** @internal */
+export function defineHttpRequest(envMiddleware: Middlewares): HttpRequest {
+  const request = getIt([
+    ...envMiddleware,
+    printWarnings,
+    jsonRequest(),
+    jsonResponse(),
+    progress(),
+    httpError,
+    observable({implementation: Observable}),
+  ])
+
+  function httpRequest(options: RequestOptions, requester = request) {
+    return requester({maxRedirects: 0, ...options} as Any)
+  }
+
+  httpRequest.defaultRequester = request
+
+  return httpRequest
+}

package/src/http/requestOptions.ts

@@ -0,0 +1,33 @@
+import type {RequestOptions} from 'get-it'
+
+import type {Any} from '../types'
+
+const projectHeader = 'X-Sanity-Project-ID'
+
+export function requestOptions(config: Any, overrides: Any = {}): Omit<RequestOptions, 'url'> {
+  const headers: Any = {}
+
+  const token = overrides.token || config.token
+  if (token) {
+    headers.Authorization = `Bearer ${token}`
+  }
+
+  if (!overrides.useGlobalApi && !config.useProjectHostname && config.projectId) {
+    headers[projectHeader] = config.projectId
+  }
+
+  const withCredentials = Boolean(
+    typeof overrides.withCredentials === 'undefined'
+      ? config.token || config.withCredentials
+      : overrides.withCredentials
+  )
+
+  const timeout = typeof overrides.timeout === 'undefined' ? config.timeout : overrides.timeout
+  return Object.assign({}, overrides, {
+    headers: Object.assign({}, headers, overrides.headers || {}),
+    timeout: typeof timeout === 'undefined' ? 5 * 60 * 1000 : timeout,
+    proxy: overrides.proxy || config.proxy,
+    json: true,
+    withCredentials,
+  })
+}

package/src/index.browser.ts

@@ -0,0 +1,28 @@
+import envMiddleware from './http/browserMiddleware'
+import {defineHttpRequest} from './http/request'
+import {SanityClient} from './SanityClient'
+import type {ClientConfig} from './types'
+import {printNoDefaultExport} from './warnings'
+
+export * from './data/patch'
+export * from './data/transaction'
+export {ClientError, ServerError} from './http/errors'
+export * from './SanityClient'
+export * from './types'
+
+// Set the http client to use for requests, and its environment specific middleware
+const httpRequest = defineHttpRequest(envMiddleware)
+/** @public */
+export const requester = httpRequest.defaultRequester
+
+/** @public */
+export const createClient = (config: ClientConfig) => new SanityClient(httpRequest, config)
+
+/**
+ * @public
+ * @deprecated Use the named export `createClient` instead of the `default` export
+ */
+export default function deprecatedCreateClient(config: ClientConfig) {
+  printNoDefaultExport()
+  return new SanityClient(httpRequest, config)
+}