@sanity/sdk 2.18.0 → 3.0.0-rc.1

package/src/installations/installations.ts

@@ -0,0 +1,202 @@
+import {switchMap} from 'rxjs'
+
+import {getClientState} from '../client/clientStore'
+import {defineFetcher} from '../store/fetcherStore'
+import {buildQuery} from '../utils/buildQuery'
+import {type Included} from '../utils/includeShape'
+
+// The Applications API is currently only available on vX.
+const API_VERSION = 'vX'
+
+/**
+ * Related data the Installations API can embed in a response. Each token adds
+ * a top-level field to the {@link Installation} item.
+ *
+ * @see https://www.sanity.io/docs/http-reference/applications-api
+ * @public
+ */
+export type InstallationInclude = 'activeConfig' | 'access' | 'interfaces'
+
+/**
+ * A resource an installation accesses, embedded when `access` is included.
+ *
+ * @see https://www.sanity.io/docs/http-reference/applications-api
+ * @public
+ */
+export interface InstallationAccess {
+  id: string
+  resourceType: 'datasets' | 'canvases' | 'dashboards' | 'media-libraries'
+  resourceId: string
+}
+
+/**
+ * An interface exposed by an installation, embedded when `interfaces` is
+ * included.
+ *
+ * @see https://www.sanity.io/docs/http-reference/applications-api
+ * @public
+ */
+export interface InstallationInterface {
+  id: string
+  type: 'app' | 'worker' | 'asset_source' | 'panel'
+  name: string
+  title: string
+  version: string
+  /** Module federation module ID; resolved from the host mf-manifest at runtime */
+  moduleId: string
+  metadata: {group?: string; priority?: number} | null
+}
+
+/**
+ * The active config of an installation, embedded when `activeConfig` is
+ * included. `null` when nothing is deployed.
+ *
+ * @see https://www.sanity.io/docs/http-reference/applications-api
+ * @public
+ */
+export interface InstallationActiveConfig {
+  id: string
+  installationId: string
+  deployedBy: string | null
+  version: string
+  isActive: boolean
+  createdAt: string
+}
+
+/**
+ * The always-present fields of an active singleton installation returned by the
+ * Installations API (`/installations`), before any {@link InstallationInclude}.
+ *
+ * @see https://www.sanity.io/docs/http-reference/applications-api
+ * @public
+ */
+export interface InstallationBase {
+  id: string
+  applicationId: string
+  organizationId: string
+  installedBy: string | null
+  createdAt: string
+  updatedAt: string
+  application: {
+    title: string
+    slug: string | null
+  }
+}
+
+/**
+ * An active singleton installation as returned by the Installations API
+ * (`/installations`). `activeConfig`, `access` and `interfaces` are top-level
+ * fields, each present only when the matching {@link InstallationInclude} token
+ * was requested.
+ *
+ * @see https://www.sanity.io/docs/http-reference/applications-api
+ * @public
+ */
+export type Installation<Include extends InstallationInclude = never> = InstallationBase &
+  Included<
+    InstallationInclude,
+    'activeConfig',
+    Include,
+    {activeConfig: InstallationActiveConfig | null}
+  > &
+  Included<InstallationInclude, 'access', Include, {access: InstallationAccess[]}> &
+  Included<InstallationInclude, 'interfaces', Include, {interfaces: InstallationInterface[]}>
+
+/**
+ * Options for listing an organization's installations.
+ *
+ * @see https://www.sanity.io/docs/http-reference/applications-api
+ * @public
+ */
+export interface InstallationsOptions<Include extends InstallationInclude = InstallationInclude> {
+  organizationId: string
+  include?: Include[]
+  /** Page size (1-100, default 50), or `'none'` to disable pagination */
+  limit?: number | 'none'
+  /** Cursor from a previous response's `nextCursor` */
+  cursor?: string
+}
+
+/**
+ * The cursor-paginated envelope returned by `GET /installations`.
+ *
+ * @see https://www.sanity.io/docs/http-reference/applications-api
+ * @public
+ */
+export interface InstallationsResponse<Include extends InstallationInclude = never> {
+  nextCursor: string | null
+  data: Installation<Include>[]
+}
+
+/** The API takes `include` as a comma-separated list; sorted so key and query agree */
+function serializeInclude(include: InstallationInclude[] | undefined): string | undefined {
+  return include?.length ? [...include].sort().join(',') : undefined
+}
+
+/**
+ * Fetcher for an organization's installations (`GET /installations`), on the
+ * shared fetcher cache.
+ *
+ * @see https://www.sanity.io/docs/http-reference/applications-api
+ * @internal
+ */
+export const installations = defineFetcher<
+  [options: InstallationsOptions],
+  InstallationsResponse<InstallationInclude>
+>({
+  name: 'installations',
+  getKey: (_instance, options) =>
+    [
+      options.organizationId,
+      serializeInclude(options.include) ?? '',
+      options.limit ?? '',
+      options.cursor ?? '',
+    ].join(':'),
+  fetch: (instance) => (options) =>
+    getClientState(instance, {apiVersion: API_VERSION, scope: 'global'}).observable.pipe(
+      switchMap((client) =>
+        client.observable.request<InstallationsResponse<InstallationInclude>>({
+          uri: '/installations',
+          query: buildQuery({
+            organizationId: options.organizationId,
+            include: serializeInclude(options.include),
+            limit: options.limit,
+            cursor: options.cursor,
+          }),
+          tag: 'installations.list',
+        }),
+      ),
+    ),
+  tags: (data) => [
+    {type: 'installation', id: 'LIST'},
+    ...data.data.map((installation) => ({type: 'installation', id: installation.id})),
+  ],
+})
+
+/**
+ * Fetcher for a single installation (`GET /installations/:id`), on the shared
+ * fetcher cache. No pre-seeding from {@link installations}: its list keys
+ * include the organization, which this fetcher's params can't reconstruct.
+ *
+ * @see https://www.sanity.io/docs/http-reference/applications-api
+ * @internal
+ */
+export const installation = defineFetcher<
+  [installationId: string, options?: {include?: InstallationInclude[]}],
+  Installation<InstallationInclude>
+>({
+  name: 'installation',
+  getKey: (_instance, installationId, options) =>
+    `${installationId}:${serializeInclude(options?.include) ?? ''}`,
+  fetch: (instance) => (installationId, options) =>
+    getClientState(instance, {apiVersion: API_VERSION, scope: 'global'}).observable.pipe(
+      switchMap((client) =>
+        client.observable.request<Installation<InstallationInclude>>({
+          uri: `/installations/${installationId}`,
+          query: buildQuery({include: serializeInclude(options?.include)}),
+          tag: 'installations.get',
+        }),
+      ),
+    ),
+  tags: (data) => [{type: 'installation', id: data.id}],
+})

package/src/organization/organization.test-d.ts

@@ -2,101 +2,35 @@ import {expectTypeOf, test} from 'vitest'
 
 import {type SanityInstance} from '../store/createSanityInstance'
 import {type StateSource} from '../store/createStateSourceAction'
-import {
-  getOrganizationState,
-  type Organization,
-  type OrganizationBase,
-  type OrganizationMember,
-  resolveOrganization,
-} from './organization'
+import {type FetcherSnapshot} from '../store/fetcherStore'
+import {type Organization, organization, type OrganizationMember} from './organization'
 
 const instance = {} as SanityInstance
 
-test('resolveOrganization — default call: members and features both omitted by default', () => {
-  expectTypeOf(resolveOrganization(instance, {organizationId: 'org_1'})).resolves.toEqualTypeOf<
-    Organization<false, false>
-  >()
-  type Result = Awaited<ReturnType<typeof resolveOrganization<false, false>>>
-  expectTypeOf<Result['id']>().toEqualTypeOf<string>()
-})
-
-test('resolveOrganization — includeMembers: true adds members to the type', () => {
-  expectTypeOf(
-    resolveOrganization(instance, {organizationId: 'org_1', includeMembers: true}),
-  ).resolves.toEqualTypeOf<Organization<true, false>>()
-  type Result = Awaited<ReturnType<typeof resolveOrganization<true, false>>>
-  expectTypeOf<Result['members']>().toEqualTypeOf<OrganizationMember[]>()
-})
-
-test('resolveOrganization — includeFeatures: true adds features to the type', () => {
-  expectTypeOf(
-    resolveOrganization(instance, {organizationId: 'org_1', includeFeatures: true}),
-  ).resolves.toEqualTypeOf<Organization<false, true>>()
-})
-
-test('resolveOrganization — both flags true → both arrays present', () => {
-  expectTypeOf(
-    resolveOrganization(instance, {
-      organizationId: 'org_1',
-      includeMembers: true,
-      includeFeatures: true,
-    }),
-  ).resolves.toEqualTypeOf<Organization<true, true>>()
-})
-
-test('resolveOrganization — rejects non-boolean flag values', () => {
-  // @ts-expect-error — includeMembers must be a boolean
-  void resolveOrganization(instance, {organizationId: 'org_1', includeMembers: 'yes'})
-})
-
-test('resolveOrganization — requires organizationId', () => {
-  // @ts-expect-error — organizationId is required
-  void resolveOrganization(instance, {})
-})
-
-test('resolveOrganization — non-literal boolean flag makes members optional', () => {
-  const includeMembers = false as boolean
+test('organization.resolveState — resolves the wide-boolean detail shape', () => {
   expectTypeOf(
-    resolveOrganization(instance, {organizationId: 'org_1', includeMembers}),
-  ).resolves.toEqualTypeOf<Organization<boolean, false>>()
+    organization.resolveState(instance, {organizationId: 'org_1'}),
+  ).resolves.toEqualTypeOf<Organization<boolean, boolean>>()
 })
 
-test('getOrganizationState — default call returns bare-base StateSource', () => {
-  expectTypeOf(getOrganizationState(instance, {organizationId: 'org_1'})).toEqualTypeOf<
-    StateSource<Organization<false, false> | undefined>
-  >()
+test('Organization — literal flags narrow members and features', () => {
+  expectTypeOf<Organization<true, true>['members']>().toEqualTypeOf<OrganizationMember[]>()
+  expectTypeOf<Organization<true, true>['features']>().toEqualTypeOf<string[]>()
+  expectTypeOf<keyof Organization<false, false> & ('members' | 'features')>().toEqualTypeOf<never>()
 })
 
-test('getOrganizationState — both flags true narrows the StateSource value type', () => {
-  expectTypeOf(
-    getOrganizationState(instance, {
-      organizationId: 'org_1',
-      includeMembers: true,
-      includeFeatures: true,
-    }),
-  ).toEqualTypeOf<StateSource<Organization<true, true> | undefined>>()
-})
-
-test('Organization — wide boolean for IncludeMembers makes members optional', () => {
-  expectTypeOf<Organization<boolean, true>>().toEqualTypeOf<
-    OrganizationBase & {members?: OrganizationMember[]} & {features: string[]}
+test('organization.getState — exposes the snapshot envelope', () => {
+  expectTypeOf(organization.getState(instance, {organizationId: 'org_1'})).toEqualTypeOf<
+    StateSource<FetcherSnapshot<Organization<boolean, boolean>>>
   >()
-  expectTypeOf<Pick<Organization<boolean, true>, 'members'>>().toEqualTypeOf<{
-    members?: OrganizationMember[]
-  }>()
 })
 
-test('Organization — wide boolean for IncludeFeatures makes features optional', () => {
-  expectTypeOf<Organization<true, boolean>>().toEqualTypeOf<
-    OrganizationBase & {members: OrganizationMember[]} & {features?: string[]}
-  >()
-  expectTypeOf<Pick<Organization<true, boolean>, 'features'>>().toEqualTypeOf<{
-    features?: string[]
-  }>()
+test('organization — requires organizationId in options', () => {
+  // @ts-expect-error organizationId is required
+  void organization.resolveState(instance, {})
 })
 
-test('Organization — both wide booleans make both fields optional', () => {
-  expectTypeOf<Organization<boolean, boolean>>().toEqualTypeOf<
-    OrganizationBase & {members?: OrganizationMember[]} & {features?: string[]}
-  >()
+test('organization — rejects non-boolean flag values', () => {
+  // @ts-expect-error includeMembers must be a boolean
+  void organization.resolveState(instance, {organizationId: 'org_1', includeMembers: 'yes'})
 })

package/src/organization/organization.test.ts

@@ -5,7 +5,7 @@ import {afterEach, beforeEach, describe, it} from 'vitest'
 import {getClientState} from '../client/clientStore'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {type StateSource} from '../store/createStateSourceAction'
-import {getOrganizationCacheKey, resolveOrganization} from './organization'
+import {getOrganizationCacheKey, organization} from './organization'
 
 vi.mock('../client/clientStore')
 
@@ -21,8 +21,8 @@ describe('organization', () => {
   })
 
   it('calls `client.observable.request` against `/organizations/<id>` and returns the result', async () => {
-    const organization = {id: 'org_1'}
-    const request = vi.fn().mockReturnValue(of(organization))
+    const detail = {id: 'org_1'}
+    const request = vi.fn().mockReturnValue(of(detail))
 
     const mockClient = {
       observable: {request} as unknown as SanityClient['observable'],
@@ -32,12 +32,12 @@ describe('organization', () => {
       observable: of(mockClient),
     } as StateSource<SanityClient>)
 
-    const result = await resolveOrganization(instance, {organizationId: 'org_1'})
-    expect(result).toEqual(organization)
+    const result = await organization.resolveState(instance, {organizationId: 'org_1'})
+    expect(result).toEqual(detail)
     expect(request).toHaveBeenCalledWith({
       uri: '/organizations/org_1',
       query: {includeMembers: 'false', includeFeatures: 'false'},
-      tag: 'organization.get',
+      tag: 'organizations.get',
     })
   })
 
@@ -51,7 +51,7 @@ describe('organization', () => {
       observable: of(mockClient),
     } as StateSource<SanityClient>)
 
-    await resolveOrganization(instance, {
+    await organization.resolveState(instance, {
       organizationId: 'org_1',
       includeMembers: true,
       includeFeatures: true,
@@ -63,14 +63,14 @@ describe('organization', () => {
         includeMembers: 'true',
         includeFeatures: 'true',
       },
-      tag: 'organization.get',
+      tag: 'organizations.get',
     })
   })
 
   it('throws when no organizationId is provided', async () => {
-    await expect(resolveOrganization(instance, {organizationId: ''} as never)).rejects.toThrow(
-      'An organizationId is required to use the organization API.',
-    )
+    await expect(
+      organization.resolveState(instance, {organizationId: ''} as never),
+    ).rejects.toThrow('An organizationId is required to use the organization API.')
   })
 })
 

package/src/organization/organization.ts

@@ -2,8 +2,8 @@ import {switchMap} from 'rxjs'
 
 import {getClientState} from '../client/clientStore'
 import {type SanityInstance} from '../store/createSanityInstance'
-import {type StateSource} from '../store/createStateSourceAction'
-import {createFetcherStore} from '../utils/createFetcherStore'
+import {defineFetcher} from '../store/fetcherStore'
+import {buildQuery} from '../utils/buildQuery'
 
 const API_VERSION = 'v2025-02-19'
 
@@ -110,57 +110,29 @@ export function getOrganizationCacheKey(
   return `organization:${organizationId}${membersKey}${featuresKey}`
 }
 
-const organization = createFetcherStore({
-  name: 'Organization',
-  getKey: getOrganizationCacheKey,
-  fetcher: (instance) => (options?: OrganizationOptions<boolean, boolean>) => {
-    const organizationId = resolveOrganizationId(options)
-
-    return getClientState(instance, {
-      apiVersion: API_VERSION,
-      scope: 'global',
-    }).observable.pipe(
-      switchMap((client) => {
-        const normalized = normalizeOrganizationOptions(options)
-        const query = Object.fromEntries(
-          Object.entries(normalized)
-            .filter(([, value]) => value !== undefined)
-            .map(([key, value]) => [key, String(value)]),
-        )
-
-        return client.observable.request({
-          uri: `/organizations/${organizationId}`,
-          query,
-          tag: 'organization.get',
-        })
-      }),
-    )
-  },
-})
-
 /**
- * Public signature for the organization state source. The conditional generics
- * cannot flow through `BoundStoreAction`, so we declare the signature here
- * and assign the (already-correct) runtime function to it.
+ * Fetcher for a single organization (`GET /organizations/:id`), on the shared
+ * fetcher cache. No pre-seeding from the organizations list: it returns a
+ * subset of the detail fields, and a partial seed would serve as fresh for
+ * the whole stale window.
+ *
+ * @internal
  */
-type GetOrganizationState = <
-  IncludeMembers extends boolean = false,
-  IncludeFeatures extends boolean = false,
->(
-  instance: SanityInstance,
-  options: OrganizationOptions<IncludeMembers, IncludeFeatures>,
-) => StateSource<Organization<IncludeMembers, IncludeFeatures> | undefined>
-
-type ResolveOrganization = <
-  IncludeMembers extends boolean = false,
-  IncludeFeatures extends boolean = false,
->(
-  instance: SanityInstance,
-  options: OrganizationOptions<IncludeMembers, IncludeFeatures>,
-) => Promise<Organization<IncludeMembers, IncludeFeatures>>
-
-/** @public */
-export const getOrganizationState: GetOrganizationState = organization.getState
-
-/** @public */
-export const resolveOrganization: ResolveOrganization = organization.resolveState
+export const organization = defineFetcher<
+  [options?: OrganizationOptions<boolean, boolean>],
+  Organization<boolean, boolean>
+>({
+  name: 'organization',
+  getKey: getOrganizationCacheKey,
+  fetch: (instance) => (options) =>
+    getClientState(instance, {apiVersion: API_VERSION, scope: 'global'}).observable.pipe(
+      switchMap((client) =>
+        client.observable.request<Organization<boolean, boolean>>({
+          uri: `/organizations/${resolveOrganizationId(options)}`,
+          query: buildQuery(normalizeOrganizationOptions(options)),
+          tag: 'organizations.get',
+        }),
+      ),
+    ),
+  tags: (data) => [{type: 'organization', id: data.id}],
+})

package/src/organizations/organizations.test-d.ts

@@ -3,41 +3,26 @@ import {expectTypeOf, test} from 'vitest'
 import {type OrganizationMember} from '../organization/organization'
 import {type SanityInstance} from '../store/createSanityInstance'
 import {type StateSource} from '../store/createStateSourceAction'
-import {getOrganizationsState, type Organizations, resolveOrganizations} from './organizations'
+import {type FetcherSnapshot} from '../store/fetcherStore'
+import {type Organizations, organizations} from './organizations'
 
 const instance = {} as SanityInstance
 
-test('resolveOrganizations — default call: bare list shape', () => {
-  expectTypeOf(resolveOrganizations(instance)).resolves.toEqualTypeOf<Organizations<false, false>>()
-})
-
-test('resolveOrganizations — includeMembers: true narrows the generic', () => {
-  expectTypeOf(resolveOrganizations(instance, {includeMembers: true})).resolves.toEqualTypeOf<
-    Organizations<true, false>
+test('organizations.resolveState — resolves the wide-boolean list shape', () => {
+  expectTypeOf(organizations.resolveState(instance)).resolves.toEqualTypeOf<
+    Organizations<boolean, boolean>
   >()
 })
 
-test('resolveOrganizations — includeFeatures: true narrows the generic', () => {
-  expectTypeOf(resolveOrganizations(instance, {includeFeatures: true})).resolves.toEqualTypeOf<
-    Organizations<false, true>
+test('organizations.getState — exposes the snapshot envelope', () => {
+  expectTypeOf(organizations.getState(instance)).toEqualTypeOf<
+    StateSource<FetcherSnapshot<Organizations<boolean, boolean>>>
   >()
 })
 
-test('resolveOrganizations — both flags true', () => {
-  expectTypeOf(
-    resolveOrganizations(instance, {includeMembers: true, includeFeatures: true}),
-  ).resolves.toEqualTypeOf<Organizations<true, true>>()
-})
-
-test('resolveOrganizations — rejects non-boolean flag values', () => {
-  // @ts-expect-error — includeMembers must be a boolean
-  void resolveOrganizations(instance, {includeMembers: 'yes'})
-})
-
-test('resolveOrganizations — includeImplicitMemberships does not change the data shape', () => {
-  expectTypeOf(
-    resolveOrganizations(instance, {includeImplicitMemberships: true}),
-  ).resolves.toEqualTypeOf<Organizations<false, false>>()
+test('organizations — rejects non-boolean flag values', () => {
+  // @ts-expect-error includeMembers must be a boolean
+  void organizations.resolveState(instance, {includeMembers: 'yes'})
 })
 
 test('Organizations — list items expose the documented subset of keys', () => {
@@ -69,9 +54,3 @@ test('Organizations<true, true>[number] exposes both members[] and features[]',
   expectTypeOf<Item['members']>().toEqualTypeOf<OrganizationMember[]>()
   expectTypeOf<Item['features']>().toEqualTypeOf<string[]>()
 })
-
-test('getOrganizationsState — default call returns the bare-base StateSource', () => {
-  expectTypeOf(getOrganizationsState(instance)).toEqualTypeOf<
-    StateSource<Organizations<false, false> | undefined>
-  >()
-})

package/src/organizations/organizations.test.ts

@@ -5,7 +5,7 @@ import {afterEach, beforeEach, describe, it} from 'vitest'
 import {getClientState} from '../client/clientStore'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {type StateSource} from '../store/createStateSourceAction'
-import {getOrganizationsCacheKey, resolveOrganizations} from './organizations'
+import {getOrganizationsCacheKey, organizations} from './organizations'
 
 vi.mock('../client/clientStore')
 
@@ -21,8 +21,8 @@ describe('organizations', () => {
   })
 
   it('calls `client.observable.request` against `/organizations` and returns the result', async () => {
-    const organizations = [{id: 'org_1'}, {id: 'org_2'}]
-    const request = vi.fn().mockReturnValue(of(organizations))
+    const list = [{id: 'org_1'}, {id: 'org_2'}]
+    const request = vi.fn().mockReturnValue(of(list))
 
     const mockClient = {
       observable: {request} as unknown as SanityClient['observable'],
@@ -32,8 +32,8 @@ describe('organizations', () => {
       observable: of(mockClient),
     } as StateSource<SanityClient>)
 
-    const result = await resolveOrganizations(instance)
-    expect(result).toEqual(organizations)
+    const result = await organizations.resolveState(instance)
+    expect(result).toEqual(list)
     expect(request).toHaveBeenCalledWith({
       uri: '/organizations',
       query: {
@@ -41,7 +41,7 @@ describe('organizations', () => {
         includeMembers: 'false',
         includeFeatures: 'false',
       },
-      tag: 'organizations.get',
+      tag: 'organizations.list',
     })
   })
 
@@ -55,7 +55,7 @@ describe('organizations', () => {
       observable: of(mockClient),
     } as StateSource<SanityClient>)
 
-    await resolveOrganizations(instance, {
+    await organizations.resolveState(instance, {
       includeMembers: true,
       includeFeatures: true,
       includeImplicitMemberships: true,
@@ -68,7 +68,7 @@ describe('organizations', () => {
         includeMembers: 'true',
         includeFeatures: 'true',
       },
-      tag: 'organizations.get',
+      tag: 'organizations.list',
     })
   })
 })