AI Changes extension API reference

/**
 * Configuration options for the AI Changes extension
 */
export interface AiChangesOptions {
  /**
   * Creates the decorations for an AI Change
   *
   * @default getDefaultDecorations parameter
   *
   * @param options The current change, the list of changes, whether the current
   * change is selected, a function to get the default decorations, the editor
   * instance, the previous document before the AI made changes, and the current
   * document after the AI made changes.
   * @returns A list of ProseMirror decorations to be applied to document
   */
  getCustomDecorations: (options: GetCustomDecorationsOptions) => Decoration[];
}

/**
 * Options for the `getCustomDecorations` function
 */
export interface GetCustomDecorationsOptions {
  /**
   * The current change being processed
   */
  change: AiChange;
  /**
   * The list of changes made by the AI
   */
  changes: AiChange[];
  /**
   * Whether the current change is selected
   */
  isSelected: boolean;
  /**
   * Get the default decorations that the extension would apply to the document
   * if the `getCustomDecorations` function was not provided.
   *
   * @returns A list of default decorations to be applied to the document
   */
  getDefaultDecorations: () => Decoration[];
  /**
   * The Tiptap Editor instance
   */
  editor: Editor;
  /**
   * The previous document before the AI made changes
   */
  previousDoc: Node | null;
  /**
   * The current document after the AI made changes
   */
  currentDoc: Node;
}

/**
 * Commands of the AI Changes extension
 */
declare module '@tiptap/core' {
  interface Commands<ReturnType> {
    previewAiAgentChanges: {
      /**
       * Starts tracking AI changes in the document, and showing the differences
       * between the current document and the initial document in the editor.
       *
       * @param doc The initial document to compare against. If not provided, the current document will be used.
       */
      startTrackingAiChanges: (doc?: Node) => ReturnType

      /**
       * Finishes tracking AI changes in the document. Sets the initial document
       * to `null`, and stops showing the differences between the current document.
       */
      stopTrackingAiChanges: () => ReturnType

      /**
       * Accepts all AI changes in the document. Sets the initial document to
       * the current document.
       */
      acceptAllAiChanges: () => ReturnType

      /**
       * Undoes all AI changes in the document, and restores the initial document.
       */
      rejectAllAiChanges: () => ReturnType

      /**
       * Accepts a specific AI change in the document. It modifies the initial document
       * so that it has the same content as the current document in that specific change
       * @param id The ID of the change to accept
       */
      acceptAiChange: (id: string) => ReturnType

      /**
       * Rejects a specific AI change in the document. The current document will have the
       * same content as the initial document in that specific change
       *
       * @param id The ID of the change to reject
       * @returns
       */
      rejectAiChange: (id: string) => ReturnType

      /**
       * Show or hide the AI changes in the document.
       *
       * @param show Whether to show the AI changes or not
       */
      setShowAiChanges: (show: boolean) => ReturnType
      /**
       * Sets a change as selected. Sets the cursor at the beginning of the change's range.
       *
       * @param id The ID of the change to select
       */
      selectAiChange: (id: string) => ReturnType
    }
  }
}

/**
 * Internal storage properties for the AI Changes extension.
 */
export interface AiChangesStorage {
  /** Key for the ProseMirror plugin used by the extension */
  pluginKey: PluginKey<AiChangesProsemirrorPluginState>
  /**
   * Returns a list of changes made to the document by the AI
   *
   * @returns The list of changes made to the document
   */
  getChanges: () => AiChange[]
  /**
   * Returns the currently selected change in the document. The selected change
   * has the cursor inside its range.
   *
   * @returns The currently selected change in the document, or null if no change is selected
   */
  getSelectedChange: () => AiChange | null
  /**
   * Returns the previous document before the AI made changes. If the extension is
   * currently not tracking changes, this will be `null`.
   *
   * @returns The previous document before the AI made changes, or null if no changes are being tracked
   */
  getPreviousDoc: () => Node | null
  /**
   * Returns `true` if the extension is currently tracking changes made by the AI
   * or `false` if it is not.
   *
   * @returns `true` if the extension is currently tracking changes made by the AI, or `false` if it is not
   */
  getIsTrackingAiChanges: () => boolean
  /**
   * Returns `true` if the extension is currently showing the changes made by the AI
   * or `false` if it is not.
   *
   * @returns `true` if the extension is currently showing the changes made by the AI, or `false` if it is not
   */
  getIsShowingAiChanges: () => boolean
}

import { Range } from '@tiptap/core'

/**
 * A change made by the AI Agent. The changes are computed by making a diff
 * between the old and new document (before and after the AI Agent's changes).
 * The change objects are stored in the extension storage of the AI Changes
 * extension and used to render the changes in the editor.
 */
export interface AiChange {
  /**
   * Unique identifier for the change.
   */
  id: string
  /**
   * The range of content that was deleted in the old document.
   */
  oldRange: Range
  /**
   * The range of content that was added in the new document.
   * This is the range of content that was inserted by the AI Agent.
   */
  newRange: Range
}