@or-sdk/files 3.8.2 → 3.9.0

package/src/Files.ts

@@ -5,32 +5,38 @@ import { Memoize } from 'typescript-memoize';
 
 import { SERVICE_KEY } from './constants';
 import type {
+  ExtendedFileModel,
   FileItem,
   FileItemSelect,
+  FileModel,
   FilesConfig,
-  GetItemsQuery, GetUploadUrlDataPayload,
+  GetItemsQuery,
+  GetSystemFileUploadUrlParams,
+  GetUploadUrlDataPayload,
+  RequestOptions,
   SearchQuery,
+  Timestamp,
+  UploadFileOptions,
   UploadFileProps,
+  UploadFilePropsLegacy,
   UploadSystemFileParams,
-  UploadSystemUrlResponse,
+  UploadSystemFileParamsLegacy,
   UploadToSignedUrlParameters,
   UploadUrlProps,
+  UploadUrlPropsLegacy,
   UploadUrlResponse,
 } from './types';
 import { isNode } from './utils';
 
 export class Files extends Base {
-  /**
-   * @deprecated serviceUrl Use filesApiUrl instead
-   */
   constructor(params: FilesConfig) {
-    const { token, discoveryUrl, serviceUrl, filesApiUrl, accountId } = params;
+    const { token, accountId, discoveryUrl, filesApiUrl, serviceUrl } = params;
 
     super({
       token,
       accountId,
       discoveryUrl,
-      serviceUrl: filesApiUrl || serviceUrl,
+      serviceUrl: filesApiUrl ?? serviceUrl,
       serviceKey: SERVICE_KEY,
     });
   }
@@ -40,7 +46,7 @@ export class Files extends Base {
    * @param isPublic does this file public or private
    * @param prefix the file path, example: /data/images/second.png
    * @param attributes select specific props from FileItem. Example: 'key, isBoolean, size'
-   * @return object with: file, headData and url for downloading
+   * @returns object with: file, headData and url for downloading
    */
   async getFile(prefix: string, isPublic: boolean, attributes?: string): Promise<FileItem> {
     return await this.callApiV2({
@@ -57,7 +63,7 @@ export class Files extends Base {
   /**
    * Get one folder full data
    * @param key the file path, example: /data/images/second.png
-   * @return object with: file, headData and url for downloading
+   * @returns Folder record
    */
   async getFolder(key: string): Promise<FileItem> {
     return await this.callApiV2({
@@ -72,7 +78,7 @@ export class Files extends Base {
   /**
    * Get folder size
    * @param key the name of folder
-   * @return total folder size in bytes
+   * @returns total folder size in bytes
    */
   async getFolderSize(key: string): Promise<number> {
     const { size } = await this.callApiV2<{ size: number; }>({
@@ -88,7 +94,7 @@ export class Files extends Base {
    * Get list of public/private FileItems from api
    * @param treePrefix the folder path where GET FileItems, for Root use ''
    * @param isPublic does this file public or private, undefined for both types
-   * @return list of FileItems
+   * @returns list of FileItem records
    */
   async getItemsList(treePrefix: string, isPublic?: boolean): Promise<FileItem[]>;
   /**
@@ -96,7 +102,7 @@ export class Files extends Base {
    * @param treePrefix the folder path where GET FileItems, for Root use ''
    * @param isPublic does this file public or private, undefined for both types
    * @param attributes select specific props from FileItem. Example: 'key, isBoolean, size'
-   * @return list of FileItemSelect
+   * @returns list of FileItemSelect
    */
   async getItemsList(treePrefix: string, isPublic?: boolean, attributes?: string): Promise<FileItemSelect[]>;
 
@@ -135,7 +141,7 @@ export class Files extends Base {
    * Se list of public/private FileItems from api with specific prefix
    * @param term the folder/file path where search will be done
    * @param isPublic does this file public or private, undefined for both types
-   * @return list of FileItems
+   * @returns list of FileItems
    */
   async search(term: string, isPublic?: boolean): Promise<FileItem[]> {
     const queryParams: SearchQuery = {
@@ -293,7 +299,7 @@ export class Files extends Base {
    * @param isPublic does this file public or private
    * @param expireMs how long PRIVATE file link will be accessible in milliseconds
    * @param checkFileExist check that file exists in database
-   * @return file url
+   * @returns file url
    */
   async getDownloadUrl(key: string, isPublic: boolean, expireMs = 86400000, checkFileExist?: boolean): Promise<string> {
     return await this.callApiV2({
@@ -310,201 +316,202 @@ export class Files extends Base {
 
   /**
    * Get a link for uploading specific file, JUST FOR INNER USE
-   * @param data has UploadUrlProps values inside
-   * @param isPublic does this file public or private
-   * @param ttl timestamp of file expiration
-   * @return uploading Url with different header Fields
+   * @returns URL for uploading a file with additional header Fields
    */
-  getUploadUrl(
-    data: UploadUrlProps,
-    isPublic: boolean,
-    ttl?: number,
-    abortSignal?: AbortSignal,
+  public async getUploadUrlV2(
+    /** Details of the file to be uploaded */
+    { fileName, prefix, contentType, isPublic = false, expiresAt, ...data }: UploadUrlProps,
+
+    /** Additional request options */
+    options?: RequestOptions,
   ): Promise<UploadUrlResponse> {
-    const reqData: GetUploadUrlDataPayload = { ...data };
-    if (ttl) reqData.ttl = new Date(ttl).toISOString();
+    const fileKey = `${prefix ?? ''}${fileName}`;
+    const reqData: GetUploadUrlDataPayload = {
+      ...data,
+      key: fileKey,
+      contentType: contentType ?? this.defaultContentType,
+    };
+    const signal = options?.signal;
 
-    return this.callApiV2({
+    const expiresDate = this.normalizeDate(expiresAt);
+    if (expiresDate != undefined) {
+      reqData.ttl = expiresDate.toISOString();
+    }
+
+    return await this.callApiV2<UploadUrlResponse>({
       method: 'post',
       route: 'files/upload-params',
       params: {
         isPublic,
         setDefaultCache: true,
       },
-      signal: abortSignal,
+      signal,
       data: reqData,
     });
   }
 
   /**
-   * Upload file to S3 bucket
-   * @param type file mime type
-   * @param name file name
-   * @param fileModel file itself or Buffer
-   * @param prefix represent the file parent folder
-   * @param isPublic file privacy state
-   * @param progress callback with progress event
-   * @param rewriteMode if file already exist, should we rewrite it
-   * @param ttl timestamp when file should be deleted
-   * @param maxFileSize max file size
-   * @param abortSignal signal to cancel file upload
-   * @param waitTillFileAddedInDb true if you want to make sure file added to DB,
-   * for example for instant removing it. Please, use it carefully.
+   * Upload the file to File service
+   *
+   * @returns URL of the uploaded file into Files
    */
-  async uploadFile({
-    type,
-    name,
-    fileModel,
-    prefix,
-    isPublic,
-    progress,
-    rewriteMode,
-    ttl,
-    maxFileSize,
-    knownLength,
-    cacheControl = 'no-cache',
-    waitTillFileAddedInDb,
-  }: UploadFileProps, abortSignal?: AbortSignal): Promise<string> {
-    const contentType = type || 'binary/octet-stream';
-    const fileKey = prefix + name;
+  public async uploadFileV2(
+    {
+      fileName,
+      prefix,
+      fileContent,
+      contentType,
+      expiresAt,
+      isPublic = false,
+      rewriteMode,
+      maxFileSize,
+      knownLength,
+      cacheControl = 'no-cache',
+      waitTillFileAddedInDb,
+      onUploadProgress,
+    }: UploadFileProps,
+    {
+      signal,
+      waitForDatabaseUpdateTimeout = 60_000,
+      waitForDatabaseUpdatePollInterval = 2_000,
+    }: UploadFileOptions = {},
+  ): Promise<string> {
+    const fileKey = `${prefix ?? ''}${fileName}`;
 
-    const signedUrl = await this.getUploadUrl(
+    const signedUrl = await this.getUploadUrlV2(
       {
+        fileName,
+        prefix,
         contentType,
-        key: fileKey,
         cacheControl,
-        rewriteMode: rewriteMode,
-        maxFileSize: maxFileSize,
+        rewriteMode,
+        maxFileSize,
+        expiresAt,
+        isPublic,
       },
-      isPublic,
-      ttl,
-      abortSignal,
+      { signal },
     );
 
-    await this.uploadToSignedUrl({
-      signedUrl,
-      file: fileModel,
-      fileName: name,
-      cacheControl,
-      contentType,
-      knownLength,
-      signal: abortSignal,
-      onUploadProgress: progress,
-    });
+    await this.uploadToSignedUrl(
+      {
+        signedUrl,
+        fileContent: this.normalizeFileModel(fileContent),
+        fileName,
+        cacheControl,
+        contentType,
+        knownLength,
+        onUploadProgress,
+      },
+      { signal },
+    );
 
     if (waitTillFileAddedInDb) {
-      const TIMEOUT = 60000; // 1 minutes in ms
-      const STEP = 2000; // 2 second in ms
-      let passed = 0;
-
-      await new Promise((res, rej) => {
-        // it may take some time to copy file on S3, so we check it each "STEP" time
+      await new Promise<void>((res, rej) => {
+        // it may take some time for database to recognize new file upload, so we check it periodically
+        const start = Date.now();
         const interval = setInterval(() => {
           this.getFile(fileKey, isPublic)
+            .catch(() => { })
             .then(() => {
-              if (passed >= TIMEOUT) rej('Timeout reached');
+              if (start + waitForDatabaseUpdateTimeout >= Date.now()) rej('Timeout reached');
               clearInterval(interval);
-              res(null);
-            })
-            .catch(() => passed += STEP);
-        }, STEP);
+              res();
+            });
+        }, waitForDatabaseUpdatePollInterval);
       });
     }
 
     return signedUrl.downloadUrl;
   }
 
-  // ------------------------
-  // ---System files logic---
-  // ------------------------
+  // --------------------------
+  // --- System files logic ---
+  // --------------------------
 
   /**
    * Upload system file to S3 bucket, will not affect total size for user storage
-   * @param prefix prefix inside the system folder
-   * @param file file for uploading
-   * @param cacheControl cache settings
-   * @param abortSignal signal to cancel uploading
-   * @deprecated use `uploadSystemFileV2` instead
    */
-  async uploadSystemFile(
-    prefix: string,
-    file: File,
-    cacheControl = 'max-age=3600',
-    abortSignal?: AbortSignal,
+  public async uploadSystemFileV3(
+    {
+      fileName,
+      prefix,
+      fileContent,
+      contentType,
+      cacheControl = 'max-age=3600',
+      expiresAt,
+      knownLength,
+      onUploadProgress,
+    }: UploadSystemFileParams,
+    options?: RequestOptions,
   ): Promise<string> {
-    const signedUrl: UploadSystemUrlResponse = await this.callApiV2({
-      method: 'post',
-      route: 'system-file',
-      data: {
+    const signal = options?.signal;
+
+    const signedUrl = await this.getSystemFileUploadUrl(
+      {
+        fileName,
         prefix,
         cacheControl,
-        key: file.name,
+        expiresAt,
       },
-      signal: abortSignal,
-    });
+      { signal },
+    );
 
-    await this.uploadToSignedUrl({
-      signedUrl,
-      file,
-      fileName: file.name,
-      cacheControl,
-      contentType: file.type,
-      signal: abortSignal,
-    });
+    await this.uploadToSignedUrl(
+      {
+        signedUrl,
+        fileContent: this.normalizeFileModel(fileContent),
+        fileName,
+        cacheControl,
+        contentType,
+        knownLength,
+        onUploadProgress,
+      },
+      { signal },
+    );
 
     return signedUrl.downloadUrl;
   }
 
-  /**
-   * Upload system file to S3 bucket, will not affect total size for user storage
-   * @param prefix prefix inside the system folder
-   * @param file file for uploading
-   * @param cacheControl cache settings
-   * @param abortSignal signal to cancel uploading
-   * @param ttl timestamp when file should be deleted
-   * @param contentType content type of file
-   * @param fileName name of file
-   */
+  /** Get signed URL params for uploading of system file */
+  protected async getSystemFileUploadUrl(
+    params: GetSystemFileUploadUrlParams,
+    options?: RequestOptions,
+  ): Promise<UploadUrlResponse> {
+    const { fileName, prefix, cacheControl, expiresAt } = params;
 
-  async uploadSystemFileV2({
-    prefix,
-    file,
-    cacheControl = 'max-age=3600',
-    ttl,
-    fileName,
-    contentType,
-    knownLength,
-    abortSignal,
-  }: UploadSystemFileParams): Promise<string> {
-    const signedUrl: UploadSystemUrlResponse = await this.callApiV2({
+    return await this.callApiV2<UploadUrlResponse>({
       method: 'post',
       route: 'system-file',
       data: {
-        prefix,
-        cacheControl,
         key: fileName,
-        ttl,
+        prefix: prefix ?? '',
+        cacheControl,
+        ttl: this.normalizeDate(expiresAt)?.getTime(),
       },
-      signal: abortSignal,
+      signal: options?.signal,
     });
+  }
 
-    await this.uploadToSignedUrl({
-      signedUrl,
-      file,
-      fileName,
-      cacheControl,
-      contentType,
-      knownLength,
-      signal: abortSignal,
+  /**
+   * Delete system file
+   * @param path file path
+   */
+  public async deleteSystemFile(path: string): Promise<void> {
+    await this.callApiV2({
+      method: 'delete',
+      route: 'system-file',
+      params: { key: path },
     });
-
-    return signedUrl.downloadUrl;
   }
 
+  // -----------------------
+  // --- Files TTL logic ---
+  // -----------------------
+
   /**
    * Set ttl for a specific file or folder
    * @param key file or folder path
-   * @param isPublic false for folders, true or false for files
+   * @param isPublic `false` for folders, `true` or `false` for files
    * @param ttl number which represents milliseconds
    */
   async addTtl(key: string, isPublic: boolean, ttl: number): Promise<void> {
@@ -553,29 +560,17 @@ export class Files extends Base {
     });
   }
 
-  /**
-   * Delete system file
-   * @param path file path
-   */
-  async deleteSystemFile(path: string): Promise<void> {
-    await this.callApiV2({
-      method: 'delete',
-      route: 'system-file',
-      params: { key: path },
-    });
-  }
-
   private async uploadToSignedUrl({
     signedUrl,
-    file,
     fileName,
+    fileContent,
     cacheControl,
     contentType,
     knownLength,
-    signal,
     onUploadProgress,
-  }: UploadToSignedUrlParameters) {
+  }: UploadToSignedUrlParameters, options?: RequestOptions) {
     const { url, fields } = signedUrl;
+    const signal = options?.signal;
 
     const FormDataLib = await this.formDataFactory();
     const formData = new FormDataLib();
@@ -590,16 +585,16 @@ export class Files extends Base {
     if (contentType) formData.append('content-type', contentType);
 
     if (isNode) {
-      (formData as FormDataNode).append('File', file, {
+      (formData as FormDataNode).append('File', fileContent, {
         filename: fileName,
         contentType,
         knownLength,
       });
     } else {
-      if (!(file instanceof File || file instanceof Blob)) {
+      if (!(fileContent instanceof File || fileContent instanceof Blob)) {
         throw new Error('In browser file can only be an instance of File or Blob');
       }
-      (formData as FormData).append('File', file, fileName);
+      (formData as FormData).append('File', fileContent, fileName);
     }
 
     return await axios.post(url, formData, {
@@ -628,4 +623,160 @@ export class Files extends Base {
       ? formData.getHeaders()
       : {};
   }
+
+  private normalizeFileModel(fileContent: ExtendedFileModel): FileModel {
+    if (typeof fileContent === 'string') {
+      const bytes = new TextEncoder().encode(fileContent);
+      return isNode ? Buffer.from(bytes) : new Blob([bytes]);
+    }
+
+    return fileContent;
+  }
+
+  /**
+   * Get Date instance from input that represents date
+   *
+   * @param input input to normalize
+   * @param errorMessage error message to throw if input is invalid date
+   * @returns Date instance represented by input
+   * @throws If input is invalid date
+   */
+  private normalizeDate(input: Timestamp | undefined, errorMessage?: string): Date | undefined {
+    if (input == undefined) return undefined;
+
+    const date = input instanceof Date ? input : new Date(input);
+
+    if (isNaN(date.getTime())) throw new Error(errorMessage ?? 'Invalid date input');
+
+    return date;
+  }
+
+  private get defaultContentType() {
+    return 'binary/octet-stream';
+  }
+
+  // --------------------------
+  // --- Deprecated methods ---
+  // --------------------------
+
+  /**
+   * Upload the file to File service
+   *
+   * @returns URL of the uploaded file into Files
+   * @deprecated Use {@link uploadFileV2} instead
+   */
+  public async uploadFile(
+    {
+      name,
+      prefix,
+      fileModel,
+      type,
+      isPublic = false,
+      rewriteMode,
+      maxFileSize,
+      knownLength,
+      cacheControl = 'no-cache',
+      ttl,
+      waitTillFileAddedInDb,
+      abortSignal,
+      progress,
+    }: UploadFilePropsLegacy,
+    signal?: AbortSignal,
+  ): Promise<string> {
+    return await this.uploadFileV2(
+      {
+        fileName: name,
+        prefix,
+        fileContent: fileModel,
+        contentType: type,
+        isPublic,
+        cacheControl,
+        rewriteMode,
+        maxFileSize,
+        knownLength,
+        expiresAt: ttl,
+        waitTillFileAddedInDb,
+        onUploadProgress: progress,
+      },
+      { signal: signal ?? abortSignal },
+    );
+  }
+
+  /**
+   * Get a link for uploading specific file, JUST FOR INNER USE
+   * @returns uploading Url with different header Fields
+   * @deprecated Use {@link getUploadUrlV2} instead
+   */
+  public async getUploadUrl(
+    /** Details of the file to be uploaded */
+    params: UploadUrlPropsLegacy,
+    isPublic?: boolean,
+    ttl?: number,
+    abortSignal?: AbortSignal,
+  ): Promise<UploadUrlResponse> {
+    const { key, ...data } = params;
+    return await this.getUploadUrlV2(
+      {
+        ...data,
+        fileName: key,
+        isPublic,
+        expiresAt: ttl,
+      },
+      { signal: abortSignal },
+    );
+  }
+
+  /**
+   * Upload system file to S3 bucket, will not affect total size for user storage
+   * @param prefix prefix inside the system folder
+   * @param file file for uploading
+   * @param cacheControl cache settings
+   * @param abortSignal signal to cancel uploading
+   * @deprecated use {@link uploadSystemFileV3} instead
+   */
+  public async uploadSystemFile(
+    prefix: string,
+    file: File,
+    cacheControl = 'max-age=3600',
+    abortSignal?: AbortSignal,
+  ): Promise<string> {
+    return await this.uploadSystemFileV3(
+      {
+        fileName: file.name,
+        prefix,
+        fileContent: file,
+        contentType: file.type,
+        cacheControl,
+      },
+      { signal: abortSignal },
+    );
+  }
+
+  /**
+   * Upload system file to S3 bucket, will not affect total size for user storage
+   * @deprecated Use {@link uploadSystemFileV3} instead
+   */
+  public async uploadSystemFileV2({
+    fileName,
+    prefix,
+    file,
+    contentType,
+    cacheControl = 'max-age=3600',
+    ttl,
+    knownLength,
+    abortSignal,
+  }: UploadSystemFileParamsLegacy): Promise<string> {
+    return await this.uploadSystemFileV3(
+      {
+        fileName,
+        prefix,
+        fileContent: file,
+        contentType,
+        cacheControl,
+        expiresAt: ttl,
+        knownLength,
+      },
+      { signal: abortSignal },
+    );
+  }
 }

package/src/index.ts

@@ -1,3 +1,3 @@
 export { Files } from './Files';
-export * from './types';
 export * from './constants';
+export type * from './types';

package/src/types/system-files.ts

@@ -0,0 +1,29 @@
+import type { ExtendedFileModel, UploadFileProps } from '../types';
+
+export type UploadSystemFileParams = Pick<
+  UploadFileProps,
+  | 'fileName'
+  | 'prefix'
+  | 'contentType'
+  | 'cacheControl'
+  | 'expiresAt'
+  | 'fileContent'
+  | 'onUploadProgress'
+  | 'knownLength'
+>
+
+export type GetSystemFileUploadUrlParams = Pick<
+  UploadSystemFileParams,
+  'fileName' | 'prefix' | 'cacheControl' | 'expiresAt'
+>
+
+// ----- deprecated -----
+
+export type UploadSystemFileParamsLegacy = Pick<
+  UploadSystemFileParams,
+  'fileName' | 'prefix' | 'contentType' | 'cacheControl' | 'knownLength'
+> & {
+  file: ExtendedFileModel;
+  ttl?: number;
+  abortSignal?: AbortSignal;
+}

package/src/types/ttl.ts

@@ -0,0 +1,6 @@
+/**
+ * - `Date` valid date instance
+ * - `number` amount of milliseconds since midnight Jan 1 1970 UTC (aka UNIX timestamp in milliseconds)
+ * - `string` valid Date string that represents datetime
+ * */
+export type Timestamp = Date | number | string;