@sanity/client
Version:
Client for retrieving, creating and patching data from Sanity.io
355 lines (325 loc) • 12.9 kB
text/typescript
import {type FetchFunction} from 'get-it'
import {defer, lastValueFrom, type Observable} from 'rxjs'
import {_request, _requestObservable} from '../data/dataMethods'
import type {ListenEventFromOptions} from '../data/listen'
import type {ObservableSanityClient, SanityClient} from '../SanityClient'
import type {HttpRequest, QueryParams, SanityDocument} from '../types'
import {legacyNamespaces, type LegacyFetch, type LegacyRequest} from './legacy'
import {_fetch as _fetchStore, _listen as _listenStore} from './store'
import type {
ContextListenOptions,
ContextRequestOptions,
CreateFileSourceParams,
FileUpload,
RequestArgs,
Response,
ResponseFormat,
Route,
Source,
SyncAccepted,
UploadFileParams,
} from './types'
type Client = SanityClient | ObservableSanityClient
type ContextRequest = {
params?: Record<string, unknown>
query?: Record<string, unknown>
headers?: Record<string, unknown>
body?: unknown
signal?: AbortSignal
tag?: string
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value)
}
function isContextRequest(value: unknown): value is ContextRequest {
return isRecord(value)
}
function _stringValues(entries: Record<string, unknown> | undefined): Record<string, string> {
const values: Record<string, string> = {}
for (const [key, value] of Object.entries(entries ?? {})) {
if (value !== undefined && value !== null) values[key] = String(value)
}
return values
}
function _pathParam(client: Client, name: string, params: Record<string, unknown>): string {
const value = params[name]
if (typeof value === 'string' && value !== '') return value
if (value !== undefined) {
throw new Error(`\`params.${name}\` must be a non-empty string`)
}
const config = client.config()
if (name === 'knowledgeBaseId' && config.resource?.type === 'knowledge-base') {
return config.resource.id
}
if (name === 'organizationId' && config.context?.organizationId) {
return config.context.organizationId
}
if (name === 'knowledgeBaseId') {
throw new Error(
'`params.knowledgeBaseId` is required unless a `knowledge-base` resource is configured',
)
}
if (name === 'organizationId') {
throw new Error(
'`params.organizationId` is required unless `context.organizationId` is configured',
)
}
throw new Error(`\`params.${name}\` is required`)
}
/**
* The request options for a `METHOD /path` route: path parameters filled in
* and encoded, query and headers stringified, `undefined` values left out.
*/
function _contextRequestOptions(client: Client, route: string, init: unknown) {
const request = isContextRequest(init) ? init : {}
const separator = route.indexOf(' ')
const method = route.slice(0, separator)
const params = request.params ?? {}
const path = route
.slice(separator + 1)
.replace(/\{([^}]+)\}/g, (_match, name: string) =>
encodeURIComponent(_pathParam(client, name, params)),
)
return {
url: `/context${path}`,
method,
query: _stringValues(request.query),
headers: _stringValues(request.headers),
...(request.body !== undefined && {body: request.body}),
signal: request.signal,
tag: request.tag,
}
}
function _fetchBody(file: FileUpload['file']) {
if (!ArrayBuffer.isView(file)) return file
return file.buffer instanceof ArrayBuffer
? new Uint8Array(file.buffer, file.byteOffset, file.byteLength)
: Uint8Array.from(file)
}
/**
* `client.context`: the Context API, typed from its OpenAPI spec.
*
* {@link ContextClient.request} calls any operation by its `METHOD /path`,
* with path parameters, query, headers and body typed from the spec.
* `knowledgeBaseId` defaults to the client's `knowledge-base` resource and
* `organizationId` to `context.organizationId`. GROQ reads of the
* organization's Context documents go through {@link ContextClient.fetch}
* and {@link ContextClient.listen}.
*
* @example
* ```ts
* const kb = await client.context.request('POST /knowledge-bases', {
* body: {organizationId: 'org123', title: 'Support docs', description: 'Product docs'},
* })
* const source = await client.context.request('POST /knowledge-bases/{knowledgeBaseId}/sources', {
* params: {knowledgeBaseId: kb.publicId},
* body: {type: 'web', url: 'https://example.com/docs'},
* })
* ```
*
* @beta
*/
export class ContextClient {
#client: SanityClient
#httpRequest: HttpRequest
constructor(client: SanityClient, httpRequest: HttpRequest) {
this.#client = client
this.#httpRequest = httpRequest
}
#legacy = legacyNamespaces(
() => this.#client,
this.request.bind(this) as unknown as LegacyRequest,
this.fetch.bind(this) as LegacyFetch,
)
/** @deprecated Use `request` with the `/knowledge-bases` routes. Kept for Sanity CLI 8.27 and earlier. */
knowledgeBases = this.#legacy.knowledgeBases
/** @deprecated Use `request` with the MCP endpoint routes. Kept for Sanity CLI 8.27 and earlier. */
mcpEndpoints = this.#legacy.mcpEndpoints
/** @deprecated Use `request` and `fetch`. Kept for Sanity CLI 8.27 and earlier. */
entries = this.#legacy.entries
/** @deprecated Use `request` and `fetch`. Kept for Sanity CLI 8.27 and earlier. */
issues = this.#legacy.issues
/** @deprecated Use `request`. Kept for Sanity CLI 8.27 and earlier. */
jobs = this.#legacy.jobs
/** @deprecated Use `request('POST /knowledge-bases/{knowledgeBaseId}/build')`. Kept for Sanity CLI 8.27 and earlier. */
build = this.#legacy.build
/** @deprecated Use `request('POST /knowledge-bases/{knowledgeBaseId}/build/cancel')`. Kept for Sanity CLI 8.27 and earlier. */
cancelBuild = this.#legacy.cancelBuild
/** @deprecated Removed with the imports API; throws. Use the sources, syncs and documents routes. */
imports = this.#legacy.imports
/** @deprecated Removed with the imports API; throws. Use `request('POST /knowledge-bases/{knowledgeBaseId}/sync')`. */
refresh = this.#legacy.refresh
/**
* Call a Context API operation. Resolves with the success response body,
* or `undefined` for `204 No Content`; rejects with the API's error.
*/
async request<R extends Route, const F extends ResponseFormat<R> = never>(
route: R,
...[init]: RequestArgs<R, F>
): Promise<Response<R, F>> {
return _request<Response<R, F>>(
this.#client,
this.#httpRequest,
_contextRequestOptions(this.#client, route, init),
)
}
/**
* {@link ContextClient.request}, resolving with the response bytes instead
* of parsed JSON: for a document's content with `format: 'raw'`, the bytes
* its source gave.
*/
async requestBytes<R extends Route>(
route: R,
...[init]: RequestArgs<R, unknown>
): Promise<Uint8Array> {
return _request<Uint8Array>(this.#client, this.#httpRequest, {
..._contextRequestOptions(this.#client, route, init),
rawBody: true,
})
}
/**
* Upload a file to a `files` source and sync it, replacing the file it
* holds: stages an upload, PUTs the bytes to the signed storage URL, and
* starts the sync with it. The bytes never pass through the Context API.
* If the API refuses the sync, the error carries the staged `uploadId`, so
* a retry can start the sync with it instead of uploading the bytes again.
*/
async uploadFile(
params: UploadFileParams,
options?: {signal?: AbortSignal; tag?: string},
): Promise<SyncAccepted> {
const {knowledgeBaseId, sourceId, file, filename, contentType} = params
const target = {params: {knowledgeBaseId, sourceId}, ...options}
const staged = await this.request(
'POST /knowledge-bases/{knowledgeBaseId}/sources/{sourceId}/uploads',
{...target, body: {filename, ...(contentType && {contentType})}},
)
// The signed URL PUT goes straight to storage, outside the API pipeline:
// no auth header, and the body is raw bytes rather than JSON. It still
// uses the client's fetch resolution so proxy config applies in Node.
const config = this.#client.config()
const doFetch: FetchFunction = config.resolveFetch?.(config.proxy) ?? globalThis.fetch
const putResponse = await doFetch(staged.uploadUrl, {
method: 'PUT',
body: _fetchBody(file),
...(contentType && {headers: {'content-type': contentType}}),
signal: options?.signal,
})
if (!putResponse.ok) {
throw new Error(`File upload failed: ${putResponse.status} ${putResponse.statusText}`)
}
try {
return await this.request(
'POST /knowledge-bases/{knowledgeBaseId}/sources/{sourceId}/syncs',
{...target, body: {uploadId: staged.uploadId}},
)
} catch (error) {
// The API keeps a staged upload whose sync was refused, for example while the source
// is already syncing, so the caller can retry the sync without sending the bytes again
if (error instanceof Error) Object.assign(error, {uploadId: staged.uploadId})
throw error
}
}
/**
* Add a `files` source holding a file: adds the source, uploads the file
* with {@link ContextClient.uploadFile}, and resolves with the source as
* created and the sync the upload started (follow its `jobId`). If the
* upload fails, the source is deleted again before the error is thrown.
*/
async createFileSource(
params: CreateFileSourceParams,
options?: {signal?: AbortSignal; tag?: string},
): Promise<{source: Source; sync: SyncAccepted}> {
const {knowledgeBaseId, file, filename, contentType, ...body} = params
const created = await this.request('POST /knowledge-bases/{knowledgeBaseId}/sources', {
params: {knowledgeBaseId},
body,
...options,
})
if (!('id' in created)) {
throw new Error('The Context API answered a source create with a crawl preview')
}
const target = {knowledgeBaseId, sourceId: created.id}
let sync: SyncAccepted
try {
sync = await this.uploadFile({...target, file, filename, contentType}, options)
} catch (error) {
// Without the file the source is an empty shell a retry would duplicate.
// The delete skips the signal, which may be what aborted the upload.
await this.request('DELETE /knowledge-bases/{knowledgeBaseId}/sources/{sourceId}', {
params: target,
...(options?.tag && {tag: options.tag}),
}).catch(() => {})
throw error
}
return {source: created, sync}
}
/**
* GROQ over the organization's Context documents. The store holds every
* Context document family and the caller's access decides what a query
* returns, so filter on `_type`.
*
* Requires `context.organizationId` in the client configuration.
*/
fetch<R = unknown>(
query: string,
params?: QueryParams,
options?: ContextRequestOptions,
): Promise<R> {
return lastValueFrom(_fetchStore<R>(this.#client, this.#httpRequest, query, params, options))
}
/**
* Listen for changes to the organization's Context documents. Mirrors
* `client.listen(query, params, options)` and emits mutation events by
* default.
*/
listen<Opts extends ContextListenOptions | undefined = undefined>(
query: string,
params?: QueryParams,
options?: Opts,
): Observable<ListenEventFromOptions<SanityDocument, Opts>> {
return _listenStore(this.#client, query, params, options)
}
}
/**
* Observable counterpart of {@link ContextClient}.
*
* @beta
*/
export class ObservableContextClient {
#client: ObservableSanityClient
#httpRequest: HttpRequest
constructor(client: ObservableSanityClient, httpRequest: HttpRequest) {
this.#client = client
this.#httpRequest = httpRequest
}
/** Call a Context API operation. See {@link ContextClient.request}. */
request<R extends Route, const F extends ResponseFormat<R> = never>(
route: R,
...[init]: RequestArgs<R, F>
): Observable<Response<R, F>> {
return defer(() =>
_requestObservable<Response<R, F>>(
this.#client,
this.#httpRequest,
_contextRequestOptions(this.#client, route, init),
),
)
}
/** GROQ over the organization's Context documents. See {@link ContextClient.fetch}. */
fetch<R = unknown>(
query: string,
params?: QueryParams,
options?: ContextRequestOptions,
): Observable<R> {
return _fetchStore<R>(this.#client, this.#httpRequest, query, params, options)
}
/** Listen for changes to the organization's Context documents. See {@link ContextClient.listen}. */
listen<Opts extends ContextListenOptions | undefined = undefined>(
query: string,
params?: QueryParams,
options?: Opts,
): Observable<ListenEventFromOptions<SanityDocument, Opts>> {
return _listenStore(this.#client, query, params, options)
}
}