refactor(common): migrate common types from Flow to TypeScript

src/common/types/annotations.ts

@@ -0,0 +1,98 @@
+import type { BoxItemVersionMini, Reply, User } from './core';
+import type { ActionItemError, Comment, FeedItemStatus } from './feed';
+
+export type Frame = {
+    type: 'frame';
+    value: number;
+};
+
+export type Page = {
+    type: 'page';
+    value: number;
+};
+
+export type Rect = {
+    fill?: {
+        color: string;
+    };
+    height: number;
+    stroke?: {
+        color: string;
+        size: number;
+    };
+    type: 'rect';
+    width: number;
+    x: number;
+    y: number;
+};
+
+export type TargetDrawing = {
+    location: Frame | Page;
+    type: 'drawing';
+};
+
+export type TargetHighlight = {
+    location: Page;
+    text?: string;
+    type: 'highlight';
+};
+
+export type TargetRegion = {
+    location: Frame | Page;
+    shape?: Rect;
+    type: 'region';
+};
+
+export type TargetPoint = {
+    location: Page;
+    type: 'point';
+    x: number;
+    y: number;
+};
+
+export type Target = TargetDrawing | TargetHighlight | TargetPoint | TargetRegion;
+
+export type AnnotationPermission = {
+    can_delete?: boolean;
+    can_edit?: boolean;
+    can_reply?: boolean;
+    can_resolve?: boolean;
+};
+
+export type Resolution = {
+    resolved_at?: string | null;
+    resolved_by?: User | null;
+};
+
+export type Annotation = {
+    created_at: string;
+    created_by: User;
+    description?: Reply;
+    error?: ActionItemError; // Doesn't come from the API but used in the FeedItems,
+    file_version: BoxItemVersionMini | null;
+    id: string;
+    isPending?: boolean; // Doesn't come from the API but used in the FeedItems,
+    isRepliesLoading?: boolean;
+    modified_at: string;
+    modified_by: User;
+    permissions: AnnotationPermission;
+    replies?: Array<Comment>;
+    resolution?: Resolution | null;
+    status?: FeedItemStatus;
+    target: Target;
+    total_reply_count?: number;
+    type: 'annotation';
+};
+
+export type Annotations = {
+    entries: Array<Annotation>;
+    limit: number;
+    next_marker: string | null;
+};
+
+export type NewAnnotation = {
+    description?: {
+        message: string;
+    };
+    target: Target;
+};

src/common/types/api.js → src/common/types/api.js.flow

@@ -86,17 +86,19 @@ type APIOptions = {
     /**
      * Optional regional metadata API host (e.g. "https://api-jp.box.com").
      *
-     * Affects ONLY metadata *instance* endpoints (file/folder
-     * `/metadata/...`). Templates, taxonomies, suggestions, options, and
-     * metadata queries always use `apiHost` regardless of this value.
+     * Affects metadata *instance* endpoints (file/folder `/metadata/...`)
+     * and metadata *template* endpoints (`/metadata_templates/...`).
+     * Taxonomies, suggestions, options, and metadata queries always use
+     * `apiHost` regardless of this value.
      *
      * Forward-compatible by design: when undefined, empty, or equal to
      * `apiHost`, the resulting URLs are identical to those produced when
      * the option is not set. Dropping the option later is therefore a
      * no-op for any consumer.
      *
-     * Transitional: this option lets host applications pin metadata-
-     * instance traffic to a regional Box gateway while the global API host
+     * Transitional: this option lets host applications pin metadata
+     * instance and template traffic to a regional Box gateway while the
+     * global API host
      * is not yet regionalized end-to-end. It is expected to be retired in
      * a future major version.
      */

src/common/types/api.ts

@@ -0,0 +1,133 @@
+/* eslint-disable @typescript-eslint/no-explicit-any -- Preserve Flow any and Function contracts. */
+import type { AxiosError } from 'axios';
+import { HTTP_GET, HTTP_POST, HTTP_PUT, HTTP_DELETE, HTTP_OPTIONS, HTTP_HEAD } from '../../constants';
+import { JSON_PATCH_OP_ADD, JSON_PATCH_OP_REMOVE, JSON_PATCH_OP_REPLACE, JSON_PATCH_OP_TEST } from '../constants';
+import type { ElementOrigin } from '../../elements/common/flowTypes';
+import type { StringAnyMap, StringMap, Token } from './core';
+import type APICache from '../../utils/Cache';
+
+type Method =
+    | typeof HTTP_DELETE
+    | typeof HTTP_GET
+    | typeof HTTP_POST
+    | typeof HTTP_OPTIONS
+    | typeof HTTP_HEAD
+    | typeof HTTP_PUT;
+
+type JSONPatch = {
+    op:
+        | typeof JSON_PATCH_OP_ADD
+        | typeof JSON_PATCH_OP_REMOVE
+        | typeof JSON_PATCH_OP_REPLACE
+        | typeof JSON_PATCH_OP_TEST;
+    path: string;
+    value?: any;
+};
+
+type JSONPatchOperations = Array<JSONPatch>;
+
+type RequestOptions = {
+    fields?: Array<string>;
+    forceFetch?: boolean;
+    noPagination?: boolean;
+    refreshCache?: boolean;
+    // Extra X-Rep-Hints brackets appended to the default header (e.g. '[waveform]')
+    repHints?: string;
+};
+
+type PayloadType = StringAnyMap | Array<StringAnyMap>;
+
+type RequestData = {
+    data: PayloadType;
+    headers?: StringMap;
+    id?: string;
+    params?: StringAnyMap;
+    url: string;
+};
+
+type ErrorResponseData = {
+    code: string;
+    context_info: any;
+    help_url: string;
+    message: string;
+    request_id: string;
+    status: number;
+    type: 'error';
+};
+
+type ElementsXhrError = AxiosError<any> | ErrorResponseData;
+
+type ElementsError = {
+    code: string;
+    context_info: any;
+    message: string;
+    origin: ElementOrigin;
+    type: 'error';
+};
+
+type ErrorContextProps = {
+    onError: (error: ElementsXhrError | Error, code: string, contextInfo?: any, origin?: ElementOrigin) => void;
+};
+
+type ElementsErrorCallback = (e: ElementsXhrError, code: string, contextInfo?: any) => void;
+
+type ElementsSuccess = {
+    code: string;
+    showNotification: boolean;
+};
+
+type APIOptions = {
+    apiHost?: string;
+    cache?: APICache;
+    clientName?: string;
+    consoleError?: boolean;
+    consoleLog?: boolean;
+    id?: string;
+    language?: string;
+    /**
+     * Optional regional metadata API host (e.g. "https://api-jp.box.com").
+     *
+     * Affects metadata *instance* endpoints (file/folder `/metadata/...`)
+     * and metadata *template* endpoints (`/metadata_templates/...`).
+     * Taxonomies, suggestions, options, and metadata queries always use
+     * `apiHost` regardless of this value.
+     *
+     * Forward-compatible by design: when undefined, empty, or equal to
+     * `apiHost`, the resulting URLs are identical to those produced when
+     * the option is not set. Dropping the option later is therefore a
+     * no-op for any consumer.
+     *
+     * Transitional: this option lets host applications pin metadata
+     * instance and template traffic to a regional Box gateway while the
+     * global API host
+     * is not yet regionalized end-to-end. It is expected to be retired in
+     * a future major version.
+     */
+    metadataApiHost?: string;
+    metadataNamespaceMode?: string;
+    requestInterceptor?: any;
+    responseInterceptor?: any;
+    retryableStatusCodes?: Array<number>;
+    sharedLink?: string;
+    sharedLinkPassword?: string;
+    shouldRetry?: boolean;
+    token: Token;
+    uploadHost?: string;
+    version?: string;
+};
+
+export type {
+    APIOptions,
+    ElementOrigin,
+    ElementsError,
+    ElementsErrorCallback,
+    ElementsSuccess,
+    ElementsXhrError,
+    ErrorContextProps,
+    ErrorResponseData,
+    RequestData,
+    RequestOptions,
+    JSONPatchOperations,
+    Method,
+    PayloadType,
+};