generaltranslation 7.9.1 → 8.0.0-alpha.1

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { DataFormat as DataFormat$1 } from 'src/types';
+
 type CustomMapping = Record<string, string | Partial<LocaleProperties>>;
 
 type LocaleProperties = {
@@ -121,42 +123,12 @@ type Entry = {
     metadata?: EntryMetadata;
 };
 
-type TranslationStatusResult = {
-    count: number;
-    availableLocales: string[];
-    locales: string[];
-    localesWaitingForApproval: any[];
-};
-type CheckTranslationStatusOptions = {
-    timeout?: number;
-};
-
-type FileFormat = 'GTJSON' | 'JSON' | 'YAML' | 'MDX' | 'MD' | 'TS' | 'JS' | 'HTML';
-type CompletedFileTranslationData = {
-    locale: string;
-    metadata: any;
-    fileId: string;
-    fileName: string;
-    versionId: string;
-    id: string;
-    isReady: boolean;
-    downloadUrl: string;
-};
-
-type FileTranslationQuery = {
-    versionId: string;
-    fileName?: string;
-    fileId?: string;
-    locale: string;
-};
 type CheckFileTranslationsOptions = {
     timeout?: number;
 };
-type CheckFileTranslationsResult = {
-    translations: CompletedFileTranslationData[];
-};
 type FileQuery = {
     fileId: string;
+    branchId?: string;
     versionId?: string;
 };
 type FileQueryResult = {
@@ -183,75 +155,65 @@ type FileQueryResult = {
     }[];
 };
 
+type FileFormat = 'GTJSON' | 'JSON' | 'YAML' | 'MDX' | 'MD' | 'TS' | 'JS' | 'HTML';
+/**
+ * File object structure for referencing files
+ * @param fileId - The ID of the file
+ * @param versionId - The ID of the version of the file
+ * @param branchId - The ID of the branch of the file
+ * @param locale - The locale of the file ()
+ */
+type FileReference = {
+    fileId: string;
+    versionId: string;
+    branchId: string;
+    fileName: string;
+    fileFormat: FileFormat;
+    dataFormat?: DataFormat$1;
+};
+
+type DownloadFileBatchRequest = {
+    fileId: string;
+    branchId?: string;
+    versionId?: string;
+    locale?: string;
+}[];
 type DownloadFileBatchOptions = {
     timeout?: number;
 };
-type File = {
+type DownloadedFile = {
     id: string;
-    fileName: string;
+    branchId: string;
+    fileId: string;
+    versionId: string;
+    locale?: string;
+    fileName?: string;
     data: string;
-    metadata: any;
+    metadata: Record<string, any>;
     fileFormat: FileFormat;
 };
 type DownloadFileBatchResult = {
-    files: File[];
+    files: DownloadedFile[];
     count: number;
 };
 
-type FetchTranslationsOptions = {
-    timeout?: number;
-};
-type RetrievedTranslation = {
-    locale: string;
-    translation: any;
-};
-type RetrievedTranslations = RetrievedTranslation[];
-type FetchTranslationsResult = {
-    translations: RetrievedTranslations;
-};
-
-type Updates = ({
-    metadata: Record<string, any>;
-} & ({
-    dataFormat: 'JSX';
-    source: JsxChildren;
-} | {
-    dataFormat: 'ICU';
-    source: string;
-} | {
-    dataFormat: 'I18NEXT';
-    source: string;
-}))[];
 type EnqueueFilesResult = {
-    translations: CompletedFileTranslationData[];
-    data: Record<string, {
-        fileName: string;
-        versionId: string;
-    }>;
+    jobData: {
+        [jobId: string]: {
+            sourceFileId: string;
+            fileId: string;
+            versionId: string;
+            branchId: string;
+            targetLocale: string;
+            projectId: string;
+            force: boolean;
+            modelProvider?: string;
+        };
+    };
     locales: string[];
     message: string;
 };
 
-type EnqueueEntriesOptions = {
-    timeout?: number;
-    sourceLocale?: string;
-    targetLocales?: string[];
-    dataFormat?: DataFormat;
-    version?: string;
-    description?: string;
-    requireApproval?: boolean;
-    modelProvider?: string;
-};
-type EnqueueEntriesResult = {
-    versionId: string;
-    locales: string[];
-    message: string;
-    projectSettings: {
-        cdnEnabled: boolean;
-        requireApproval: boolean;
-    };
-};
-
 type DownloadFileOptions = {
     timeout?: number;
 };
@@ -295,6 +257,86 @@ type TranslationResult = RequestSuccess | TranslationError;
  */
 type TranslateManyResult = Array<TranslationResult>;
 
+type BranchDataResult = {
+    branches: {
+        id: string;
+        name: string;
+    }[];
+    defaultBranch: {
+        id: string;
+        name: string;
+    } | null;
+};
+
+type BranchQuery = {
+    branchNames: string[];
+};
+
+type FileDataQuery = {
+    sourceFiles?: {
+        fileId: string;
+        versionId: string;
+        branchId: string;
+    }[];
+    translatedFiles?: {
+        fileId: string;
+        versionId: string;
+        branchId: string;
+        locale: string;
+    }[];
+};
+type FileDataResult = {
+    sourceFiles?: {
+        branchId: string;
+        fileId: string;
+        versionId: string;
+        fileName: string;
+        fileFormat: string;
+        dataFormat: string | null;
+        createdAt: string;
+        updatedAt: string;
+        approvalRequiredAt: string | null;
+        publishedAt: string | null;
+        locales: string[];
+        sourceLocale: string;
+    }[];
+    translatedFiles?: {
+        branchId: string;
+        fileId: string;
+        versionId: string;
+        fileFormat: string;
+        dataFormat: string | null;
+        createdAt: string;
+        updatedAt: string;
+        approvedAt: string | null;
+        publishedAt: string | null;
+        completedAt: string | null;
+        locale: string;
+    }[];
+};
+
+type JobStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'unknown';
+type CheckJobStatusResult = {
+    jobId: string;
+    status: JobStatus;
+    error?: {
+        message: string;
+    };
+}[];
+
+type SubmitUserEditDiff = {
+    fileName: string;
+    locale: string;
+    diff: string;
+    branchId: string;
+    versionId: string;
+    fileId: string;
+    localContent?: string;
+};
+type SubmitUserEditDiffsPayload = {
+    diffs: SubmitUserEditDiff[];
+};
+
 type FormatVariables = Record<string, string | number | boolean | null | undefined | Date>;
 
 type SetupProjectResult = {
@@ -308,19 +350,6 @@ type SetupProjectOptions = {
     timeoutMs?: number;
 };
 
-type SetupJobStatus = 'queued' | 'processing' | 'completed' | 'failed';
-type CheckSetupStatusResult = {
-    jobId: string;
-    status: SetupJobStatus;
-    error?: {
-        message: string;
-    };
-};
-
-type ShouldSetupProjectResult = {
-    shouldSetupProject: boolean;
-};
-
 type EnqueueOptions = {
     sourceLocale: string;
     targetLocales: string[];
@@ -331,19 +360,6 @@ type EnqueueOptions = {
     timeout?: number;
 };
 
-type SubmitUserEditDiff = {
-    fileName: string;
-    locale: string;
-    diff: string;
-    versionId?: string;
-    fileId?: string;
-    localContent?: string;
-};
-type SubmitUserEditDiffsPayload = {
-    projectId?: string;
-    diffs: SubmitUserEditDiff[];
-};
-
 type CustomRegionMapping = {
     [region: string]: {
         name?: string;
@@ -353,6 +369,9 @@ type CustomRegionMapping = {
 };
 
 type FileUpload = {
+    branchId?: string;
+    incomingBranchId?: string;
+    checkedOutBranchId?: string;
     content: string;
     fileName: string;
     fileFormat: FileFormat;
@@ -361,21 +380,13 @@ type FileUpload = {
     versionId?: string;
     fileId?: string;
 };
-type FileUploadRef = {
-    fileId: string;
-    versionId: string;
-    fileName: string;
-    fileFormat: FileFormat;
-    dataFormat?: DataFormat;
-    locale?: string;
-};
 type UploadFilesOptions = {
     sourceLocale: string;
     modelProvider?: string;
     timeout?: number;
 };
 type UploadFilesResponse = {
-    uploadedFiles: FileUploadRef[];
+    uploadedFiles: FileReference[];
     count: number;
     message: string;
 };
@@ -388,6 +399,17 @@ type ProjectData = {
     currentLocales: string[];
 };
 
+type CreateBranchQuery = {
+    branchName: string;
+    defaultBranch: boolean;
+};
+type CreateBranchResult = {
+    branch: {
+        id: string;
+        name: string;
+    };
+};
+
 /**
  * Type representing the constructor parameters for the GT class.
  * @typedef {Object} GTConstructorParams
@@ -467,36 +489,19 @@ declare class GT {
     private _getTranslationConfig;
     private _validateAuth;
     /**
-     * Enqueues translation entries for processing.
+     * Queries branch information from the API.
      *
-     * @param {Updates} updates - The translation entries to enqueue.
-     * @param {EnqueueEntriesOptions} options - Options for enqueueing entries.
-     * @param {string} library - The library being used (for context).
-     * @returns {Promise<EnqueueTranslationEntriesResult>} The result of the enqueue operation.
-     *
-     * @example
-     * @deprecated Use the {@link enqueueFiles} method instead. Will be removed in v8.0.0.
-     * const gt = new GT({
-     *   sourceLocale: 'en-US',
-     *   targetLocale: 'es-ES',
-     *   locales: ['en-US', 'es-ES', 'fr-FR']
-     * });
+     * @param {BranchQuery} query - Object mapping the current branch and incoming branches
+     * @returns {Promise<BranchDataResult>} The branch information
+     */
+    queryBranchData(query: BranchQuery): Promise<BranchDataResult>;
+    /**
+     * Creates a new branch in the API. If the branch already exists, it will be returned.
      *
-     * const result = await gt.enqueueEntries([
-     *   {
-     *     content: 'Hello, world!',
-     *     fileName: 'Button.tsx',
-     *     fileFormat: 'TS',
-     *     dataFormat: 'JSX',
-     *   },
-     * ], {
-     *   sourceLocale: 'en-US',
-     *   targetLocales: ['es-ES', 'fr-FR'],
-     *   publish: true,
-     *   description: 'Translations for the Button component',
-     * });
+     * @param {CreateBranchQuery} query - Object mapping the branch name and default branch flag
+     * @returns {Promise<CreateBranchResult>} The created branch information
      */
-    enqueueEntries(updates: Updates, options?: EnqueueEntriesOptions): Promise<EnqueueEntriesResult>;
+    createBranch(query: CreateBranchQuery): Promise<CreateBranchResult>;
     /**
      * Enqueues project setup job using the specified file references
      *
@@ -505,32 +510,30 @@ declare class GT {
      * files that have already been uploaded via uploadSourceFiles. The setup jobs are queued
      * for processing and will generate a project setup based on the source files.
      *
-     * @param {FileUploadRef[]} files - Array of file references containing IDs of previously uploaded source files
+     * @param {FileReference[]} files - Array of file references containing IDs of previously uploaded source files
      * @param {SetupProjectOptions} [options] - Optional settings for target locales and timeout
      * @returns {Promise<SetupProjectResult>} Object containing the jobId and status
      */
-    setupProject(files: FileUploadRef[], options?: SetupProjectOptions): Promise<SetupProjectResult>;
+    setupProject(files: FileReference[], options?: SetupProjectOptions): Promise<SetupProjectResult>;
     /**
-     * Checks the current status of a project setup job by its unique identifier.
+     * Checks the current status of one or more project jobs by their unique identifiers.
      *
-     * This method polls the API to determine whether a setup job is still running,
-     * has completed successfully, or has failed. Setup jobs are created when
-     * uploading source files to initialize project translation workflows.
+     * This method polls the API to determine whether one or more jobs are still running,
+     * have completed successfully, or have failed. Jobs are created after calling either enqueueFiles or setupProject.
      *
-     * @param {string} jobId - The unique identifier of the setup job to check
+     * @param {string[]} jobIds - The unique identifiers of the jobs to check
      * @param {number} [timeoutMs] - Optional timeout in milliseconds for the API request
-     * @returns {Promise<CheckSetupStatusResult>} Object containing the job status
-     */
-    checkSetupStatus(jobId: string, timeoutMs?: number): Promise<CheckSetupStatusResult>;
-    /**
-     * Checks if a prpject requires setup.
+     * @returns {Promise<CheckJobStatusResult>} Object containing the job status
      *
-     * This method queries API to check if a project has been set up and returns
-     * true if setup is missing
-     *
-     * @returns {Promise<ShouldSetupProjectResult>} Object containing shouldSetupProject
+     * @example
+     * const result = await gt.checkJobStatus([
+     *   'job-123',
+     *   'job-456',
+     * ], {
+     *   timeout: 10000,
+     * });
      */
-    shouldSetupProject(): Promise<ShouldSetupProjectResult>;
+    checkJobStatus(jobIds: string[], timeoutMs?: number): Promise<CheckJobStatusResult>;
     /**
      * Enqueues translation jobs for previously uploaded source files.
      *
@@ -540,11 +543,11 @@ declare class GT {
      * uploadSourceFiles. The translation jobs are queued for processing and will
      * generate translated content based on the source files and target locales provided.
      *
-     * @param {FileUploadRef[]} files - Array of file references containing IDs of previously uploaded source files
+     * @param {FileReference[]} files - Array of file references containing IDs of previously uploaded source files
      * @param {EnqueueOptions} options - Configuration options including source locale, target locales, and job settings
      * @returns {Promise<EnqueueFilesResult>} Result containing job IDs, queue status, and processing information
      */
-    enqueueFiles(files: FileUploadRef[], options: EnqueueOptions): Promise<EnqueueFilesResult>;
+    enqueueFiles(files: FileReference[], options: EnqueueOptions): Promise<EnqueueFilesResult>;
     /**
      * Submits user edit diffs for existing translations so future generations preserve user intent.
      *
@@ -553,28 +556,26 @@ declare class GT {
      */
     submitUserEditDiffs(payload: SubmitUserEditDiffsPayload): Promise<void>;
     /**
-     * Checks the translation status of files.
+     * Queries data about one or more source or translation files.
      *
-     * @param {Object} data - Object mapping source paths to file information.
-     * @param {CheckFileTranslationsOptions} options - Options for checking file translations.
-     * @returns {Promise<CheckFileTranslationsResult>} The file translation status information.
+     * @param {FileDataQuery} data - Object mapping source and translation file information.
+     * @param {CheckFileTranslationsOptions} options - Options for the API call.
+     * @returns {Promise<FileDataResult>} The source and translation file data information.
      *
      * @example
-     * const gt = new GT({
-     *   sourceLocale: 'en-US',
-     *   targetLocale: 'es-ES',
-     *   locales: ['en-US', 'es-ES', 'fr-FR']
-     * });
-     *
-     * const result = await gt.checkFileTranslations([
-     *   { sourcePath: 'src/components/Button.tsx', locale: 'es-ES' },
-     *   { sourcePath: 'src/components/Input.tsx', locale: 'fr-FR' },
-     * ], {
+     * const result = await gt.queryFileData({
+     *   sourceFiles: [
+     *     { fileId: '1234567890', versionId: '1234567890', branchId: '1234567890' },
+     *   ],
+     *   translatedFiles: [
+     *     { fileId: '1234567890', versionId: '1234567890', branchId: '1234567890', locale: 'es-ES' },
+     *   ],
+     * }, {
      *   timeout: 10000,
      * });
      *
      */
-    checkFileTranslations(data: FileTranslationQuery[], options?: CheckFileTranslationsOptions): Promise<CheckFileTranslationsResult>;
+    queryFileData(data: FileDataQuery, options?: CheckFileTranslationsOptions): Promise<FileDataResult>;
     /**
      * Gets source and translation information for a given file ID and version ID.
      *
@@ -583,12 +584,6 @@ declare class GT {
      * @returns {Promise<FileQueryResult>} The source file and translation information.
      *
      * @example
-     * const gt = new GT({
-     *   sourceLocale: 'en-US',
-     *   targetLocale: 'es-ES',
-     *   locales: ['en-US', 'es-ES', 'fr-FR']
-     * });
-     *
      * const result = await gt.querySourceFile(
      *   { fileId: '1234567890', versionId: '1234567890' },
      *   { timeout: 10000 }
@@ -603,12 +598,6 @@ declare class GT {
      * @returns {Promise<ProjectData>} The project data.
      *
      * @example
-     * const gt = new GT({
-     *   sourceLocale: 'en-US',
-     *   targetLocale: 'es-ES',
-     *   locales: ['en-US', 'es-ES', 'fr-FR']
-     * });
-     *
      * const result = await gt.getProjectData(
      *   '1234567890'
      * );
@@ -618,107 +607,49 @@ declare class GT {
         timeout?: number;
     }): Promise<ProjectData>;
     /**
-     * Checks the translation status of a version.
-     *
-     * @param {string} versionId - The ID of the version to check.
-     * @param {CheckTranslationStatusOptions} options - Options for checking the translation status.
-     * @returns {Promise<TranslationStatusResult>} The translation status of the version.
-     *
-     * @example
-     * @deprecated Use the {@link checkFileTranslations} method instead. Will be removed in v7.0.0.
-     * const gt = new GT({
-     *   sourceLocale: 'en-US',
-     *   targetLocale: 'es-ES',
-     *   locales: ['en-US', 'es-ES', 'fr-FR']
-     * });
-     *
-     * const result = await gt.checkTranslationStatus('1234567890', {
-     *   timeout: 10000,
-     * });
-     */
-    checkTranslationStatus(versionId: string, options?: CheckTranslationStatusOptions): Promise<TranslationStatusResult>;
-    /**
-     * Downloads a single translation file.
-     *
-     * @param {string} translationId - The ID of the translation to download.
-     * @param {DownloadFileOptions} options - Options for downloading the file.
-     * @returns {Promise<DownloadFileResult>} The downloaded file content and metadata.
-     * @deprecated Use the {@link downloadTranslatedFile} method instead. Will be removed in v7.0.0.
-     * @example
-     * const gt = new GT({
-     *   sourceLocale: 'en-US',
-     *   targetLocale: 'es-ES',
-     *   locales: ['en-US', 'es-ES', 'fr-FR']
-     * });
-     *
-     * const result = await gt.downloadFile('1234567890', {
-     *   timeout: 10000,
-     * });
-     */
-    downloadFile(translationId: string, options?: DownloadFileOptions): Promise<ArrayBuffer>;
-    /**
-     * Downloads a single translated file.
+     * Downloads a single file.
      *
-     * @param {string} file - The file to download.
+     * @param file - The file query object.
+     * @param {string} file.fileId - The ID of the file to download.
+     * @param {string} [file.branchId] - The ID of the branch to download the file from. If not provided, the default branch will be used.
+     * @param {string} [file.locale] - The locale to download the file for. If not provided, the source file will be downloaded.
+     * @param {string} [file.versionId] - The version ID to download the file from. If not provided, the latest version will be used.
      * @param {DownloadFileOptions} options - Options for downloading the file.
      * @returns {Promise<string>} The downloaded file content.
      *
      * @example
-     * const gt = new GT({
-     *   sourceLocale: 'en-US',
-     *   targetLocale: 'es-ES',
-     *   locales: ['en-US', 'es-ES', 'fr-FR']
-     * });
-     *
-     * const result = await gt.downloadTranslatedFile({
+     * const result = await gt.downloadFile({
      *   fileId: '1234567890',
+     *   branchId: '1234567890',
      *   locale: 'es-ES',
      *   versionId: '1234567890',
      * }, {
      *   timeout: 10000,
      * });
      */
-    downloadTranslatedFile(file: {
+    downloadFile(file: {
         fileId: string;
-        locale: string;
+        branchId?: string;
+        locale?: string;
         versionId?: string;
     }, options?: DownloadFileOptions): Promise<string>;
     /**
-     * Downloads multiple translation files in a batch.
+     * Downloads multiple files in a batch.
      *
-     * @param {string[]} fileIds - Array of file IDs to download.
+     * @param {DownloadFileBatchRequest} requests - Array of file query objects to download.
      * @param {DownloadFileBatchOptions} options - Options for the batch download.
      * @returns {Promise<DownloadFileBatchResult>} The batch download results.
      *
      * @example
-     * const gt = new GT({
-     *   sourceLocale: 'en-US',
-     *   targetLocale: 'es-ES',
-     *   locales: ['en-US', 'es-ES', 'fr-FR']
-     * });
-     *
-     * const result = await gt.downloadFileBatch(['1234567890', '1234567891'], {
+     * const result = await gt.downloadFileBatch([{
+     *   fileId: '1234567890',
+     *   locale: 'es-ES',
+     *   versionId: '1234567890',
+     * }], {
      *   timeout: 10000,
      * });
      */
-    downloadFileBatch(fileIds: string[], options?: DownloadFileBatchOptions): Promise<DownloadFileBatchResult>;
-    /**
-     * Fetches translation metadata and information.
-     *
-     * @param {string} versionId - The version ID to fetch translations for.
-     * @param {FetchTranslationsOptions} options - Options for fetching translations.
-     * @returns {Promise<FetchTranslationsResult>} The translation metadata and information.
-     *
-     * @example
-     * const gt = new GT({
-     *   sourceLocale: 'en-US',
-     *   targetLocale: 'es-ES',
-     *   locales: ['en-US', 'es-ES', 'fr-FR']
-     * });
-     *
-     * const result = await gt.fetchTranslations('1234567890');
-     */
-    fetchTranslations(versionId: string, options?: FetchTranslationsOptions): Promise<FetchTranslationsResult>;
+    downloadFileBatch(requests: DownloadFileBatchRequest, options?: DownloadFileBatchOptions): Promise<DownloadFileBatchResult>;
     /**
      * Translates the source content to the target locale.
      * @deprecated Use the {@link translate} method instead.