@sanity/sdk 0.0.0-alpha.8 → 0.0.0-alpha.9

package/dist/index.d.ts

@@ -3,14 +3,23 @@ import {ChannelInstance} from '@sanity/comlink'
 import {ClientConfig} from '@sanity/client'
 import {Controller} from '@sanity/comlink'
 import {CurrentUser} from '@sanity/types'
+import {IndexTuple} from '@sanity/types'
+import {ListenEvent} from '@sanity/client'
 import {Message} from '@sanity/comlink'
+import {Mutation} from '@sanity/types'
 import {Node as Node_2} from '@sanity/comlink'
 import {NodeInput} from '@sanity/comlink'
 import {Observable} from 'rxjs'
+import {PatchMutation} from '@sanity/mutate/_unstable_store'
+import {PatchOperations} from '@sanity/types'
+import {PathSegment} from '@sanity/types'
 import {Role} from '@sanity/types'
 import {SanityClient} from '@sanity/client'
+import {SanityDocument} from '@sanity/types'
+import {SanityDocumentLike} from '@sanity/types'
 import {SchemaTypeDefinition} from '@sanity/types'
 import {SortOrderingItem} from '@sanity/types'
+import {Subject} from 'rxjs'
 import {Subscribable} from 'rxjs'
 import {SyncTag} from '@sanity/client'
 
@@ -20,6 +29,117 @@ export declare interface ActionContext<TState> {
   state: ResourceState<TState>
 }
 
+/** @beta */
+export declare interface ActionErrorEvent {
+  type: 'error'
+  documentId: string
+  transactionId: string
+  message: string
+  error: unknown
+}
+
+declare type ActionMap = {
+  create: 'sanity.action.document.version.create'
+  discard: 'sanity.action.document.version.discard'
+  unpublish: 'sanity.action.document.unpublish'
+  delete: 'sanity.action.document.delete'
+  edit: 'sanity.action.document.edit'
+  publish: 'sanity.action.document.publish'
+}
+
+/** @beta */
+export declare interface ActionsResult<TDocument extends SanityDocument = SanityDocument> {
+  transactionId: string
+  documents: DocumentSet<TDocument>
+  previous: DocumentSet<TDocument>
+  previousRevs: {
+    [documentId: string]: string | undefined
+  }
+  appeared: string[]
+  updated: string[]
+  disappeared: string[]
+  submitted: () => ReturnType<SanityClient['action']>
+}
+
+/**
+ * Represents a transaction that has been applied locally but has not been
+ * committed/transitioned-to-outgoing. These transactions are visible to the
+ * user but may be rebased upon a new working document set. Applied transactions
+ * also contain the resulting `outgoingActions` that will be submitted to
+ * Content Lake. These `outgoingActions` depend on the state of the working
+ * documents so they are recomputed on rebase and are only relevant to applied
+ * actions (we cannot compute `outgoingActions` for queued transactions because
+ * we haven't resolved the set of documents the actions are dependent on yet).
+ *
+ * In order to support better conflict resolution, the original `previous` set
+ * is saved as the `base` set.
+ */
+declare interface AppliedTransaction extends QueuedTransaction {
+  /**
+   * the resulting set of documents after the actions have been applied
+   */
+  working: DocumentSet
+  /**
+   * the previous set of documents before the action was applied
+   */
+  previous: DocumentSet
+  /**
+   * the original `previous` document set captured when this action was
+   * originally applied. this is used as a reference point to do a 3-way merge
+   * if this applied transaction ever needs to be reapplied on a different
+   * set of documents.
+   */
+  base: DocumentSet
+  /**
+   * the `_rev`s from `previous` document set
+   */
+  previousRevs: {
+    [TDocumentId in string]?: string
+  }
+  /**
+   * a timestamp for when this transaction was applied locally
+   */
+  timestamp: string
+  /**
+   * the resulting HTTP actions derived from the state of the `working` document
+   * set. these are sent to Content Lake as-is when this transaction is batched
+   * and transitioned into an outgoing transaction.
+   */
+  outgoingActions: HttpAction[]
+  /**
+   * similar to `outgoingActions` but comprised of mutations instead of action.
+   * this left here for debugging purposes but could be used to send mutations
+   * to Content Lake instead of actions.
+   */
+  outgoingMutations: Mutation[]
+}
+
+/** @beta */
+export declare function applyActions<TDocument extends SanityDocument>(
+  instance: SanityInstance | ActionContext<DocumentStoreState>,
+  action: DocumentAction<TDocument> | DocumentAction<TDocument>[],
+  options?: ApplyActionsOptions,
+): Promise<ActionsResult<TDocument>>
+
+/** @beta */
+export declare function applyActions(
+  instance: SanityInstance | ActionContext<DocumentStoreState>,
+  action: DocumentAction | DocumentAction[],
+  options?: ApplyActionsOptions,
+): Promise<ActionsResult>
+
+/** @beta */
+export declare interface ApplyActionsOptions {
+  /**
+   * Optionally provide an ID to be used as this transaction ID
+   */
+  transactionId?: string
+  /**
+   * Set this to true to prevent this action from being batched with others.
+   */
+  disableBatching?: boolean
+}
+
 /**
  * Configuration options for creating an auth store.
  *
@@ -191,6 +311,20 @@ export declare interface ComlinkNodeState {
   nodes: Map<string, NodeEntry>
 }
 
+/** @beta */
+export declare function createDocument<TDocument extends SanityDocumentLike>(
+  doc: DocumentTypeHandle<TDocument> | DocumentHandle<TDocument>,
+): CreateDocumentAction<TDocument>
+
+/** @beta */
+export declare interface CreateDocumentAction<
+  TDocument extends SanityDocumentLike = SanityDocumentLike,
+> {
+  type: 'document.create'
+  documentId: string
+  documentType: TDocument['_type']
+}
+
 /**
  * @public
  */
@@ -200,7 +334,7 @@ export declare const createDocumentListStore: (instance: SanityInstance | Action
   getState: BoundResourceAction<
     [],
     StateSource<{
-      results: DocumentHandle[]
+      results: DocumentHandle_2[]
       isPending: boolean
       count: number
       hasMore: boolean
@@ -227,6 +361,38 @@ export declare function createSanityInstance({
 
 export {CurrentUser}
 
+/**
+ * Given a type T and an array of “access keys” Parts, recursively index into T.
+ *
+ * If a part is a key, it looks up that property.
+ * If T is an array and the part is a number, it “indexes” into the element type.
+ */
+declare type DeepGet<T, TParts extends readonly unknown[]> = TParts extends [
+  infer Head,
+  ...infer Tail,
+]
+  ? Head extends keyof T
+    ? DeepGet<T[Head], Tail>
+    : T extends Array<infer U>
+      ? Head extends number
+        ? DeepGet<U, Tail>
+        : never
+      : never
+  : T
+
+/** @beta */
+export declare function deleteDocument<TDocument extends SanityDocumentLike>(
+  doc: string | DocumentHandle<TDocument>,
+): DeleteDocumentAction<TDocument>
+
+/** @beta */
+export declare interface DeleteDocumentAction<
+  _TDocument extends SanityDocumentLike = SanityDocumentLike,
+> {
+  type: 'document.delete'
+  documentId: string
+}
+
 /**
  * Calls the destroy method on the controller and resets the controller state.
  * @public
@@ -235,12 +401,81 @@ export declare const destroyController: (
   actionContext: ActionContext<ComlinkControllerState>,
 ) => void
 
+/** @beta */
+export declare function discardDocument<TDocument extends SanityDocumentLike>(
+  doc: string | DocumentHandle<TDocument>,
+): DiscardDocumentAction<TDocument>
+
+/** @beta */
+export declare interface DiscardDocumentAction<
+  _TDocument extends SanityDocumentLike = SanityDocumentLike,
+> {
+  type: 'document.discard'
+  documentId: string
+}
+
+/** @beta */
+export declare type DocumentAction<TDocument extends SanityDocumentLike = SanityDocumentLike> =
+  | CreateDocumentAction<TDocument>
+  | DeleteDocumentAction<TDocument>
+  | EditDocumentAction<TDocument>
+  | PublishDocumentAction<TDocument>
+  | UnpublishDocumentAction<TDocument>
+  | DiscardDocumentAction<TDocument>
+
+/** @beta */
+export declare interface DocumentCreatedEvent {
+  type: 'created'
+  documentId: string
+  outgoing: OutgoingTransaction
+}
+
+/** @beta */
+export declare interface DocumentDeletedEvent {
+  type: 'deleted'
+  documentId: string
+  outgoing: OutgoingTransaction
+}
+
+/** @beta */
+export declare interface DocumentDiscardedEvent {
+  type: 'discarded'
+  documentId: string
+  outgoing: OutgoingTransaction
+}
+
+/** @beta */
+export declare interface DocumentEditedEvent {
+  type: 'edited'
+  documentId: string
+  outgoing: OutgoingTransaction
+}
+
+/** @beta */
+export declare type DocumentEvent =
+  | ActionErrorEvent
+  | TransactionRevertedEvent
+  | TransactionAcceptedEvent
+  | DocumentRebaseErrorEvent
+  | DocumentEditedEvent
+  | DocumentCreatedEvent
+  | DocumentDeletedEvent
+  | DocumentPublishedEvent
+  | DocumentUnpublishedEvent
+  | DocumentDiscardedEvent
+
+/** @beta */
+export declare interface DocumentHandle<TDocument extends SanityDocumentLike = SanityDocumentLike> {
+  _id: string
+  _type: TDocument['_type']
+}
+
 /**
  * Represents an identifier to a Sanity document, containing its `_id` to pull
  * the document from content lake and its `_type` to look up its schema type.
  * @public
  */
-export declare interface DocumentHandle {
+declare interface DocumentHandle_2 {
   _id: string
   _type: string
 }
@@ -267,10 +502,121 @@ export declare interface DocumentListState {
   syncTags: SyncTag[]
   limit: number
   count: number
-  results: DocumentHandle[]
+  results: DocumentHandle_2[]
   isPending: boolean
 }
 
+/** @beta */
+export declare interface DocumentPublishedEvent {
+  type: 'published'
+  documentId: string
+  outgoing: OutgoingTransaction
+}
+
+/** @beta */
+declare interface DocumentRebaseErrorEvent {
+  type: 'rebase-error'
+  documentId: string
+  transactionId: string
+  message: string
+  error: unknown
+}
+
+/**
+ * Represents a set of document that will go into `applyMutations`. Before
+ * applying a mutation, it's expected that all relevant documents that the
+ * mutations affect are included, including those that do not exist yet.
+ * Documents that don't exist have a `null` value.
+ */
+declare type DocumentSet<TDocument extends SanityDocument = SanityDocument> = {
+  [TDocumentId in string]?: TDocument | null
+}
+
+declare interface DocumentState {
+  id: string
+  /**
+   * the "remote" local copy that matches the server. represents the last known
+   * server state. this gets updated every time we confirm remote patches
+   */
+  remote?: SanityDocument | null
+  /**
+   * the current ephemeral working copy that includes local optimistic changes
+   * that have not yet been confirmed by the server
+   */
+  local?: SanityDocument | null
+  /**
+   * the revision that our remote document is at
+   */
+  remoteRev?: string | null
+  /**
+   * Array of subscription IDs. This document state will be deleted if there are
+   * no subscribers.
+   */
+  subscriptions: string[]
+  /**
+   * An object keyed by transaction ID of revisions sent out but that have not
+   * yet been verified yet. When an applied transaction is transitioned to an
+   * outgoing transaction, it also adds unverified revisions for each document
+   * that is part of that outgoing transaction. Transactions are submitted to
+   * the server with a locally generated transaction ID. This way we can observe
+   * when our transaction comes back through the shared listener. Each listener
+   * event that comes back contains a `previousRev`. If we see our own
+   * transaction with a different `previousRev` than expected, we can rebase our
+   * local transactions on top of this new remote.
+   */
+  unverifiedRevisions?: {
+    [TTransactionId in string]?: UnverifiedDocumentRevision
+  }
+}
+
+declare interface DocumentStoreState {
+  documentStates: {
+    [TDocumentId in string]?: DocumentState
+  }
+  queued: QueuedTransaction[]
+  applied: AppliedTransaction[]
+  outgoing?: OutgoingTransaction
+  error?: unknown
+  sharedListener: Observable<ListenEvent<SanityDocument>>
+  fetchDocument: (documentId: string) => Observable<SanityDocument | null>
+  events: Subject<DocumentEvent>
+}
+
+/** @beta */
+export declare interface DocumentTypeHandle<
+  TDocument extends SanityDocumentLike = SanityDocumentLike,
+> {
+  _id?: string
+  _type: TDocument['_type']
+}
+
+/** @beta */
+export declare interface DocumentUnpublishedEvent {
+  type: 'unpublished'
+  documentId: string
+  outgoing: OutgoingTransaction
+}
+
+/** @beta */
+export declare function editDocument<TDocument extends SanityDocumentLike>(
+  sanityMutatePatch: PatchMutation,
+): EditDocumentAction<TDocument>
+
+/** @beta */
+export declare function editDocument<TDocument extends SanityDocumentLike>(
+  doc: string | DocumentHandle<TDocument>,
+  patches: PatchOperations | PatchOperations[],
+): EditDocumentAction<TDocument>
+
+/** @beta */
+export declare interface EditDocumentAction<
+  _TDocument extends SanityDocumentLike = SanityDocumentLike,
+> {
+  type: 'document.edit'
+  documentId: string
+  patches: PatchOperations[]
+}
+
 /**
  * Error state from the auth state.
  * @public
@@ -326,6 +672,36 @@ export declare const getCurrentUserState: ResourceAction<
   StateSource<CurrentUser | null>
 >
 
+/** @beta */
+export declare function getDocumentState<
+  TDocument extends SanityDocument,
+  TPath extends JsonMatchPath<TDocument>,
+>(
+  instance: SanityInstance | ActionContext<DocumentStoreState>,
+  doc: string | DocumentHandle<TDocument>,
+  path: TPath,
+): StateSource<JsonMatch<TDocument, TPath> | undefined>
+
+/** @beta */
+export declare function getDocumentState<TDocument extends SanityDocument>(
+  instance: SanityInstance | ActionContext<DocumentStoreState>,
+  doc: string | DocumentHandle<TDocument>,
+): StateSource<TDocument | null>
+
+/** @beta */
+export declare function getDocumentState(
+  instance: SanityInstance | ActionContext<DocumentStoreState>,
+  doc: string | DocumentHandle,
+  path?: string,
+): StateSource<unknown>
+
+/** @beta */
+export declare const getDocumentSyncStatus: ResourceAction<
+  DocumentStoreState,
+  [doc: string | DocumentHandle<SanityDocumentLike>],
+  StateSource<boolean | undefined>
+>
+
 /**
  * Retrieves the global, project-less client.
  * @public
@@ -388,7 +764,7 @@ export declare const getPreviewState: ResourceAction<
  * @public
  */
 export declare interface GetPreviewStateOptions {
-  document: DocumentHandle
+  document: DocumentHandle_2
 }
 
 /**
@@ -416,6 +792,77 @@ export declare const handleCallback: ResourceAction<
   Promise<string | false>
 >
 
+declare type HttpAction =
+  | {
+      actionType: ActionMap['create']
+      publishedId: string
+      attributes: SanityDocumentLike
+    }
+  | {
+      actionType: ActionMap['discard']
+      versionId: string
+      purge?: boolean
+    }
+  | {
+      actionType: ActionMap['unpublish']
+      draftId: string
+      publishedId: string
+    }
+  | {
+      actionType: ActionMap['delete']
+      publishedId: string
+      includeDrafts?: string[]
+    }
+  | {
+      actionType: ActionMap['edit']
+      draftId: string
+      publishedId: string
+      patch: PatchOperations
+    }
+  | ({
+      actionType: ActionMap['publish']
+      draftId: string
+      publishedId: string
+    } & OptimisticLock)
+
+/**
+ * Given a document type TDocument and a JSON Match path string TPath,
+ * compute the type found at that path.
+ * @beta
+ */
+export declare type JsonMatch<TDocument extends SanityDocumentLike, TPath extends string> = DeepGet<
+  TDocument,
+  PathParts<TPath>
+>
+
+/**
+ * A very simplified implementation of [JSONMatch][0] that only supports:
+ * - descent e.g. `friend.name`
+ * - array index e.g. `items[-1]`
+ * - array matching with `_key` e.g. `items[_key=="dd9efe09"]`
+ * - array matching with a range e.g. `items[4:]`
+ *
+ * E.g. `friends[_key=="dd9efe09"].address.zip`
+ *
+ * [0]: https://www.sanity.io/docs/json-match
+ *
+ * @beta
+ */
+export declare function jsonMatch<
+  TDocument extends SanityDocumentLike,
+  TPath extends JsonMatchPath<TDocument>,
+>(input: TDocument, path: TPath): MatchEntry<JsonMatch<TDocument, TPath>>[]
+
+/** @beta */
+export declare function jsonMatch<TValue>(input: unknown, path: string): MatchEntry<TValue>[]
+
+/**
+ * Computing the full possible paths may be possible but is hard to compute
+ * within the type system for complex document types so we use string.
+ * @beta
+ */
+export declare type JsonMatchPath<_TDocument extends SanityDocumentLike> = string
+
 /**
  * Logged-in state from the auth state.
  * @public
@@ -449,6 +896,11 @@ export declare type LoggingInAuthState = {
  */
 export declare const logout: ResourceAction<AuthStoreState, [], Promise<void>>
 
+declare type MatchEntry<T = unknown> = {
+  value: T
+  path: SingleValuePath
+}
+
 /**
  * Individual node with its relevant options
  * @public
@@ -459,6 +911,86 @@ declare interface NodeEntry {
   refCount: number
 }
 
+declare type OptimisticLock = {
+  ifDraftRevisionId?: string
+  ifPublishedRevisionId?: string
+}
+
+/**
+ * Represents a set of applied transactions batched into a single outgoing
+ * transaction. An outgoing transaction is the result of batching many applied
+ * actions. An outgoing transaction may be reverted locally if the server
+ * does not accept it.
+ */
+declare interface OutgoingTransaction extends AppliedTransaction {
+  disableBatching: boolean
+  batchedTransactionIds: string[]
+}
+
+/**
+ * Parse one or more bracketed parts from a segment.
+ *
+ * It recursively “peels off” a bracketed part and then continues.
+ *
+ * For example, given the string:
+ *
+ * ```
+ * "[0][foo]"
+ * ```
+ *
+ * it produces:
+ *
+ * ```
+ * [ToNumber<"0">, "foo"]
+ * ```
+ */
+declare type ParseBracket<TInput extends string> = TInput extends `[${infer TPart}]${infer TRest}`
+  ? [ToNumber<TPart>, ...ParseSegment<TRest>]
+  : []
+
+/**
+ * Parse a single “segment” that may include bracket parts.
+ *
+ * For example, the literal
+ *
+ * ```
+ * "friends[0][1]"
+ * ```
+ *
+ * is parsed as:
+ *
+ * ```
+ * ["friends", 0, 1]
+ * ```
+ */
+declare type ParseSegment<TInput extends string> = TInput extends `${infer TProp}[${infer TRest}`
+  ? TProp extends ''
+    ? [...ParseBracket<`[${TRest}`>]
+    : [TProp, ...ParseBracket<`[${TRest}`>]
+  : TInput extends ''
+    ? []
+    : [TInput]
+
+/**
+ * Split the entire path string on dots “outside” of any brackets.
+ *
+ * For example:
+ * ```
+ * "friends[0].name"
+ * ```
+ *
+ * becomes:
+ *
+ * ```
+ * [...ParseSegment<"friends[0]">, ...ParseSegment<"name">]
+ * ```
+ *
+ * (We use a simple recursion that splits on the first dot.)
+ */
+declare type PathParts<TPath extends string> = TPath extends `${infer TLeft}.${infer TRight}`
+  ? [...ParseSegment<TLeft>, ...PathParts<TRight>]
+  : ParseSegment<TPath>
+
 /**
  * @public
  */
@@ -508,6 +1040,42 @@ export declare interface PreviewValue {
   }
 }
 
+/** @beta */
+export declare function publishDocument<TDocument extends SanityDocumentLike>(
+  doc: string | DocumentHandle<TDocument>,
+): PublishDocumentAction<TDocument>
+
+/** @beta */
+export declare interface PublishDocumentAction<
+  _TDocument extends SanityDocumentLike = SanityDocumentLike,
+> {
+  type: 'document.publish'
+  documentId: string
+}
+
+/**
+ * Represents a transaction that is queued to be applied but has not yet been
+ * applied. A transaction will remain in a queued state until all required
+ * documents for the transactions are available locally.
+ */
+declare interface QueuedTransaction {
+  /**
+   * the ID of this transaction. this is generated client-side.
+   */
+  transactionId: string
+  /**
+   * the high-level actions associated with this transaction. note that these
+   * actions don't mention draft IDs and is meant to abstract away the draft
+   * model from users.
+   */
+  actions: DocumentAction[]
+  /**
+   * An optional flag set to disable this transaction from being batched with
+   * other transactions.
+   */
+  disableBatching?: boolean
+}
+
 /**
  * Signals to the store that the consumer has stopped using the channel
  * @public
@@ -520,6 +1088,18 @@ export declare const releaseChannel: ResourceAction<ComlinkControllerState, [nam
  */
 export declare const releaseNode: ResourceAction<ComlinkNodeState, [name: string], void>
 
+/** @beta */
+export declare function resolveDocument<TDocument extends SanityDocument>(
+  instance: SanityInstance | ActionContext<DocumentStoreState>,
+  doc: string | DocumentHandle<TDocument>,
+): Promise<TDocument | null>
+
+/** @beta */
+export declare function resolveDocument(
+  instance: SanityInstance | ActionContext<DocumentStoreState>,
+  doc: string | DocumentHandle,
+): Promise<SanityDocument | null>
+
 /**
  * @public
  */
@@ -533,7 +1113,7 @@ export declare const resolvePreview: ResourceAction<
  * @public
  */
 export declare interface ResolvePreviewOptions {
-  document: DocumentHandle
+  document: DocumentHandle_2
 }
 
 /**
@@ -565,6 +1145,8 @@ export declare interface SanityConfig {
   schema?: SchemaConfig
 }
 
+export {SanityDocumentLike}
+
 /** @public */
 export declare interface SanityInstance {
   /**
@@ -592,15 +1174,63 @@ export declare interface SdkIdentity {
   readonly dataset: string
 }
 
+declare type SingleValuePath = Exclude<PathSegment, IndexTuple>[]
+
 /**
  * @public
  */
 export declare interface StateSource<T> {
-  subscribe: (onStoreChanged: () => void) => () => void
+  subscribe: (onStoreChanged?: () => void) => () => void
   getCurrent: () => T
   observable: Observable<T>
 }
 
+/** @beta */
+export declare const subscribeDocumentEvents: ResourceAction<
+  DocumentStoreState,
+  [eventHandler: (e: DocumentEvent) => void],
+  () => void
+>
+
+declare type ToNumber<TInput extends string> = TInput extends `${infer TNumber extends number}`
+  ? TNumber
+  : TInput
+
+/** @beta */
+export declare interface TransactionAcceptedEvent {
+  type: 'accepted'
+  outgoing: OutgoingTransaction
+  result: Awaited<ReturnType<SanityClient['action']>>
+}
+
+/** @beta */
+export declare interface TransactionRevertedEvent {
+  type: 'reverted'
+  message: string
+  error: unknown
+  outgoing: OutgoingTransaction
+}
+
+/** @beta */
+export declare function unpublishDocument<TDocument extends SanityDocumentLike>(
+  doc: string | DocumentHandle<TDocument>,
+): UnpublishDocumentAction<TDocument>
+
+/** @beta */
+export declare interface UnpublishDocumentAction<
+  _TDocument extends SanityDocumentLike = SanityDocumentLike,
+> {
+  type: 'document.unpublish'
+  documentId: string
+}
+
+declare interface UnverifiedDocumentRevision {
+  transactionId: string
+  documentId: string
+  previousRev: string | undefined
+  timestamp: string
+}
+
 /**
  * Represents the current state of a preview value along with a flag indicating whether
  * the preview data is still being fetched or is fully resolved.