@sanity/client 7.1.0 → 7.2.1

package/src/releases/createRelease.ts

@@ -0,0 +1,53 @@
+import type {BaseActionOptions, CreateReleaseAction, ReleaseDocument} from '@sanity/client'
+
+import {generateReleaseId} from '../util/createVersionId'
+
+interface ReleaseOrOptions extends BaseActionOptions {
+  releaseId?: string
+  metadata?: Partial<ReleaseDocument['metadata']>
+}
+
+interface CompleteCreateReleaseAction extends CreateReleaseAction {
+  metadata: ReleaseDocument['metadata']
+}
+
+const getArgs = (
+  releaseOrOptions?: ReleaseOrOptions,
+  maybeOptions?: BaseActionOptions,
+): [string, Partial<ReleaseDocument['metadata']>, BaseActionOptions | undefined] => {
+  const isReleaseInput =
+    typeof releaseOrOptions === 'object' &&
+    releaseOrOptions !== null &&
+    ('releaseId' in releaseOrOptions || 'metadata' in releaseOrOptions)
+
+  if (isReleaseInput) {
+    const {releaseId = generateReleaseId(), metadata = {}} = releaseOrOptions
+    return [releaseId, metadata, maybeOptions]
+  }
+
+  return [generateReleaseId(), {}, releaseOrOptions as BaseActionOptions]
+}
+
+/** @internal */
+export const createRelease = (
+  releaseOrOptions?: ReleaseOrOptions,
+  maybeOptions?: BaseActionOptions,
+): {
+  action: CompleteCreateReleaseAction
+  options?: BaseActionOptions
+} => {
+  const [releaseId, metadata, options] = getArgs(releaseOrOptions, maybeOptions)
+
+  const finalMetadata: ReleaseDocument['metadata'] = {
+    ...metadata,
+    releaseType: metadata.releaseType || 'undecided',
+  }
+
+  const createAction: CompleteCreateReleaseAction = {
+    actionType: 'sanity.action.release.create',
+    releaseId,
+    metadata: finalMetadata,
+  }
+
+  return {action: createAction, options}
+}

package/src/types.ts

@@ -573,6 +573,24 @@ export type Mutation<R extends Record<string, Any> = Record<string, Any>> =
   | {delete: MutationSelection}
   | {patch: PatchMutationOperation}
 
+/** @public */
+export type ReleaseAction =
+  | CreateReleaseAction
+  | EditReleaseAction
+  | PublishReleaseAction
+  | ArchiveReleaseAction
+  | UnarchiveReleaseAction
+  | ScheduleReleaseAction
+  | UnscheduleReleaseAction
+  | DeleteReleaseAction
+
+/** @public */
+export type VersionAction =
+  | CreateVersionAction
+  | DiscardVersionAction
+  | ReplaceVersionAction
+  | UnpublishVersionAction
+
 /** @public */
 export type Action =
   | CreateAction
@@ -582,6 +600,136 @@ export type Action =
   | DiscardAction
   | PublishAction
   | UnpublishAction
+  | VersionAction
+  | ReleaseAction
+
+/**
+ * Creates a new release under the given id, with metadata.
+ *
+ * @public
+ */
+export interface CreateReleaseAction {
+  actionType: 'sanity.action.release.create'
+  releaseId: string
+  metadata?: Partial<ReleaseDocument['metadata']>
+}
+
+/**
+ * Edits an existing release, updating the metadata.
+ *
+ * @public
+ */
+export interface EditReleaseAction {
+  actionType: 'sanity.action.release.edit'
+  releaseId: string
+  patch: PatchOperations
+}
+
+/**
+ * Publishes all documents in a release at once.
+ *
+ * @public
+ */
+export interface PublishReleaseAction {
+  actionType: 'sanity.action.release.publish'
+  releaseId: string
+}
+
+/**
+ * Archives an `active` release, and deletes all the release documents.
+ *
+ * @public
+ */
+export interface ArchiveReleaseAction {
+  actionType: 'sanity.action.release.archive'
+  releaseId: string
+}
+
+/**
+ * Unarchived an `archived` release, and restores all the release documents.
+ *
+ * @public
+ */
+export interface UnarchiveReleaseAction {
+  actionType: 'sanity.action.release.unarchive'
+  releaseId: string
+}
+
+/**
+ * Queues release for publishing at the given future time.
+ *
+ * @public
+ */
+export interface ScheduleReleaseAction {
+  actionType: 'sanity.action.release.schedule'
+  releaseId: string
+  publishAt: string
+}
+
+/**
+ * Unschedules a `scheduled` release, stopping it from being published.
+ *
+ * @public
+ */
+export interface UnscheduleReleaseAction {
+  actionType: 'sanity.action.release.unschedule'
+  releaseId: string
+}
+
+/**
+ * Deletes a `archived` or `published` release, and all the release documents versions.
+ *
+ * @public
+ */
+export interface DeleteReleaseAction {
+  actionType: 'sanity.action.release.delete'
+  releaseId: string
+}
+
+/**
+ * Creates a new version of an existing document, attached to the release as given
+ * by `document._id`
+ *
+ * @public
+ */
+export interface CreateVersionAction {
+  actionType: 'sanity.action.document.version.create'
+  publishedId: string
+  document: IdentifiedSanityDocumentStub
+}
+
+/**
+ * Delete a version of a document.
+ *
+ * @public
+ */
+export interface DiscardVersionAction {
+  actionType: 'sanity.action.document.version.discard'
+  versionId: string
+  purge?: boolean
+}
+
+/**
+ * Replace an existing version of a document.
+ *
+ * @public
+ */
+export interface ReplaceVersionAction {
+  actionType: 'sanity.action.document.version.replace'
+  document: IdentifiedSanityDocumentStub
+}
+
+/**
+ * Identify that a version of a document should be unpublished when
+ * the release that version is contained within is published.
+ *
+ * @public
+ */
+export interface UnpublishVersionAction {
+  actionType: 'sanity.action.document.version.unpublish'
+  versionId: string
+  publishedId: string
+}
 
 /**
  * Creates a new draft document. The published version of the document must not already exist.
@@ -614,6 +762,7 @@ export type CreateAction = {
  * At least one of the draft or published versions of the document must exist.
  *
  * @public
+ * @deprecated Use {@link ReplaceVersionAction} instead
  */
 export type ReplaceDraftAction = {
   actionType: 'sanity.action.document.replaceDraft'
@@ -686,6 +835,7 @@ export type DeleteAction = {
  * It is an error if it does not exist. If the purge flag is set, the document history is also deleted.
  *
  * @public
+ * @deprecated Use {@link DiscardVersionAction} instead
  */
 export type DiscardAction = {
   actionType: 'sanity.action.document.discard'
@@ -1244,6 +1394,71 @@ export interface ActionErrorItem {
   index: number
 }
 
+/** @internal */
+export type PartialExcept<T, K extends keyof T> = Pick<T, K> & Partial<Omit<T, K>>
+
+/** @beta */
+export type ReleaseState =
+  | 'active'
+  | 'archiving'
+  | 'unarchiving'
+  | 'archived'
+  | 'published'
+  | 'publishing'
+  | 'scheduled'
+  | 'scheduling'
+
+/** @internal */
+export type ReleaseType = 'asap' | 'scheduled' | 'undecided'
+
+/** @internal */
+export interface ReleaseDocument extends SanityDocument {
+  /**
+   * typically
+   * `_.releases.<name>`
+   */
+  _id: string
+  /**
+   * where a release has _id `_.releases.foo`, the name is `foo`
+   */
+  name: string
+  _type: 'system.release'
+  _createdAt: string
+  _updatedAt: string
+  _rev: string
+  state: ReleaseState
+  error?: {
+    message: string
+  }
+  finalDocumentStates?: {
+    /** Document ID */
+    id: string
+  }[]
+  /**
+   * If defined, it takes precedence over the intendedPublishAt, the state should be 'scheduled'
+   */
+  publishAt?: string
+  /**
+   * If defined, it provides the time the release was actually published
+   */
+  publishedAt?: string
+  metadata: {
+    title?: string
+    description?: string
+    intendedPublishAt?: string
+    releaseType: ReleaseType
+  }
+}
+
+/** @internal */
+export type EditableReleaseDocument = Omit<
+  PartialExcept<ReleaseDocument, '_id'>,
+  'metadata' | '_type'
+> & {
+  _id: string
+  metadata: Partial<ReleaseDocument['metadata']>
+}
+
 /**
  * DocumentValueSource is a path to a value within a document
  * @public

package/src/util/createVersionId.ts

@@ -0,0 +1,79 @@
+import {
+  getDraftId,
+  getVersionFromId,
+  getVersionId,
+  isDraftId,
+  isVersionId,
+} from '@sanity/client/csm'
+import {customAlphabet} from 'nanoid'
+
+import type {IdentifiedSanityDocumentStub, SanityDocumentStub} from '../types'
+import {validateVersionIdMatch} from '../validators'
+
+/**
+ * @internal
+ *
+ * ~24 years (or 7.54e+8 seconds) needed, in order to have a 1% probability of at least one collision if 10 ID's are generated every hour.
+ */
+export const generateReleaseId = customAlphabet(
+  'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789',
+  8,
+)
+
+/** @internal */
+export const getDocumentVersionId = (publishedId: string, releaseId?: string) =>
+  releaseId ? getVersionId(publishedId, releaseId) : getDraftId(publishedId)
+
+/** @internal */
+export function deriveDocumentVersionId(
+  op: string,
+  {
+    releaseId,
+    publishedId,
+    document,
+  }: {
+    releaseId?: string
+    publishedId?: string
+    document: SanityDocumentStub | IdentifiedSanityDocumentStub
+  },
+): string {
+  if (publishedId && document._id) {
+    const versionId = getDocumentVersionId(publishedId, releaseId)
+    validateVersionIdMatch(versionId, document)
+    return versionId
+  }
+
+  if (document._id) {
+    const isDraft = isDraftId(document._id)
+    const isVersion = isVersionId(document._id)
+
+    if (!isDraft && !isVersion) {
+      throw new Error(
+        `\`${op}()\` requires a document with an \`_id\` that is a version or draft ID`,
+      )
+    }
+
+    if (releaseId) {
+      if (isDraft) {
+        throw new Error(
+          `\`${op}()\` was called with a document ID (\`${document._id}\`) that is a draft ID, but a release ID (\`${releaseId}\`) was also provided.`,
+        )
+      }
+
+      const builtVersionId = getVersionFromId(document._id)
+      if (builtVersionId !== releaseId) {
+        throw new Error(
+          `\`${op}()\` was called with a document ID (\`${document._id}\`) that is a version ID, but the release ID (\`${releaseId}\`) does not match the document's version ID (\`${builtVersionId}\`).`,
+        )
+      }
+    }
+
+    return document._id
+  }
+
+  if (publishedId) {
+    return getDocumentVersionId(publishedId, releaseId)
+  }
+
+  throw new Error(`\`${op}()\` requires either a publishedId or a document with an \`_id\``)
+}

package/src/validators.ts

@@ -1,4 +1,4 @@
-import type {Any, InitializedClientConfig} from './types'
+import type {Any, InitializedClientConfig, SanityDocumentStub} from './types'
 
 const VALID_ASSET_TYPES = ['image', 'file']
 const VALID_INSERT_LOCATIONS = ['before', 'after', 'replace']
@@ -43,6 +43,28 @@ export const requireDocumentId = (op: string, doc: Record<string, Any>) => {
   validateDocumentId(op, doc._id)
 }
 
+export const validateDocumentType = (op: string, type: string) => {
+  if (typeof type !== 'string') {
+    throw new Error(`\`${op}()\`: \`${type}\` is not a valid document type`)
+  }
+}
+
+export const requireDocumentType = (op: string, doc: Record<string, Any>) => {
+  if (!doc._type) {
+    throw new Error(`\`${op}()\` requires that the document contains a type (\`_type\` property)`)
+  }
+
+  validateDocumentType(op, doc._type)
+}
+
+export const validateVersionIdMatch = (builtVersionId: string, document: SanityDocumentStub) => {
+  if (document._id && document._id !== builtVersionId) {
+    throw new Error(
+      `The provided document ID (\`${document._id}\`) does not match the generated version ID (\`${builtVersionId}\`)`,
+    )
+  }
+}
+
 export const validateInsert = (at: string, selector: string, items: Any[]) => {
   const signature = 'insert(at, selector, items)'
   if (VALID_INSERT_LOCATIONS.indexOf(at) === -1) {