@sanity/sdk 3.0.0-rc.0 → 3.0.0-rc.2

package/src/installations/installations.ts

@@ -0,0 +1,206 @@
+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
+    /** Stable, immutable identity of the installed singleton, distinct from `slug`. */
+    name: string
+    /** Qualified, globally-unique handle of the installed singleton (e.g. `sanity/<name>`). */
+    reference: 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

@@ -0,0 +1,36 @@
+import {expectTypeOf, test} from 'vitest'
+
+import {type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {type FetcherSnapshot} from '../store/fetcherStore'
+import {type Organization, organization, type OrganizationMember} from './organization'
+
+const instance = {} as SanityInstance
+
+test('organization.resolveState — resolves the wide-boolean detail shape', () => {
+  expectTypeOf(
+    organization.resolveState(instance, {organizationId: 'org_1'}),
+  ).resolves.toEqualTypeOf<Organization<boolean, boolean>>()
+})
+
+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('organization.getState — exposes the snapshot envelope', () => {
+  expectTypeOf(organization.getState(instance, {organizationId: 'org_1'})).toEqualTypeOf<
+    StateSource<FetcherSnapshot<Organization<boolean, boolean>>>
+  >()
+})
+
+test('organization — requires organizationId in options', () => {
+  // @ts-expect-error organizationId is required
+  void organization.resolveState(instance, {})
+})
+
+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

@@ -0,0 +1,138 @@
+import {type SanityClient} from '@sanity/client'
+import {of} from 'rxjs'
+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, organization} from './organization'
+
+vi.mock('../client/clientStore')
+
+describe('organization', () => {
+  let instance: SanityInstance
+
+  beforeEach(() => {
+    instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+  })
+
+  afterEach(() => {
+    instance.dispose()
+  })
+
+  it('calls `client.observable.request` against `/organizations/<id>` and returns the result', async () => {
+    const detail = {id: 'org_1'}
+    const request = vi.fn().mockReturnValue(of(detail))
+
+    const mockClient = {
+      observable: {request} as unknown as SanityClient['observable'],
+    } as SanityClient
+
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of(mockClient),
+    } as StateSource<SanityClient>)
+
+    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: 'organizations.get',
+    })
+  })
+
+  it('serializes query params (booleans → strings) and respects flags', async () => {
+    const request = vi.fn().mockReturnValue(of({id: 'org_1'}))
+    const mockClient = {
+      observable: {request} as unknown as SanityClient['observable'],
+    } as SanityClient
+
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of(mockClient),
+    } as StateSource<SanityClient>)
+
+    await organization.resolveState(instance, {
+      organizationId: 'org_1',
+      includeMembers: true,
+      includeFeatures: true,
+    })
+
+    expect(request).toHaveBeenCalledWith({
+      uri: '/organizations/org_1',
+      query: {
+        includeMembers: 'true',
+        includeFeatures: 'true',
+      },
+      tag: 'organizations.get',
+    })
+  })
+
+  it('throws when no organizationId is provided', async () => {
+    await expect(
+      organization.resolveState(instance, {organizationId: ''} as never),
+    ).rejects.toThrow('An organizationId is required to use the organization API.')
+  })
+})
+
+describe('organization cache key generation', () => {
+  let instance: SanityInstance
+
+  beforeEach(() => {
+    instance = createSanityInstance({})
+  })
+
+  afterEach(() => {
+    instance.dispose()
+  })
+
+  it('default call excludes :members and :features (both default-false)', () => {
+    expect(getOrganizationCacheKey(instance, {organizationId: 'org_1'})).toBe('organization:org_1')
+  })
+
+  it('treats undefined and the matching default as the same key', () => {
+    expect(getOrganizationCacheKey(instance, {organizationId: 'org_1'})).toBe(
+      getOrganizationCacheKey(instance, {
+        organizationId: 'org_1',
+        includeMembers: false,
+        includeFeatures: false,
+      }),
+    )
+  })
+
+  it('explicit includeMembers: true appends :members', () => {
+    expect(getOrganizationCacheKey(instance, {organizationId: 'org_1', includeMembers: true})).toBe(
+      'organization:org_1:members',
+    )
+  })
+
+  it('explicit includeFeatures: true appends :features', () => {
+    expect(
+      getOrganizationCacheKey(instance, {organizationId: 'org_1', includeFeatures: true}),
+    ).toBe('organization:org_1:features')
+  })
+
+  it('combines all segments in order', () => {
+    expect(
+      getOrganizationCacheKey(instance, {
+        organizationId: 'org_1',
+        includeMembers: true,
+        includeFeatures: true,
+      }),
+    ).toBe('organization:org_1:members:features')
+  })
+
+  it('produces distinct keys for each meaningful option permutation', () => {
+    const keys = new Set([
+      getOrganizationCacheKey(instance, {organizationId: 'org_1'}),
+      getOrganizationCacheKey(instance, {organizationId: 'org_1', includeMembers: true}),
+      getOrganizationCacheKey(instance, {organizationId: 'org_1', includeFeatures: true}),
+      getOrganizationCacheKey(instance, {
+        organizationId: 'org_1',
+        includeMembers: true,
+        includeFeatures: true,
+      }),
+      getOrganizationCacheKey(instance, {organizationId: 'org_2'}),
+    ])
+    expect(keys.size).toBe(5)
+  })
+})

package/src/organization/organization.ts

@@ -0,0 +1,138 @@
+import {switchMap} from 'rxjs'
+
+import {getClientState} from '../client/clientStore'
+import {type SanityInstance} from '../store/createSanityInstance'
+import {defineFetcher} from '../store/fetcherStore'
+import {buildQuery} from '../utils/buildQuery'
+
+const API_VERSION = 'v2025-02-19'
+
+/** @public */
+export interface OrganizationMember {
+  sanityUserId: string
+  isCurrentUser: boolean
+  user: {
+    id: string
+    displayName: string
+    familyName: string
+    givenName: string
+    middleName: string | null
+    imageUrl: string | null
+    email: string
+    loginProvider: string
+  }
+  roles: Array<{
+    name: string
+    title: string
+    description?: string
+  }>
+}
+
+/**
+ * The base fields returned from `/organizations/<id>` for every organization.
+ * @public
+ */
+export interface OrganizationBase {
+  id: string
+  name: string
+  slug: string | null
+  createdAt: string
+  createdByUserId: string
+  updatedAt: string
+  deletedAt: string | null
+  dashboardStatus: 'enabled' | 'disabled'
+  aiFeaturesStatus: 'enabled' | 'disabled'
+  mediaLibraryStatus: 'enabled' | 'disabled'
+  requestAccessStatus: 'allowed' | 'disabled'
+  telemetryConsentStatus: 'allowed' | 'msa_denied' | 'customer_denied'
+  oauthAppsStatus: 'allowed' | 'blocked'
+  defaultRoleName: string
+  domains: string[] | null
+}
+
+/** @public */
+export interface OrganizationOptions<
+  IncludeMembers extends boolean = false,
+  IncludeFeatures extends boolean = false,
+> {
+  includeMembers?: IncludeMembers
+  includeFeatures?: IncludeFeatures
+  organizationId: string
+}
+
+/**
+ * An `Organization` with `members` and/or `features` conditionally included
+ * based on the query options used to fetch it.
+ * @public
+ */
+export type Organization<
+  IncludeMembers extends boolean = false,
+  IncludeFeatures extends boolean = false,
+> = OrganizationBase &
+  // `boolean extends T` is non-distributive — true only when T is the wide
+  // `boolean`, in which case the field is optional. Literal `true`/`false`
+  // fall through to the strict branch.
+  (boolean extends IncludeMembers
+    ? {members?: OrganizationMember[]}
+    : IncludeMembers extends true
+      ? {members: OrganizationMember[]}
+      : unknown) &
+  (boolean extends IncludeFeatures
+    ? {features?: string[]}
+    : IncludeFeatures extends true
+      ? {features: string[]}
+      : unknown)
+
+function resolveOrganizationId(options?: OrganizationOptions<boolean, boolean>) {
+  const organizationId = options?.organizationId
+  if (!organizationId) {
+    throw new Error('An organizationId is required to use the organization API.')
+  }
+  return organizationId
+}
+
+function normalizeOrganizationOptions(options?: OrganizationOptions<boolean, boolean>) {
+  return {
+    includeMembers: options?.includeMembers ?? false,
+    includeFeatures: options?.includeFeatures ?? false,
+  }
+}
+
+/** @internal */
+export function getOrganizationCacheKey(
+  _instance: SanityInstance,
+  options?: OrganizationOptions<boolean, boolean>,
+): string {
+  const organizationId = resolveOrganizationId(options)
+  const {includeMembers, includeFeatures} = normalizeOrganizationOptions(options)
+  const membersKey = includeMembers ? ':members' : ''
+  const featuresKey = includeFeatures ? ':features' : ''
+  return `organization:${organizationId}${membersKey}${featuresKey}`
+}
+
+/**
+ * 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
+ */
+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

@@ -0,0 +1,56 @@
+import {expectTypeOf, test} from 'vitest'
+
+import {type OrganizationMember} from '../organization/organization'
+import {type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {type FetcherSnapshot} from '../store/fetcherStore'
+import {type Organizations, organizations} from './organizations'
+
+const instance = {} as SanityInstance
+
+test('organizations.resolveState — resolves the wide-boolean list shape', () => {
+  expectTypeOf(organizations.resolveState(instance)).resolves.toEqualTypeOf<
+    Organizations<boolean, boolean>
+  >()
+})
+
+test('organizations.getState — exposes the snapshot envelope', () => {
+  expectTypeOf(organizations.getState(instance)).toEqualTypeOf<
+    StateSource<FetcherSnapshot<Organizations<boolean, boolean>>>
+  >()
+})
+
+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', () => {
+  type Keys = keyof Organizations<false, false>[number]
+  expectTypeOf<Keys>().toEqualTypeOf<
+    | 'id'
+    | 'name'
+    | 'slug'
+    | 'createdAt'
+    | 'updatedAt'
+    | 'defaultRoleName'
+    | 'dashboardStatus'
+    | 'aiFeaturesStatus'
+  >()
+})
+
+test('Organizations<true, false>[number] exposes members[]', () => {
+  type Item = Organizations<true, false>[number]
+  expectTypeOf<Item['members']>().toEqualTypeOf<OrganizationMember[]>()
+})
+
+test('Organizations<false, true>[number] exposes features[]', () => {
+  type Item = Organizations<false, true>[number]
+  expectTypeOf<Item['features']>().toEqualTypeOf<string[]>()
+})
+
+test('Organizations<true, true>[number] exposes both members[] and features[]', () => {
+  type Item = Organizations<true, true>[number]
+  expectTypeOf<Item['members']>().toEqualTypeOf<OrganizationMember[]>()
+  expectTypeOf<Item['features']>().toEqualTypeOf<string[]>()
+})