refactor(schemas): migrate API schemas from Flow to TypeScript

src/api/schemas/AiAgentBasicTextTool.ts

@@ -0,0 +1,21 @@
+import type { AiLlmEndpointParamsGoogleOrAiLlmEndpointParamsOpenAi } from './AiLlmEndpointParamsGoogleOrAiLlmEndpointParamsOpenAi';
+
+export interface AiAgentBasicTextTool {
+    /** The model to be used for the AI Agent for basic text. */
+    readonly model?: string;
+
+    /** System messages that help the LLM understand its role and task. */
+    readonly system_message?: string;
+
+    /**
+     * Prompt template with contextual information and the user prompt; may use `{current_date}`, `{user_question}`,
+     * and `{content}`.
+     */
+    readonly prompt_template?: string;
+
+    /** The number of tokens for completion. */
+    readonly num_tokens_for_completion?: number;
+
+    /** The parameters for the selected LLM endpoint. */
+    readonly llm_endpoint_params?: AiLlmEndpointParamsGoogleOrAiLlmEndpointParamsOpenAi;
+}

src/api/schemas/AiAgentExtractStructured.ts

@@ -0,0 +1,15 @@
+import type { AiAgentBasicTextTool } from './AiAgentBasicTextTool';
+import type { AiAgentLongTextTool } from './AiAgentLongTextTool';
+
+export type AiAgentExtractStructuredTypeField = 'ai_agent_extract_structured';
+
+export interface AiAgentExtractStructured {
+    /** The type of AI agent to be used for extraction. */
+    readonly type: AiAgentExtractStructuredTypeField;
+
+    /** The long-text tool configuration. */
+    readonly long_text?: AiAgentLongTextTool;
+
+    /** The basic-text tool configuration. */
+    readonly basic_text?: AiAgentBasicTextTool;
+}

src/api/schemas/AiAgentLongTextTool.ts

@@ -0,0 +1,22 @@
+import type { AiAgentBasicTextTool } from './AiAgentBasicTextTool';
+
+export interface AiAgentLongTextToolEmbeddingsStrategyField {
+    /** The strategy to be used for calculating embeddings. */
+    readonly id?: string;
+
+    /** The number of tokens per chunk. */
+    readonly num_tokens_per_chunk?: number;
+}
+
+export interface AiAgentLongTextToolEmbeddingsField {
+    /** The model to be used for calculating embeddings. */
+    readonly model?: string;
+
+    /** The strategy configuration used to calculate embeddings. */
+    readonly strategy?: AiAgentLongTextToolEmbeddingsStrategyField;
+}
+
+export type AiAgentLongTextTool = AiAgentBasicTextTool & {
+    /** The embeddings configuration for long-text processing. */
+    readonly embeddings?: AiAgentLongTextToolEmbeddingsField;
+};

src/api/schemas/AiAgentReference.ts

@@ -0,0 +1,12 @@
+export type AiAgentTypeField = 'ai_agent_id';
+
+export interface AiAgentReference {
+    /**
+     * AI Agent Reference type for a custom AI Agent ID.
+     * @see https://developer.box.com/reference/resources/ai-agent-reference/
+     */
+    readonly type: AiAgentTypeField;
+
+    /** The ID of the custom AI Agent. */
+    readonly id: string;
+}

src/api/schemas/AiExtractResponse.ts

@@ -0,0 +1,59 @@
+export interface AiExtractConfidenceScore {
+    /** The qualitative confidence level. */
+    level: string;
+
+    /** The numeric confidence score. */
+    score: number;
+}
+
+export interface AiExtractReference {
+    /** The ID of the referenced item. */
+    itemId: string;
+
+    /** The page containing the referenced text. */
+    page: number;
+
+    /** The referenced text. */
+    text: string;
+
+    /** The position of the referenced text on the page. */
+    boundingBox?: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+}
+
+export interface AiAgentInfo {
+    /** The models used by the AI Agent. */
+    models?: Array<{
+        name?: string;
+        provider?: string;
+        supported_purpose?: string;
+    }>;
+
+    /** The processor used by the AI Agent. */
+    processor?: string;
+}
+
+export interface AiExtractResponse {
+    /** The fields extracted from the supplied items. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Preserve the Flow schema's arbitrary answer values
+    answer: { [key: string]: any };
+
+    /** The date and time when the response was created. */
+    created_at: string;
+
+    /** The reason the extraction was completed. */
+    completion_reason?: string;
+
+    /** Confidence scores keyed by extracted field. */
+    confidence_score?: { [key: string]: AiExtractConfidenceScore };
+
+    /** References keyed by extracted field. */
+    reference?: { [key: string]: Array<AiExtractReference> };
+
+    /** Information about the AI Agent used for extraction. */
+    ai_agent_info?: AiAgentInfo;
+}

src/api/schemas/AiExtractStructured.ts

@@ -0,0 +1,71 @@
+import type { AiAgentExtractStructured } from './AiAgentExtractStructured';
+import type { AiAgentReference } from './AiAgentReference';
+import type { AiItemBase } from './AiItemBase';
+
+export type AiExtractStructuredMetadataTemplateTypeField = 'metadata_template';
+
+export interface AiExtractStructuredMetadataTemplateField {
+    /** The name of the metadata template. */
+    readonly template_key?: string;
+
+    /** Value is always `metadata_template`. */
+    readonly type?: AiExtractStructuredMetadataTemplateTypeField;
+
+    /**
+     * The scope of the metadata template can either be global or enterprise_*. The global scope is used for
+     * templates that are available to any Box enterprise. The enterprise_* scope represents templates that have
+     * been created within a specific enterprise, where * is the ID of that enterprise.
+     */
+    readonly scope?: string;
+}
+
+export interface AiExtractStructuredFieldsOptionsField {
+    /** A unique identifier for the field. */
+    readonly key: string;
+}
+
+export interface AiExtractStructuredFieldsField {
+    /** A unique identifier for the field. */
+    readonly key: string;
+
+    /** A description of the field. */
+    readonly description?: string;
+
+    /** The display name of the field. */
+    readonly display_name?: string;
+
+    /** Context about the key (how to find and format it). */
+    readonly prompt?: string;
+
+    /** Field type (e.g. string, float, date, enum, multiSelect). */
+    readonly type?: string;
+
+    /** Options for enum and multiSelect field types. */
+    readonly options?: ReadonlyArray<AiExtractStructuredFieldsOptionsField>;
+}
+
+export interface AiExtractStructured {
+    /** The items to be processed by the LLM, often files. */
+    readonly items: ReadonlyArray<AiItemBase>;
+
+    /** Metadata template for fields to extract; cannot be used with `fields`. */
+    readonly metadata_template?: AiExtractStructuredMetadataTemplateField;
+
+    /** Fields to extract; cannot be used with `metadata_template`. */
+    readonly fields?: ReadonlyArray<AiExtractStructuredFieldsField>;
+
+    /** JSON blob containing overrides for the agent config. */
+    readonly agent_config?: string;
+
+    /**
+     * The AI Agent definition to use for extraction. Use `AiAgentExtractStructured` to customize basic-text or
+     * long-text agents, or `AiAgentReference` to reference a custom AI Agent by ID.
+     */
+    readonly ai_agent?: AiAgentExtractStructured | AiAgentReference;
+
+    /** When `true`, include confidence scores for each extracted field. */
+    readonly include_confidence_score?: boolean;
+
+    /** When `true`, include reference locations (bounding boxes) for each extracted field. */
+    readonly include_reference?: boolean;
+}

src/api/schemas/AiItemBase.ts

@@ -0,0 +1,12 @@
+export type AiItemBaseTypeField = 'file';
+
+export interface AiItemBase {
+    /** The ID of the item. */
+    readonly id: string;
+
+    /** The type of the item. */
+    readonly type: AiItemBaseTypeField;
+
+    /** The content of the item, often the text representation. */
+    readonly content?: string;
+}

src/api/schemas/AiLlmEndpointParamsGoogle.ts

@@ -0,0 +1,18 @@
+export type AiLlmEndpointParamsGoogleTypeField = 'google_params';
+
+export interface AiLlmEndpointParamsGoogle {
+    /** The type of the AI LLM endpoint params object for Google. */
+    readonly type: AiLlmEndpointParamsGoogleTypeField;
+
+    /**
+     * The sampling temperature used during response generation.
+     * Temperature controls the degree of randomness in token selection.
+     */
+    readonly temperature?: number;
+
+    /** The cumulative probability threshold used to select output tokens. */
+    readonly top_p?: number;
+
+    /** The number of most probable tokens considered when selecting the next token. */
+    readonly top_k?: number;
+}

src/api/schemas/AiLlmEndpointParamsGoogleOrAiLlmEndpointParamsOpenAi.ts

@@ -0,0 +1,6 @@
+import type { AiLlmEndpointParamsGoogle } from './AiLlmEndpointParamsGoogle';
+import type { AiLlmEndpointParamsOpenAi } from './AiLlmEndpointParamsOpenAi';
+
+export type AiLlmEndpointParamsGoogleOrAiLlmEndpointParamsOpenAi =
+    | AiLlmEndpointParamsGoogle
+    | AiLlmEndpointParamsOpenAi;

src/api/schemas/AiLlmEndpointParamsOpenAi.ts

@@ -0,0 +1,24 @@
+export type AiLlmEndpointParamsOpenAiTypeField = 'openai_params';
+
+export interface AiLlmEndpointParamsOpenAi {
+    /**
+     * The sampling temperature, between 0 and 2. Higher values make the output more random, while lower values make it
+     * more focused and deterministic. Alter this or `top_p`, but not both.
+     */
+    readonly type: AiLlmEndpointParamsOpenAiTypeField;
+
+    /** Sampling temperature (0–2). Alter this or `top_p`, but not both. */
+    readonly temperature?: number;
+
+    /** Nucleus sampling probability mass. Alter this or `temperature`, but not both. */
+    readonly top_p?: number;
+
+    /** Penalty (-2.0 to 2.0) for tokens based on existing frequency in the generated text. */
+    readonly frequency_penalty?: number;
+
+    /** Penalty (-2.0 to 2.0) for tokens based on whether they appear in the generated text. */
+    readonly presence_penalty?: number;
+
+    /** Up to four sequences where the API stops generating further tokens. */
+    readonly stop?: string;
+}

src/elements/content-sidebar/hooks/useSidebarMetadataFetcher.ts

@@ -29,6 +29,7 @@ import messages from '../../common/messages';
 import { type BoxItem } from '../../../common/types/core';
 import { type ErrorContextProps, type ExternalProps, type SuccessContextProps } from '../MetadataSidebarRedesign';
 import { type AiExtractStructured } from '../../../api/schemas/AiExtractStructured';
+import { type AiItemBaseTypeField } from '../../../api/schemas/AiItemBase';
 import { isSameMetadataTemplate } from '../utils/metadataTemplateIdentity';
 
 export enum STATUS {
@@ -250,13 +251,13 @@ function useSidebarMetadataFetcher(
             const aiAPI = api.getIntelligenceAPI();
             setExtractErrorCode(null);
             let response = null;
-            const customAiAgent = agentId ? { ai_agent: { type: 'ai_agent_id', id: agentId } } : {};
+            const customAiAgent = agentId ? { ai_agent: { type: 'ai_agent_id' as const, id: agentId } } : {};
 
             const confidenceScoreParams = isConfidenceScoreApiEnabled ? { include_confidence_score: true } : {};
             const boundingBoxParams = isBoundingBoxApiEnabled ? { include_reference: true } : {};
 
             const requestBody: AiExtractStructured = {
-                items: [{ id: file.id, type: file.type }],
+                items: [{ id: file.id, type: file.type as AiItemBaseTypeField }],
                 metadata_template: { template_key: templateKey, scope, type: 'metadata_template' },
                 ...customAiAgent,
                 ...confidenceScoreParams,