@sanity/sdk 2.1.0 → 2.1.1

package/src/utils/defineIntent.ts

@@ -0,0 +1,244 @@
+/**
+ * Filter criteria for intent matching. Can be combined to create more specific intents.
+ *
+ * @example
+ * ```typescript
+ * // matches only geopoints in the travel-project project, production dataset
+ * const filter: IntentFilter = {
+ *   projectId: 'travel-project',
+ *   dataset: 'production',
+ *   types: ['geopoint']
+ * }
+ *
+ * // matches all documents in the travel-project project
+ * const filter: IntentFilter = {
+ *   projectId: 'travel-project',
+ *   types: ['*']
+ * }
+ *
+ * // matches geopoints in the travel-project production dataset and map pins in all projects in the org
+ * const filters: IntentFilter[] = [
+ *  {
+ *    projectId: 'travel-project',
+ *    dataset: 'production',
+ *    types: ['geopoint']
+ *  },
+ *  {
+ *    types: ['map-pin']
+ *  }
+ * ]
+ * ```
+ * @public
+ */
+export interface IntentFilter {
+  /**
+   * Project ID to match against
+   * @remarks When specified, the intent will only match for the specified project.
+   */
+  projectId?: string
+
+  /**
+   * Dataset to match against
+   * @remarks When specified, the intent will only match for the specified dataset. Requires projectId to be specified.
+   */
+  dataset?: string
+
+  /**
+   * Document types that this intent can handle
+   * @remarks This is required for all filters. Use ['*'] to match all document types.
+   */
+  types: string[]
+}
+
+/**
+ * Intent definition structure for registering user intents
+ * @public
+ */
+export interface Intent {
+  /**
+   * Unique identifier for this intent
+   * @remarks Should be unique across all registered intents in an org for proper matching
+   */
+  id: string
+
+  /**
+   * The action that this intent performs
+   * @remarks Examples: "view", "edit", "create", "delete"
+   */
+  action: 'view' | 'edit' | 'create' | 'delete'
+
+  /**
+   * Human-readable title for this intent
+   * @remarks Used for display purposes in UI or logs
+   */
+  title: string
+
+  /**
+   * Detailed description of what this intent does
+   * @remarks Helps users understand the purpose and behavior of the intent
+   */
+  description?: string
+
+  /**
+   * Array of filter criteria for intent matching
+   * @remarks At least one filter is required. Use `{types: ['*']}` to match everything
+   */
+  filters: IntentFilter[]
+}
+
+/**
+ * Creates a properly typed intent definition for registration with the backend.
+ *
+ * This utility function provides TypeScript support and validation for intent declarations.
+ * It is also used in the CLI if intents are declared as bare objects in an intents file.
+ *
+ * @param intent - The intent definition object
+ * @returns The same intent object with proper typing
+ *
+ * @example
+ * ```typescript
+ * // Specific filter for a document type
+ * const viewGeopointInMapApp = defineIntent({
+ *   id: 'viewGeopointInMapApp',
+ *   action: 'view',
+ *   title: 'View a geopoint in the map app',
+ *   description: 'This lets you view a geopoint in the map app',
+ *   filters: [
+ *     {
+ *       projectId: 'travel-project',
+ *       dataset: 'production',
+ *       types: ['geopoint']
+ *     }
+ *   ]
+ * })
+ *
+ * export default viewGeopointInMapApp
+ * ```
+ *
+ * If your intent is asynchronous, resolve the promise before defining / returning the intent
+ * ```typescript
+ * async function createAsyncIntent() {
+ *   const currentProject = await asyncProjectFunction()
+ *   const currentDataset = await asyncDatasetFunction()
+ *
+ *   return defineIntent({
+ *     id: 'dynamicIntent',
+ *     action: 'view',
+ *     title: 'Dynamic Intent',
+ *     description: 'Intent with dynamically resolved values',
+ *     filters: [
+ *       {
+ *         projectId: currentProject,  // Resolved value
+ *         dataset: currentDataset,    // Resolved value
+ *         types: ['document']
+ *       }
+ *     ]
+ *   })
+ * }
+ *
+ * const intent = await createAsyncIntent()
+ * export default intent
+ * ```
+ *
+ * @public
+ */
+export function defineIntent(intent: Intent): Intent {
+  // Validate required fields
+  if (!intent.id) {
+    throw new Error('Intent must have an id')
+  }
+  if (!intent.action) {
+    throw new Error('Intent must have an action')
+  }
+  if (!intent.title) {
+    throw new Error('Intent must have a title')
+  }
+  if (!Array.isArray(intent.filters)) {
+    throw new Error('Intent must have a filters array')
+  }
+  if (intent.filters.length === 0) {
+    throw new Error(
+      "Intent must have at least one filter. If you want to match everything, use {types: ['*']}",
+    )
+  }
+
+  // Validate each filter
+  intent.filters.forEach((filter, index) => {
+    validateFilter(filter, index)
+  })
+
+  // Return the intent as-is, providing type safety and runtime validation
+  return intent
+}
+
+/**
+ * Validates an individual filter object
+ * @param filter - The filter to validate
+ * @param index - The filter's index in the array (for error messages)
+ * @internal
+ */
+function validateFilter(filter: IntentFilter, index: number): void {
+  const filterContext = `Filter at index ${index}`
+
+  // Check that filter is an object
+  if (!filter || typeof filter !== 'object') {
+    throw new Error(`${filterContext} must be an object`)
+  }
+
+  // Check that types is required
+  if (filter.types === undefined) {
+    throw new Error(
+      `${filterContext} must have a types property. Use ['*'] to match all document types.`,
+    )
+  }
+
+  // Validate projectId
+  if (filter.projectId !== undefined) {
+    if (typeof filter.projectId !== 'string') {
+      throw new Error(`${filterContext}: projectId must be a string`)
+    }
+    if (filter.projectId.trim() === '') {
+      throw new Error(`${filterContext}: projectId cannot be empty`)
+    }
+  }
+
+  // Validate dataset
+  if (filter.dataset !== undefined) {
+    if (typeof filter.dataset !== 'string') {
+      throw new Error(`${filterContext}: dataset must be a string`)
+    }
+    if (filter.dataset.trim() === '') {
+      throw new Error(`${filterContext}: dataset cannot be empty`)
+    }
+    // Dataset requires projectId to be specified
+    if (filter.projectId === undefined) {
+      throw new Error(`${filterContext}: dataset cannot be specified without projectId`)
+    }
+  }
+
+  // Validate types (now required)
+  if (!Array.isArray(filter.types)) {
+    throw new Error(`${filterContext}: types must be an array`)
+  }
+  if (filter.types.length === 0) {
+    throw new Error(`${filterContext}: types array cannot be empty`)
+  }
+
+  // Validate each type
+  filter.types.forEach((type, typeIndex) => {
+    if (typeof type !== 'string') {
+      throw new Error(`${filterContext}: types[${typeIndex}] must be a string`)
+    }
+    if (type.trim() === '') {
+      throw new Error(`${filterContext}: types[${typeIndex}] cannot be empty`)
+    }
+  })
+
+  // Check for wildcard exclusivity
+  const hasWildcard = filter.types.includes('*')
+  if (hasWildcard && filter.types.length > 1) {
+    throw new Error(
+      `${filterContext}: when using wildcard '*', it must be the only type in the array`,
+    )
+  }
+}