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

src/api/schemas/AiAgentBasicTextTool.ts

@@ -0,0 +1,29 @@
+/**
+ * @author Box
+ */
+
+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 try to help the LLM "understand" its role and what it is supposed to do.
+     */
+    readonly system_message?: string;
+    /**
+     * Prompt template containing contextual information and the user prompt. May include inputs for
+     * `{current_date}`, `{user_question}`, and `{content}` depending on the use.
+     */
+    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,23 @@
+/**
+ * @author Box
+ */
+
+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,32 @@
+/**
+ * @author Box
+ */
+
+import type { AiAgentBasicTextTool } from './AiAgentBasicTextTool';
+
+export interface AiAgentLongTextToolEmbeddingsStrategyField {
+    /**
+     * The strategy to be used for the AI Agent 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 the AI Agent 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,17 @@
+/**
+ * @author Box
+ */
+
+export type AiAgentTypeField = 'ai_agent_id';
+
+export interface AiAgentReference {
+    /**
+     * AI Agent Reference type used to pass a custom AI Agent ID to requests.
+     * 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,53 @@
+/**
+ * @author Box
+ */
+
+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,93 @@
+/**
+ * @author Box
+ */
+
+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 that may include how to find and how to format it.
+     */
+    readonly prompt?: string;
+    /**
+     * The type of the field. Can include but is not limited to string, float, date, enum, and multiSelect.
+     */
+    readonly type?: string;
+    /**
+     * A list of options for this field. This is most often used in combination with the 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>;
+    /**
+     * The metadata template containing the fields to extract. Cannot be used in combination with `fields`.
+     */
+    readonly metadata_template?: AiExtractStructuredMetadataTemplateField;
+    /**
+     * The fields to be extracted from the items. Cannot be used in combination with `metadata_template`.
+     */
+    readonly fields?: ReadonlyArray<AiExtractStructuredFieldsField>;
+    /**
+     * The JSON blob that contains 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`, the response includes confidence scores for each extracted field.
+     */
+    readonly include_confidence_score?: boolean;
+    /**
+     * When `true`, the response includes reference locations (bounding boxes) for each extracted field.
+     */
+    readonly include_reference?: boolean;
+}

src/api/schemas/AiItemBase.ts

@@ -0,0 +1,20 @@
+/**
+ * @author Box
+ */
+
+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,25 @@
+/**
+ * @author Box
+ */
+
+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,10 @@
+/**
+ * @author Box
+ */
+
+import type { AiLlmEndpointParamsGoogle } from './AiLlmEndpointParamsGoogle';
+import type { AiLlmEndpointParamsOpenAi } from './AiLlmEndpointParamsOpenAi';
+
+export type AiLlmEndpointParamsGoogleOrAiLlmEndpointParamsOpenAi =
+    | AiLlmEndpointParamsGoogle
+    | AiLlmEndpointParamsOpenAi;

src/api/schemas/AiLlmEndpointParamsOpenAi.ts

@@ -0,0 +1,33 @@
+/**
+ * @author Box
+ */
+
+export type AiLlmEndpointParamsOpenAiTypeField = 'openai_params';
+
+export interface AiLlmEndpointParamsOpenAi {
+    /**
+     * The type of the AI LLM endpoint params object for OpenAI.
+     */
+    readonly type: AiLlmEndpointParamsOpenAiTypeField;
+    /**
+     * 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 temperature?: number;
+    /**
+     * The nucleus sampling probability mass. Alter this or `temperature`, but not both.
+     */
+    readonly top_p?: number;
+    /**
+     * A number between -2.0 and 2.0 that penalizes new tokens based on their existing frequency in the generated text.
+     */
+    readonly frequency_penalty?: number;
+    /**
+     * A number between -2.0 and 2.0 that penalizes new 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

@@ -227,7 +227,7 @@ 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 = isConfidenceScoreEnabled ? { include_confidence_score: true } : {};
             const boundingBoxParams = isBoundingBoxEnabled ? { include_reference: true } : {};