@sanity/sdk 3.8.0 → 3.9.0-next.20261007114705

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk",
-  "version": "3.8.0",
+  "version": "3.9.0-next.20261007114705",
   "private": false,
   "description": "Sanity SDK",
   "keywords": [
@@ -73,7 +73,7 @@
     "@types/node": "^24.19.1",
     "@vitest/coverage-v8": "^5.0.3",
     "eslint": "^10.12.0",
-    "oxfmt": "^0.71.0",
+    "oxfmt": "^0.72.0",
     "rolldown": "^1.2.12",
     "typescript": "^6.0.3",
     "vite": "^8.3.2",

package/src/_exports/_internal.ts

@@ -4,6 +4,7 @@ export {
   type ApiErrorBody,
   getClientErrorApiBody,
   getClientErrorApiDescription,
+  getClientErrorApiProjectId,
   getClientErrorApiType,
   isProjectUserNotFoundClientError,
 } from '../auth/utils'

package/src/auth/utils.test.ts

@@ -1,3 +1,4 @@
+import {ClientError} from '@sanity/client'
 import {EMPTY, NEVER} from 'rxjs'
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
 
@@ -5,6 +6,7 @@ import {AUTH_CODE_PARAM, DEFAULT_BASE} from './authConstants'
 import {
   getAuthCode,
   getCleanedUrl,
+  getClientErrorApiProjectId,
   getDefaultLocation,
   getDefaultStorage,
   getStorageEvents,
@@ -264,3 +266,26 @@ describe('getCleanedUrl', () => {
     expect(cleaned).toBe('http://example.com/page#section')
   })
 })
+
+describe('getClientErrorApiProjectId', () => {
+  const clientError = (body: unknown) =>
+    new ClientError({
+      statusCode: 401,
+      headers: {},
+      body,
+      url: 'https://exx11uqh.api.sanity.work/v2025-05-06/data/query/production',
+      method: 'GET',
+    } as ConstructorParameters<typeof ClientError>[0])
+
+  it('reads the project from the error body', () => {
+    expect(getClientErrorApiProjectId(clientError({error: {projectID: 'exx11uqh'}}))).toBe(
+      'exx11uqh',
+    )
+  })
+
+  it('ignores a missing, empty or non-string project', () => {
+    expect(getClientErrorApiProjectId(clientError({error: {}}))).toBeUndefined()
+    expect(getClientErrorApiProjectId(clientError({error: {projectID: 42}}))).toBeUndefined()
+    expect(getClientErrorApiProjectId(clientError({error: {projectID: ''}}))).toBeUndefined()
+  })
+})

package/src/auth/utils.ts

@@ -175,7 +175,7 @@ export function getCleanedUrl(locationUrl: string): string {
 
 /** @internal */
 export type ApiErrorBody = {
-  error?: {type?: string; description?: string}
+  error?: {type?: string; description?: string; projectID?: string}
   type?: string
   description?: string
   message?: string
@@ -199,6 +199,15 @@ export function getClientErrorApiDescription(error: ClientError): string | undef
   return body?.error?.description ?? body?.description
 }
 
+/**
+ * Returns the project an API error refers to, if available.
+ * @internal
+ */
+export function getClientErrorApiProjectId(error: ClientError): string | undefined {
+  const projectId = getClientErrorApiBody(error)?.error?.projectID
+  return typeof projectId === 'string' && projectId ? projectId : undefined
+}
+
 /** @internal True if the error represents a projectUserNotFoundError. */
 export function isProjectUserNotFoundClientError(error: ClientError): boolean {
   return getClientErrorApiType(error) === 'projectUserNotFoundError'

package/src/config/__tests__/handles.test-d.ts

@@ -0,0 +1,24 @@
+import {expectTypeOf, test} from 'vitest'
+
+import {createDocumentHandle} from '../handles'
+
+// `createDocumentHandle` exists to capture the literal types of its input. Its runtime
+// behavior, returning the input unchanged, is covered in `handles.test.ts` and is the
+// uninteresting half: a signature change that dropped `TDataset` or `TProjectId` would
+// pass every runtime test while silently removing inference for every consumer.
+//
+// Typegen looks results up by a `projectId.dataset` key, so a handle carrying `string`
+// instead of a literal matches nothing.
+
+test('createDocumentHandle preserves the literal types of its input', () => {
+  const handle = createDocumentHandle({
+    projectId: 'ppsg7ml5',
+    dataset: 'test',
+    documentId: 'some-id',
+    documentType: 'author',
+  })
+
+  expectTypeOf(handle.projectId).toEqualTypeOf<'ppsg7ml5' | undefined>()
+  expectTypeOf(handle.dataset).toEqualTypeOf<'test' | undefined>()
+  expectTypeOf(handle.documentType).toEqualTypeOf<'author'>()
+})

package/src/typegen/resolve.test-d.ts

@@ -0,0 +1,105 @@
+import {expectTypeOf, test} from 'vitest'
+
+import {type ActionsResult} from '../document/applyDocumentActions'
+import {
+  type ResolveDocument,
+  type ResolveProjectionResult,
+  type ResolveQueryResult,
+} from './resolve'
+
+// Stands in for what a multi-resource `sanity typegen` run emits. Two resources whose
+// schemas disagree, plus an object type that must not resolve as a document.
+type TestPost = {
+  _id: string
+  _type: 'post'
+  _createdAt: string
+  _updatedAt: string
+  _rev: string
+  title: string
+}
+interface ProductionPost {
+  _id: string
+  _type: 'post'
+  _createdAt: string
+  _updatedAt: string
+  _rev: string
+  title: number
+}
+type Slug = {_type: 'slug'; current: string}
+
+type TestPostsResult = {_id: string; title: string}[]
+type ProductionPostsResult = {_id: string; title: number}[]
+type TestTitleProjection = {title: string}
+
+// Registered the way generated files do: as globals, which the interfaces `@sanity/client`
+// exports extend. Every file in this package's type-check program sees these registrations, not
+// only this test, so their keys must stay unique across the package's tests.
+declare global {
+  interface SanitySchemasByResource {
+    'resolve1.test': TestPost | Slug
+    'resolve2.production': ProductionPost
+  }
+  interface SanityQueriesByResource {
+    'resolve1.test': {'*[_type == "post"]': TestPostsResult}
+    'resolve2.production': {'*[_type == "post"]': ProductionPostsResult}
+  }
+  interface SanityProjectionsByResource {
+    'resolve1.test': {post: {'{title}': TestTitleProjection}}
+  }
+}
+
+test('registered resources resolve documents declared as aliases or interfaces', () => {
+  expectTypeOf<ResolveDocument<'post', 'resolve1.test'>>().toEqualTypeOf<TestPost>()
+  expectTypeOf<ResolveDocument<'post', 'resolve2.production'>>().toEqualTypeOf<ProductionPost>()
+})
+
+test('interface registrations remain usable in document action results', () => {
+  type Result = ActionsResult<ResolveDocument<'post', 'resolve2.production'>>
+  expectTypeOf<NonNullable<Result['documents'][string]>>().toEqualTypeOf<ProductionPost>()
+})
+
+test('a document type absent from a registered resource is never', () => {
+  // Not the legacy union. Falling through would describe the wrong dataset while looking
+  // precise.
+  expectTypeOf<ResolveDocument<'movie', 'resolve1.test'>>().toEqualTypeOf<never>()
+})
+
+test('an object type in the schema union is not a document', () => {
+  expectTypeOf<ResolveDocument<'slug', 'resolve1.test'>>().toEqualTypeOf<never>()
+})
+
+test('an unconstrained document type yields the resource documents only', () => {
+  expectTypeOf<ResolveDocument<string, 'resolve1.test'>>().toEqualTypeOf<TestPost>()
+})
+
+test('an unregistered resource falls back to the legacy lookup', () => {
+  // The legacy path answers with the base document shape when nothing is registered, which
+  // is what keeps saved experimental output working.
+  expectTypeOf<ResolveDocument<string, 'unregistered.dataset'>['_id']>().toEqualTypeOf<string>()
+  expectTypeOf<ResolveDocument<'post', 'unregistered.dataset'>>().toEqualTypeOf<never>()
+})
+
+test('the same query text resolves to a different type per resource', () => {
+  expectTypeOf<
+    ResolveQueryResult<'*[_type == "post"]', 'resolve1.test'>
+  >().toEqualTypeOf<TestPostsResult>()
+  expectTypeOf<
+    ResolveQueryResult<'*[_type == "post"]', 'resolve2.production'>
+  >().toEqualTypeOf<ProductionPostsResult>()
+})
+
+test('an unregistered query on a registered resource is never', () => {
+  expectTypeOf<ResolveQueryResult<'*[_type == "movie"]', 'resolve1.test'>>().toEqualTypeOf<never>()
+})
+
+test('a projection resolves by resource and document type', () => {
+  expectTypeOf<
+    ResolveProjectionResult<'{title}', 'post', 'resolve1.test'>
+  >().toEqualTypeOf<TestTitleProjection>()
+})
+
+test('a projection on a document type with no registrations is never', () => {
+  expectTypeOf<
+    ResolveProjectionResult<'{title}', 'movie', 'resolve1.test'>
+  >().toEqualTypeOf<never>()
+})

package/src/typegen/resolve.ts

@@ -1,32 +1,79 @@
 import './groqCompat'
 
+import {
+  type SanityProjectionsByResource,
+  type SanityQueriesByResource,
+  type SanitySchemasByResource,
+} from '@sanity/client'
 import {type SanityDocument, type SanityProjectionResult, type SanityQueryResult} from 'groq'
 
 /**
- * Resolves a document using declarations from experimental Typegen.
- * Preserves the legacy lookup behavior while the SDK uses released `groq`.
+ * Indexes `T` by `K`, or `never` when `K` is not a key of `T`.
+ *
+ * Deliberately exact. The legacy `groq` lookup falls back to the union of every registered
+ * value on a miss, which lets a query resolve to another dataset's result type.
+ */
+type At<T, K> = K extends keyof T ? T[K] : never
+
+/**
+ * Fields Sanity adds to every document. A resource's schema union also carries object types
+ * such as `slug`, which lack these, so this separates documents from the rest.
+ * No index signature is required, so both type aliases and interfaces are supported.
+ */
+interface DocumentFields {
+  _id: string
+  _type: string
+  _createdAt: string
+  _updatedAt: string
+  _rev: string
+}
+
+/**
+ * Copies document fields into a type alias so interface registrations satisfy the
+ * record constraints used by document actions without adding an index signature.
+ */
+type DocumentRecord<T> = {[K in keyof T]: T[K]}
+
+/**
+ * Resolves a document type for one resource.
+ *
+ * A resource registered in `SanitySchemasByResource` is answered from there and only there:
+ * a document type absent from a registered resource is `never`, never the legacy union,
+ * because an unrelated union looks precise while describing the wrong dataset. A resource
+ * with no registration falls back to the experimental Typegen declarations, which is what
+ * keeps saved generated files working.
  *
  * @beta
  */
 export type ResolveDocument<
   TDocumentType extends string = string,
   TSchemaId extends string = string,
-> = SanityDocument<TDocumentType, TSchemaId>
+> = TSchemaId extends keyof SanitySchemasByResource
+  ? DocumentRecord<
+      Extract<Extract<SanitySchemasByResource[TSchemaId], DocumentFields>, {_type: TDocumentType}>
+    >
+  : SanityDocument<TDocumentType, TSchemaId>
 
 /**
- * Resolves a query using declarations from experimental Typegen.
- * For types generated by current Typegen, pass the result type to the hook explicitly.
+ * Resolves a query result for one resource, selected by the exact query text.
+ *
+ * Falls back to the experimental Typegen declarations for an unregistered resource. See
+ * {@link ResolveDocument} for why a registered resource does not fall through.
  *
  * @beta
  */
 export type ResolveQueryResult<
   TQuery extends string = string,
   TSchemaId extends string = string,
-> = SanityQueryResult<TQuery, TSchemaId>
+> = TSchemaId extends keyof SanityQueriesByResource
+  ? At<SanityQueriesByResource[TSchemaId], TQuery>
+  : SanityQueryResult<TQuery, TSchemaId>
 
 /**
- * Resolves a projection using declarations from experimental Typegen.
- * Selects the result by projection string, document type, and schema ID.
+ * Resolves a projection result for one resource and document type.
+ *
+ * A projection runs against the document its handle names, so the same projection text
+ * resolves differently per document type as well as per resource.
  *
  * @beta
  */
@@ -34,4 +81,9 @@ export type ResolveProjectionResult<
   TProjection extends string = string,
   TDocumentType extends string = string,
   TSchemaId extends string = string,
-> = SanityProjectionResult<TProjection, TDocumentType, TSchemaId>
+> = TSchemaId extends keyof SanityProjectionsByResource
+  ? // `Extract<..., object>` keeps this assignable to the `object` bound that
+    // `ProjectionValuePending` places on a projection result. A projection always selects
+    // fields into an object, so nothing is lost.
+    Extract<At<At<SanityProjectionsByResource[TSchemaId], TDocumentType>, TProjection>, object>
+  : SanityProjectionResult<TProjection, TDocumentType, TSchemaId>