feat: add Studio resource (#128)

Author: snocorp

src/definers/studios.ts

@@ -0,0 +1,34 @@
+import {validateStudio} from '../index.js'
+import type {BlueprintStudioConfig, BlueprintStudioResource} from '../types/studios.js'
+import {runValidation} from '../utils/validation.js'
+
+/**
+ * Defines a studio.
+ *
+ * ```ts
+ * defineStudio({
+ *   name: 'my-studio',
+ *   src: 'studios/my-studio',
+ *   autoUpdates: {
+ *     enabled: true
+ *   }
+ * })
+ * ```
+ * @param parameters The studio configuration
+ * @public
+ * @beta Deploying Studios via Blueprints is experimental. This may be subject to breaking changes.
+ * @category Definers
+ * @expandType BlueprintStudioConfig
+ * @returns The studio resource
+ * @hidden
+ */
+export function defineStudio(config: BlueprintStudioConfig): BlueprintStudioResource {
+  const studioResource: BlueprintStudioResource = {
+    ...config,
+    type: 'sanity.studio',
+  }
+
+  runValidation(() => validateStudio(studioResource))
+
+  return studioResource
+}

src/index.ts

@@ -16,6 +16,7 @@ export * from './definers/resources.js'
 export * from './definers/robots.js'
 export * from './definers/robotTokens.js'
 export * from './definers/roles.js'
+export * from './definers/studios.js'
 export * from './definers/webhooks.js'
 
 // TYPES - base types for all resources
@@ -37,6 +38,7 @@ export * from './types/resources.js'
 export * from './types/robots.js'
 export * from './types/robotTokens.js'
 export * from './types/roles.js'
+export * from './types/studios.js'
 export * from './types/webhooks.js'
 
 // VALIDATION - validation for all resources
@@ -53,6 +55,7 @@ export * from './validation/resources.js'
 export * from './validation/robots.js'
 export * from './validation/robotTokens.js'
 export * from './validation/roles.js'
+export * from './validation/studios.js'
 export * from './validation/webhooks.js'
 
 // Public BLUEPRINTS INTERNALS - published bucket of misc Blueprint types

src/types/studios.ts

@@ -0,0 +1,46 @@
+import type {BlueprintProjectResourceLifecycle, BlueprintResource} from '../index.js'
+
+/**
+ * Represents a Studio resource.
+ * @see https://www.sanity.io/docs/studio
+ * @beta This feature is subject to breaking changes.
+ * @category Resource Types
+ */
+export interface BlueprintStudioResource extends BlueprintResource<BlueprintProjectResourceLifecycle> {
+  type: 'sanity.studio'
+
+  /** The relative location of the studio source code. */
+  src: string
+
+  /**
+   * Auto update settings for the studio.
+   */
+  autoUpdates: {
+    /** Whether auto updates are enabled for the studio */
+    enabled: boolean
+
+    /** What "version"/"channel" to use for auto updates */
+    version?: string // 'next', 'stable', 'latest' or a semantic version (e.g., "1.2.3", "2.0.0-beta.1")
+  }
+
+  /** The base path of the studio URL. Defaults to '/' */
+  basePath?: string
+
+  /** Whether or not to minify the source code. Defaults to true. */
+  minify?: boolean
+
+  /** Whether or not to configure the reactCompiler. Defaults to false. */
+  reactCompiler?: boolean
+
+  /** Whether or not to generate source maps. Defaults to false. */
+  sourceMap?: boolean
+
+  /**
+   * The project ID of the project that contains your Studio.
+   *
+   * The `project` attribute must be defined if your blueprint is scoped to an organization.
+   */
+  project?: string
+}
+
+export interface BlueprintStudioConfig extends Omit<BlueprintStudioResource, 'type'> {}

src/validation/studios.ts

@@ -0,0 +1,76 @@
+import type {BlueprintError} from '../types/errors.js'
+import {validateResource} from './resources.js'
+
+/**
+ * Validates that the given resource is a valid Studio.
+ * @param resource The Studio resource
+ * @hidden
+ * @category Validation
+ * @returns A list of validation errors
+ */
+export function validateStudio(resource: unknown): BlueprintError[] {
+  if (!resource) return [{type: 'invalid_value', message: 'Studio config must be provided'}]
+  if (typeof resource !== 'object') return [{type: 'invalid_type', message: 'Studio config must be an object'}]
+
+  const errors: BlueprintError[] = validateResource(resource, {projectContained: true})
+
+  if ('type' in resource && resource.type !== 'sanity.studio') {
+    errors.push({type: 'invalid_value', message: 'Studio type must be `sanity.studio`'})
+  }
+
+  if (!('src' in resource) || !resource.src) {
+    errors.push({type: 'missing_parameter', message: 'Studio src is required'})
+  } else if (typeof resource.src !== 'string') {
+    errors.push({type: 'invalid_type', message: 'Studio src must be a string'})
+  }
+
+  if (!('autoUpdates' in resource) || !resource.autoUpdates) {
+    errors.push({type: 'missing_parameter', message: 'Studio autoUpdates is required'})
+  } else if (typeof resource.autoUpdates !== 'object') {
+    errors.push({type: 'invalid_type', message: 'Studio autoUpdates must be an object'})
+  } else {
+    if (!('enabled' in resource.autoUpdates)) {
+      errors.push({type: 'missing_parameter', message: 'Studio autoUpdates.enabled is required'})
+    } else if (typeof resource.autoUpdates.enabled !== 'boolean') {
+      errors.push({type: 'invalid_type', message: 'Studio autoUpdates.enabled must be a boolean'})
+    }
+
+    if ('version' in resource.autoUpdates) {
+      if (typeof resource.autoUpdates.version !== 'string') {
+        errors.push({type: 'invalid_type', message: 'Studio autoUpdates.version must be a string'})
+      }
+    }
+  }
+
+  if ('basePath' in resource) {
+    if (typeof resource.basePath !== 'string') {
+      errors.push({type: 'invalid_type', message: 'Studio basePath must be a string'})
+    }
+  }
+
+  if ('minify' in resource) {
+    if (typeof resource.minify !== 'boolean') {
+      errors.push({type: 'invalid_type', message: 'Studio minify must be a boolean'})
+    }
+  }
+
+  if ('reactCompiler' in resource) {
+    if (typeof resource.reactCompiler !== 'boolean') {
+      errors.push({type: 'invalid_type', message: 'Studio reactCompiler must be a boolean'})
+    }
+  }
+
+  if ('sourceMap' in resource) {
+    if (typeof resource.sourceMap !== 'boolean') {
+      errors.push({type: 'invalid_type', message: 'Studio sourceMap must be a boolean'})
+    }
+  }
+
+  if ('project' in resource) {
+    if (typeof resource.project !== 'string') {
+      errors.push({type: 'invalid_type', message: 'Studio project must be a string'})
+    }
+  }
+
+  return errors
+}

test/unit/definers/studios.test.ts

@@ -0,0 +1,69 @@
+import {afterEach, describe, expect, test, vi} from 'vitest'
+import * as studios from '../../../src/definers/studios.js'
+import * as index from '../../../src/index.js'
+import {defineBlueprintForResource} from '../../helpers/index.js'
+
+vi.mock(import('../../../src/index.js'), async (importOriginal) => {
+  const originalModule = await importOriginal()
+  return {
+    ...originalModule,
+    validateBlueprint: vi.fn(() => []),
+  }
+})
+
+describe('defineStudio', () => {
+  afterEach(() => {
+    vi.resetAllMocks()
+  })
+
+  test('should throw an error if validateStudio returns an error', () => {
+    const spy = vi.spyOn(index, 'validateStudio').mockImplementation(() => [{type: 'test', message: 'this is a test'}])
+    expect(() =>
+      defineBlueprintForResource(
+        studios.defineStudio({
+          name: 'studio-name',
+          src: 'studios/my-studio',
+          autoUpdates: {
+            enabled: true,
+          },
+        }),
+      ),
+    ).toThrow(/this is a test/)
+
+    expect(spy).toHaveBeenCalledOnce()
+  })
+
+  test('should accept a valid configuration and set the type', () => {
+    const studioResource = studios.defineStudio({
+      name: 'studio-name',
+      src: 'studios/my-studio',
+      autoUpdates: {
+        enabled: true,
+      },
+    })
+
+    expect(studioResource.type).toStrictEqual('sanity.studio')
+  })
+
+  test('should accept a valid configuration with a lifecycle', () => {
+    const studioResource = studios.defineStudio({
+      name: 'studio-name',
+      src: 'studios/my-studio',
+      autoUpdates: {
+        enabled: true,
+      },
+
+      lifecycle: {
+        deletionPolicy: 'allow',
+
+        ownershipAction: {
+          type: 'attach',
+          projectId: 'a1b2c3',
+          id: 'abc123',
+        },
+      },
+    })
+
+    expect(studioResource.lifecycle?.deletionPolicy).toStrictEqual('allow')
+  })
+})

test/unit/validation/studios.test.ts

@@ -0,0 +1,101 @@
+import {describe, expect, test} from 'vitest'
+import {validateStudio} from '../../../src/index.js'
+
+const validStudio = {
+  name: 'my-studio',
+  type: 'sanity.studio',
+  src: './studio',
+  autoUpdates: {enabled: true},
+}
+
+describe('validateStudio', () => {
+  test('should return an error if config is falsey', () => {
+    const errors = validateStudio(undefined)
+    expect(errors).toContainEqual({type: 'invalid_value', message: 'Studio config must be provided'})
+  })
+
+  test('should return an error if config is not an object', () => {
+    const errors = validateStudio(1)
+    expect(errors).toContainEqual({type: 'invalid_type', message: 'Studio config must be an object'})
+  })
+
+  test('should return an error if type is not sanity.studio', () => {
+    const errors = validateStudio({...validStudio, type: 'invalid'})
+    expect(errors).toContainEqual({type: 'invalid_value', message: 'Studio type must be `sanity.studio`'})
+  })
+
+  test('should return an error if src is not provided', () => {
+    const {src: _src, ...noSrc} = validStudio
+    const errors = validateStudio(noSrc)
+    expect(errors).toContainEqual({type: 'missing_parameter', message: 'Studio src is required'})
+  })
+
+  test('should return an error if src is not a string', () => {
+    const errors = validateStudio({...validStudio, src: 1})
+    expect(errors).toContainEqual({type: 'invalid_type', message: 'Studio src must be a string'})
+  })
+
+  test('should return an error if autoUpdates is not provided', () => {
+    const {autoUpdates: _au, ...noAutoUpdates} = validStudio
+    const errors = validateStudio(noAutoUpdates)
+    expect(errors).toContainEqual({type: 'missing_parameter', message: 'Studio autoUpdates is required'})
+  })
+
+  test('should return an error if autoUpdates is not an object', () => {
+    const errors = validateStudio({...validStudio, autoUpdates: 'yes'})
+    expect(errors).toContainEqual({type: 'invalid_type', message: 'Studio autoUpdates must be an object'})
+  })
+
+  test('should return an error if autoUpdates.enabled is not provided', () => {
+    const errors = validateStudio({...validStudio, autoUpdates: {}})
+    expect(errors).toContainEqual({type: 'missing_parameter', message: 'Studio autoUpdates.enabled is required'})
+  })
+
+  test('should return an error if autoUpdates.enabled is not a boolean', () => {
+    const errors = validateStudio({...validStudio, autoUpdates: {enabled: 'yes'}})
+    expect(errors).toContainEqual({type: 'invalid_type', message: 'Studio autoUpdates.enabled must be a boolean'})
+  })
+
+  test('should return an error if autoUpdates.version is not a string', () => {
+    const errors = validateStudio({...validStudio, autoUpdates: {enabled: true, version: 1}})
+    expect(errors).toContainEqual({type: 'invalid_type', message: 'Studio autoUpdates.version must be a string'})
+  })
+
+  test('should return an error if basePath is not a string', () => {
+    const errors = validateStudio({...validStudio, basePath: 1})
+    expect(errors).toContainEqual({type: 'invalid_type', message: 'Studio basePath must be a string'})
+  })
+
+  test('should return an error if minify is not a boolean', () => {
+    const errors = validateStudio({...validStudio, minify: 'yes'})
+    expect(errors).toContainEqual({type: 'invalid_type', message: 'Studio minify must be a boolean'})
+  })
+
+  test('should return an error if reactCompiler is not a boolean', () => {
+    const errors = validateStudio({...validStudio, reactCompiler: 'yes'})
+    expect(errors).toContainEqual({type: 'invalid_type', message: 'Studio reactCompiler must be a boolean'})
+  })
+
+  test('should return an error if sourceMap is not a boolean', () => {
+    const errors = validateStudio({...validStudio, sourceMap: 'yes'})
+    expect(errors).toContainEqual({type: 'invalid_type', message: 'Studio sourceMap must be a boolean'})
+  })
+
+  test('should return an error if project is not a string', () => {
+    const errors = validateStudio({...validStudio, project: 1})
+    expect(errors).toContainEqual({type: 'invalid_type', message: 'Studio project must be a string'})
+  })
+
+  test('should accept a valid configuration', () => {
+    const errors = validateStudio({
+      ...validStudio,
+      autoUpdates: {enabled: true, version: '^3.0.0'},
+      basePath: '/studio',
+      minify: true,
+      reactCompiler: false,
+      sourceMap: true,
+      project: 'abcdefg',
+    })
+    expect(errors, JSON.stringify(errors)).toHaveLength(0)
+  })
+})