content-agent 1.1.0 → 1.2.1

package/dist/_chunks-dts/types.d.ts

@@ -0,0 +1,794 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+type paths = {
+  '/{organizationId}/threads/{threadId}': {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    get?: never;
+    put?: never;
+    /**
+     * Send a chat message
+     * @description Send a message to the agent and receive a streaming response.
+     *     This endpoint manages conversation threads and persists message history.
+     */
+    post: operations['chat'];
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
+  '/prompt': {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    get?: never;
+    put?: never;
+    /**
+     * Send a one-shot prompt
+     * @description Stateless one-shot prompt endpoint. No thread management or message persistence.
+     *     Ideal for simple, single-turn interactions.
+     */
+    post: operations['prompt'];
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
+};
+type components = {
+  schemas: {
+    ChatRequest: {
+      /** @description Array of message objects */messages: components['schemas']['Message'][];
+      application?: components['schemas']['Application'];
+      config?: components['schemas']['Config'];
+      /**
+       * @description Enable or disable streaming responses
+       * @default true
+       */
+      stream: boolean;
+      /**
+       * @description Controls how directives in the response are formatted.
+       *     - markdown (default): Directives are resolved server-side into standard markdown (e.g., links with titles).
+       *     - directives: Raw directive syntax is preserved (e.g., `::document{id="doc-id"}`), useful for clients that render custom UI components.
+       * @default markdown
+       * @enum {string}
+       */
+      format: 'markdown' | 'directives';
+    };
+    PromptRequest: {
+      /**
+       * @description Your Sanity organization ID
+       * @example abc123
+       */
+      organizationId: string;
+      /**
+       * @description The prompt message
+       * @example Summarize my latest blog posts
+       */
+      message: string;
+      config?: components['schemas']['Config'];
+      /**
+       * @description Custom instructions for the agent
+       * @example Be concise and use bullet points
+       */
+      instructions?: string;
+      /**
+       * @description Controls how directives in the response are formatted.
+       *     - markdown (default): Directives are resolved server-side into standard markdown.
+       *     - directives: Raw directive syntax is preserved for clients that render custom UI.
+       * @default markdown
+       * @enum {string}
+       */
+      format: 'markdown' | 'directives';
+    };
+    Message: {
+      /**
+       * @description The role of the message sender
+       * @enum {string}
+       */
+      role: 'user' | 'assistant' | 'system'; /** @description The message content */
+      content: string; /** @description Optional unique identifier for the message */
+      id?: string; /** @description Optional name for the message sender */
+      name?: string;
+    }; /** @description Target Sanity application configuration */
+    Application: {
+      /**
+       * @description Application key in format "projectId.datasetName"
+       * @example abc123.production
+       */
+      key?: string;
+      resource?: {
+        /**
+         * @description Resource ID in format "projectId.datasetName"
+         * @example abc123.production
+         */
+        id?: string;
+        /**
+         * @description Resource type
+         * @enum {string}
+         */
+        type?: 'dataset';
+      };
+      /**
+       * Format: uri
+       * @description Base URL for the Sanity Studio
+       * @example https://your-studio.sanity.studio
+       */
+      intentBaseUrl?: string; /** @description Bundle version */
+      bundleVersion?: string; /** @description Application name */
+      name?: string; /** @description Application title */
+      title?: string; /** @description Schema descriptor ID */
+      schemaDescriptorId?: string;
+    }; /** @description Agent configuration. Controls behavior, capabilities, and document access. */
+    Config: {
+      /**
+       * @description Custom instruction string to include in the system prompt
+       * @example You are a helpful content assistant.
+       */
+      instruction?: string;
+      /**
+       * @description Key-value pairs appended to each user message as XML tags.
+       *     Each key becomes an XML tag with the value as content.
+       *     Example: { "slack-channel": "#marketing" } renders as <slack-channel>#marketing</slack-channel>
+       * @example {
+       *       "slack-channel": "#marketing",
+       *       "user-role": "editor"
+       *     }
+       */
+      userMessageContext?: {
+        [key: string]: string;
+      };
+      capabilities?: components['schemas']['Capabilities'];
+      filter?: components['schemas']['Filter'];
+      perspectives?: components['schemas']['Perspectives'];
+    };
+    /**
+     * @description Agent capabilities that control what operations are allowed.
+     *     Each capability can be a boolean or an object with a preset.
+     * @example {
+     *       "read": true,
+     *       "write": false
+     *     }
+     */
+    Capabilities: {
+      read?: components['schemas']['Capability'];
+      write?: components['schemas']['Capability'];
+      features?: components['schemas']['FeatureOverrides'];
+    };
+    /**
+     * @description Explicit feature overrides applied on top of capability-derived defaults.
+     *     When not specified, features use values derived from read/write capability presets.
+     */
+    FeatureOverrides: {
+      /**
+       * @description Override web search availability.
+       *     By default, web search is enabled when read capability is 'standard'.
+       */
+      webSearch?: boolean;
+    };
+    /**
+     * @description A capability can be:
+     *     - true: Full access (standard preset)
+     *     - false: No access
+     *     - { preset: 'minimal' | 'standard' }: Explicit preset selection
+     */
+    Capability: boolean | components['schemas']['CapabilityPreset'];
+    CapabilityPreset: {
+      /**
+       * @description For read capability:
+       *     - minimal: Basic queries only (no bulk document analysis)
+       *     - standard: All read tools including bulk analysis
+       *
+       *     For write capability:
+       *     - minimal: Basic mutations only (no bulk mutations)
+       *     - standard: All write tools including bulk mutations
+       * @enum {string}
+       */
+      preset: 'minimal' | 'standard';
+    }; /** @description GROQ filter expressions for document access control */
+    Filter: {
+      /**
+       * @description GROQ boolean expression for document visibility.
+       *     Documents matching this filter are visible to the agent.
+       * @example _type in ['post', 'author']
+       */
+      read?: string;
+      /**
+       * @description GROQ boolean expression for mutation permissions.
+       *     Documents matching this filter can be mutated.
+       * @example _type == 'post'
+       */
+      write?: string;
+    };
+    /**
+     * @description Perspective locking configuration.
+     *     Controls which document perspectives the agent can read from and write to.
+     *     Values are Sanity perspective IDs: 'drafts', 'published', 'raw', or release/bundle IDs.
+     */
+    Perspectives: {
+      /**
+       * @description Allowed read perspectives. When set, query tools can only use these perspectives.
+       *     If the agent tries to use a disallowed perspective, the request is rejected with an error.
+       * @example [
+       *       "drafts",
+       *       "published"
+       *     ]
+       */
+      read?: string[];
+      /**
+       * @description The write perspective. When set, new documents are created in this perspective
+       *     and mutations are restricted to documents whose ID matches it.
+       * @example drafts
+       */
+      write?: string;
+    }; /** @description JSON response when streaming is disabled */
+    ChatResponse: {
+      /** @description The agent's response text */text?: string; /** @description The application key used for this conversation */
+      applicationKey?: string;
+    };
+    ErrorResponse: {
+      /**
+       * @description Error type
+       * @example Invalid request
+       */
+      error: string;
+      /**
+       * @description Human-readable error description
+       * @example Request body validation failed
+       */
+      details?: string; /** @description Validation issues (when applicable) */
+      issues?: components['schemas']['ValidationIssue'][];
+    };
+    ValidationIssue: {
+      /**
+       * @description Error code
+       * @example invalid_type
+       */
+      code?: string;
+      /**
+       * @description Path to the invalid field
+       * @example [
+       *       "messages"
+       *     ]
+       */
+      path?: string[];
+      /**
+       * @description Error message
+       * @example Required
+       */
+      message?: string;
+    };
+  };
+  responses: {
+    /** @description Bad Request - Request validation failed */BadRequest: {
+      headers: {
+        [name: string]: unknown;
+      };
+      content: {
+        /**
+         * @example {
+         *       "error": "Invalid request",
+         *       "details": "Request body validation failed",
+         *       "issues": [
+         *         {
+         *           "code": "invalid_type",
+         *           "path": [
+         *             "messages"
+         *           ],
+         *           "message": "Required"
+         *         }
+         *       ]
+         *     }
+         */
+        'application/json': components['schemas']['ErrorResponse'];
+      };
+    }; /** @description Unauthorized - Missing or invalid authentication token */
+    Unauthorized: {
+      headers: {
+        [name: string]: unknown;
+      };
+      content: {
+        /**
+         * @example {
+         *       "error": "Unauthorized",
+         *       "details": "Missing authorization token"
+         *     }
+         */
+        'application/json': components['schemas']['ErrorResponse'];
+      };
+    }; /** @description Internal Server Error */
+    InternalServerError: {
+      headers: {
+        [name: string]: unknown;
+      };
+      content: {
+        /**
+         * @example {
+         *       "error": "Internal Server Error",
+         *       "details": "An unexpected error occurred"
+         *     }
+         */
+        'application/json': components['schemas']['ErrorResponse'];
+      };
+    };
+  };
+  parameters: never;
+  requestBodies: never;
+  headers: never;
+  pathItems: never;
+};
+interface operations {
+  chat: {
+    parameters: {
+      query?: never;
+      header?: never;
+      path: {
+        /**
+         * @description Your Sanity organization ID
+         * @example abc123
+         */
+        organizationId: string;
+        /**
+         * @description Unique identifier for the conversation thread
+         * @example my-conversation-thread
+         */
+        threadId: string;
+      };
+      cookie?: never;
+    };
+    requestBody: {
+      content: {
+        'application/json': components['schemas']['ChatRequest'];
+      };
+    };
+    responses: {
+      /** @description Streaming response */200: {
+        headers: {
+          'Content-Type'?: string;
+          'X-Vercel-AI-Data-Stream'?: string;
+          [name: string]: unknown;
+        };
+        content: {
+          'text/event-stream': string; /** @description JSON response when stream is false */
+          'application/json': components['schemas']['ChatResponse'];
+        };
+      };
+      400: components['responses']['BadRequest'];
+      401: components['responses']['Unauthorized'];
+      500: components['responses']['InternalServerError'];
+    };
+  };
+  prompt: {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    requestBody: {
+      content: {
+        'application/json': components['schemas']['PromptRequest'];
+      };
+    };
+    responses: {
+      /** @description Streaming response */200: {
+        headers: {
+          'Content-Type'?: string;
+          'X-Vercel-AI-Data-Stream'?: string;
+          [name: string]: unknown;
+        };
+        content: {
+          'text/event-stream': string;
+        };
+      };
+      400: components['responses']['BadRequest'];
+      401: components['responses']['Unauthorized'];
+      500: components['responses']['InternalServerError'];
+    };
+  };
+}
+/**
+ * Request body for the conversation thread endpoint (`POST /{organizationId}/threads/{threadId}`).
+ * @category API Types
+ */
+type ChatRequest = components['schemas']['ChatRequest'];
+/**
+ * Request body for the one-shot prompt endpoint (`POST /prompt`).
+ * @category API Types
+ */
+type GenerateRequest = components['schemas']['PromptRequest'];
+/**
+ * Controls how directives in the response are formatted (`'markdown'` or `'directives'`).
+ * @category Configuration
+ */
+type OutputFormat = ChatRequest['format'];
+/**
+ * Response from the conversation thread endpoint when `stream: false`.
+ * @category API Types
+ */
+type ChatResponse = components['schemas']['ChatResponse'];
+/**
+ * Error response body returned by the API on failure.
+ * @category API Types
+ */
+type ErrorResponse = components['schemas']['ErrorResponse'];
+/**
+ * Individual validation issue within an {@link ErrorResponse}.
+ * @category API Types
+ */
+type ValidationIssue = components['schemas']['ValidationIssue'];
+/**
+ * A message in a conversation (user, assistant, or system).
+ * @category API Types
+ */
+type Message = components['schemas']['Message'];
+/**
+ * The role of a {@link Message}: `'user'`, `'assistant'`, or `'system'`.
+ * @category API Types
+ */
+type MessageRole = Message['role'];
+/**
+ * Specifies which Sanity project and dataset the agent should work with.
+ *
+ * @category Configuration
+ *
+ * @example
+ * ```ts
+ * const application = {
+ *   key: 'project-id.dataset-name',
+ * }
+ * ```
+ */
+type Application = components['schemas']['Application'];
+/**
+ * Resource within an {@link Application}.
+ * @category Configuration
+ */
+type ApplicationResource = NonNullable<Application['resource']>;
+/**
+ * Agent configuration for controlling behavior, capabilities, and document access.
+ *
+ * @category Configuration
+ *
+ * @example Read-only with custom instruction and user message context
+ * ```ts
+ * const config = {
+ *   instruction: 'You are a Slack bot helping users manage content.',
+ *   userMessageContext: {
+ *     'slack-channel': '#content-team',
+ *     'slack-user': '@john.doe',
+ *   },
+ *   capabilities: {
+ *     read: true,
+ *     write: false,
+ *   },
+ * }
+ * ```
+ *
+ * @example Read-only document explorer with type filtering
+ * ```ts
+ * const config = {
+ *   capabilities: {
+ *     read: { preset: 'standard' },
+ *     write: false,
+ *   },
+ *   filter: {
+ *     read: '_type in ["post", "author", "page"]',
+ *   },
+ * }
+ * ```
+ */
+type Config = components['schemas']['Config'];
+/**
+ * Controls what operations the agent can perform.
+ *
+ * Each capability (`read`, `write`) can be:
+ * - `true` — Full access (standard preset)
+ * - `false` — No access
+ * - `{ preset: 'minimal' }` — Basic tools only
+ * - `{ preset: 'standard' }` — All tools available
+ *
+ * Use `features` to override individual feature toggles independently of presets.
+ *
+ * @example Read-only access
+ * ```ts
+ * const capabilities = { read: true, write: false }
+ * ```
+ *
+ * @example Full read, minimal write
+ * ```ts
+ * const capabilities = {
+ *   read: true,
+ *   write: { preset: 'minimal' },
+ * }
+ * ```
+ *
+ * @example Standard read with web search disabled
+ * ```ts
+ * const capabilities = {
+ *   read: true,
+ *   write: false,
+ *   features: { webSearch: false },
+ * }
+ * ```
+ *
+ * @category Configuration
+ */
+type Capabilities = components['schemas']['Capabilities'];
+/**
+ * A single capability value: `true`, `false`, or a {@link CapabilityPreset}.
+ * @category Configuration
+ */
+type Capability = components['schemas']['Capability'];
+/**
+ * A capability preset object, e.g. `{ preset: 'minimal' }` or `{ preset: 'standard' }`.
+ * @category Configuration
+ */
+type CapabilityPreset = components['schemas']['CapabilityPreset'];
+/**
+ * The preset level string: `'minimal'` or `'standard'`.
+ * @category Configuration
+ */
+type CapabilityPresetValue = CapabilityPreset['preset'];
+/**
+ * GROQ boolean expressions to control document visibility and mutation permissions.
+ *
+ * @category Configuration
+ *
+ * @example
+ * ```ts
+ * const filter = {
+ *   read: '_type in ["post", "author", "category"]',
+ *   write: '_type == "post"',
+ * }
+ * ```
+ */
+type Filter = components['schemas']['Filter'];
+/**
+ * Key-value pairs appended to each user message as XML tags.
+ *
+ * @category Configuration
+ *
+ * @example
+ * ```ts
+ * const userMessageContext = {
+ *   'slack-channel': '#marketing',
+ *   'user-role': 'editor',
+ * }
+ * // Renders in the user message as:
+ * // <slack-channel>#marketing</slack-channel>
+ * // <user-role>editor</user-role>
+ * ```
+ */
+type UserMessageContext = NonNullable<Config['userMessageContext']>;
+/**
+ * Settings for creating a Content Agent provider instance via {@link createContentAgent}.
+ *
+ * @category Provider
+ *
+ * @example
+ * ```ts
+ * import { createContentAgent } from 'content-agent'
+ *
+ * const contentAgent = createContentAgent({
+ *   organizationId: 'your-org-id',
+ *   token: 'your-sanity-token',
+ *   // Optional overrides:
+ *   // baseURL: 'https://api.sanity.io',
+ *   // apiVersion: 'v2026-01-01',
+ * })
+ * ```
+ */
+interface ContentAgentProviderSettings {
+  /**
+   * Your Sanity organization ID.
+   *
+   * When using {@link createStudioAgent}, this is fetched automatically
+   * from the project metadata.
+   */
+  organizationId: string;
+  /**
+   * Default application for all agent and prompt calls.
+   *
+   * When set, this application is used unless overridden per-call via
+   * {@link AgentSettings.application} or {@link GenerateSettings.application}.
+   *
+   * Typically set automatically by {@link createStudioAgent}.
+   */
+  application?: Application;
+  /**
+   * Base URL for the Sanity API.
+   * @default 'https://api.sanity.io'
+   */
+  baseURL?: string;
+  /**
+   * API version to use for requests.
+   * Should be in format 'vYYYY-MM-DD' (e.g., 'v2026-01-01').
+   * @default 'v2026-01-01'
+   */
+  apiVersion?: string;
+  /**
+   * Authentication token for the Sanity API.
+   * If not provided, requests will be made without authentication
+   * (useful for browser contexts where auth may come from cookies).
+   */
+  token?: string;
+  /**
+   * Custom headers to include in requests.
+   */
+  headers?: Record<string, string>;
+  /**
+   * Custom fetch implementation.
+   * Useful for testing or adding middleware.
+   */
+  fetch?: typeof globalThis.fetch;
+}
+/**
+ * Base settings shared between agent and generate requests.
+ *
+ * @example Read-only agent with document type filtering
+ * ```ts
+ * const settings = {
+ *   application: { key: 'projectId.datasetName' },
+ *   config: {
+ *     instruction: 'You are a helpful content assistant for our blog.',
+ *     capabilities: {
+ *       read: true,
+ *       write: false,
+ *     },
+ *     filter: {
+ *       read: '_type in ["post", "author", "category"]',
+ *     },
+ *   },
+ * }
+ * ```
+ *
+ * @example Read/write agent with perspective locking
+ * ```ts
+ * const settings = {
+ *   application: { key: 'projectId.datasetName' },
+ *   config: {
+ *     capabilities: {
+ *       read: true,
+ *       write: { preset: 'minimal' },
+ *     },
+ *     filter: {
+ *       read: '_type in ["post", "author", "category"]',
+ *       write: '_type == "post"',
+ *     },
+ *     perspectives: {
+ *       read: ['drafts', 'published'],
+ *       write: 'drafts',
+ *     },
+ *   },
+ * }
+ * ```
+ */
+interface BaseAgentSettings {
+  /**
+   * Target Sanity application configuration.
+   */
+  application?: Application;
+  /**
+   * Agent configuration for controlling behavior, capabilities, and document access.
+   */
+  config?: Config;
+  /**
+   * Controls how directives in the response are formatted.
+   * - `markdown` (default): Directives are resolved server-side into standard markdown.
+   * - `directives`: Raw directive syntax is preserved for clients that render custom UI.
+   * @default 'markdown'
+   */
+  format?: OutputFormat;
+}
+/**
+ * Settings for creating an agent instance (per-thread).
+ *
+ * Passed as the second argument to {@link ContentAgentProvider.agent | contentAgent.agent(threadId, settings)}.
+ *
+ * @example
+ * ```ts
+ * const model = contentAgent.agent('my-thread-id', {
+ *   application: { key: 'projectId.datasetName' },
+ *   config: {
+ *     capabilities: { read: true, write: false },
+ *   },
+ * })
+ * ```
+ *
+ * @category Configuration
+ */
+interface AgentSettings extends BaseAgentSettings {
+  /**
+   * Identifies the client that created the thread (e.g. `'slack'`, `'linear'`, `'dashboard'`).
+   *
+   * Stored in thread metadata and used by the dashboard to filter its thread list.
+   * When omitted, the server assigns a default value.
+   */
+  clientId?: string;
+  /**
+   * Called when a custom `data-*` SSE part arrives during streaming.
+   *
+   * @param type - The data part type with the `data-` prefix stripped (e.g. `'agent-status'`).
+   * @param data - The parsed payload.
+   */
+  onStreamData?: (type: string, data: unknown) => void;
+}
+/**
+ * Settings for one-shot generation requests via {@link ContentAgentProvider.prompt | contentAgent.prompt()}.
+ *
+ * Extends {@link BaseAgentSettings} with an additional `instructions` field
+ * for providing custom system-level instructions.
+ *
+ * @example
+ * ```ts
+ * const { text } = await contentAgent.prompt(
+ *   {
+ *     application: { key: 'projectId.datasetName' },
+ *     config: { capabilities: { read: true, write: false } },
+ *     instructions: 'Be concise',
+ *   },
+ *   { message: 'List my 5 most recent posts' },
+ * )
+ * ```
+ *
+ * @category Configuration
+ */
+interface GenerateSettings extends BaseAgentSettings {
+  /**
+   * Custom instructions for the agent.
+   */
+  instructions?: string;
+}
+/**
+ * Options for a one-shot generation request via {@link ContentAgentProvider.prompt | contentAgent.prompt()}.
+ *
+ * @category Configuration
+ *
+ * @example
+ * ```ts
+ * const { text } = await contentAgent.prompt(
+ *   { instructions: 'Be concise' },
+ *   { message: 'List all authors in my dataset' },
+ * )
+ * ```
+ */
+interface GenerateOptions {
+  /**
+   * The prompt message to send.
+   */
+  message: string;
+  /**
+   * Enable streaming response.
+   * @default false
+   */
+  stream?: boolean;
+  /**
+   * Signal to abort the request.
+   */
+  abortSignal?: AbortSignal;
+}
+/**
+ * Result from a one-shot generation request via {@link ContentAgentProvider.prompt | contentAgent.prompt()}.
+ *
+ * @category Configuration
+ */
+interface GenerateResult {
+  /**
+   * The generated text response.
+   */
+  text: string;
+}
+export { components as C, ValidationIssue as S, paths as T, GenerateSettings as _, Capability as a, OutputFormat as b, ChatRequest as c, ContentAgentProviderSettings as d, ErrorResponse as f, GenerateResult as g, GenerateRequest as h, Capabilities as i, ChatResponse as l, GenerateOptions as m, Application as n, CapabilityPreset as o, Filter as p, ApplicationResource as r, CapabilityPresetValue as s, AgentSettings as t, Config as u, Message as v, operations as w, UserMessageContext as x, MessageRole as y };
+//# sourceMappingURL=types.d.ts.map