@or-sdk/files 3.8.2 → 3.9.0

package/src/types/upload-files.ts

@@ -0,0 +1,170 @@
+import type { AxiosProgressEvent } from 'axios';
+import type { ReadStream } from 'node:fs';
+
+import type { Timestamp } from './ttl';
+
+export type { AxiosProgressEvent };
+
+export type RequestOptions = {
+  /** Signal from AbortController to abort active request */
+  signal?: AbortSignal;
+}
+
+export type UploadBaseParams = {
+  /**
+   * Name of the file
+   * @example 'my_file.json'
+   */
+  fileName: string;
+
+  /**
+   * File path prefix
+   * @example If fine name is 'my_file.json' and prefix is 'path/to/file/' the result file path is:
+   * 'path/to/file/my_file.json'
+   *
+   * @example If fine name is 'my_file.json' and prefix is 'name_prefix_' the result file path is:
+   * 'name_prefix_my_file.json'
+   */
+  prefix?: string;
+
+  /**
+   * [MIME type](https://www.iana.org/assignments/media-types/media-types.xhtml)
+   * of the file.
+   * @default 'binary/octet-stream'
+   * @example 'application/json'
+   */
+  contentType?: string;
+
+  /** Max size of the file in bytes */
+  maxFileSize?: number;
+
+  /**
+   * Custom cache control setting for a file
+   *
+   * Examples:
+   * - `max-age=<seconds>`
+   * Specifies the maximum time (in seconds) a resource is considered fresh.
+   * For example, max-age=86400 means the resource is cached for 1 day.
+   * - `no-cache`
+   * Force to validate with the origin server before serving a cached copy.
+   * Useful for content that changes frequently.
+   */
+  cacheControl?: string;
+
+  /* If `rewrite` then existing file with same name could be overwritten */
+  rewriteMode?: 'rewrite' | 'prevent-rewrite';
+
+  /** Datetime when file should expire and be deleted */
+  expiresAt?: Timestamp;
+
+  /**
+   * If `true` after upload file would be publicly available by it's URL.
+   * If `false` access to file is possible only via temporary signed URL to a file.
+   * @default false
+   */
+  isPublic?: boolean;
+};
+
+export type UploadUrlProps = UploadBaseParams;
+
+export type UploadUrlPropsLegacy = Omit<UploadUrlProps, 'expiresAt' | 'fileName' | 'prefix' | 'isPublic'> & {
+  key: string;
+};
+
+export type GetUploadUrlDataPayload = Omit<UploadUrlProps, 'expiresAt' | 'fileName' | 'prefix' | 'isPublic'> & {
+  key: string;
+  contentType: string;
+  ttl?: string;
+};
+
+export type UploadUrlResponse = {
+  url: string;
+  downloadUrl: string;
+  fields: UploadFields;
+};
+
+export type UploadFields = {
+  key: string;
+  bucket: string;
+  Policy: string;
+  'X-Amz-Date': string;
+  'X-Amz-Signature': string;
+  'X-Amz-Algorithm': string;
+  'X-Amz-Credential': string;
+  'X-Amz-Security-Token': string;
+  'cache-control'?: string;
+};
+
+/** Buffer and ReadStream only supported in Node.js */
+export type FileModel = File | Blob | Buffer | ReadStream;
+/** Allows to use string as a file value */
+export type ExtendedFileModel = FileModel | string;
+
+export type UploadFileBaseParams = UploadBaseParams & {
+  /** File contents */
+  fileContent: ExtendedFileModel;
+
+  /** Callback function to be called with upload progress events */
+  onUploadProgress?: (event: ProgressEvent | AxiosProgressEvent) => void;
+
+  /** Size of the file in bytes. Helpful when file is an instance of ReadStream in Node.js */
+  knownLength?: number;
+
+  /** If `true` method will wait after file upload until file system will update to include file */
+  waitTillFileAddedInDb?: boolean;
+}
+
+export type UploadFileProps = UploadFileBaseParams;
+
+/** Optional config for uploading files */
+export type UploadFileOptions = RequestOptions & {
+  /**
+   * Maximum wait time for update of the data base in milliseconds.
+   * @default 60_000
+   */
+  waitForDatabaseUpdateTimeout?: number;
+
+  /**
+   * Interval between checking if database was updated in milliseconds.
+   * @default 2_000
+   */
+  waitForDatabaseUpdatePollInterval?: number;
+}
+
+export type UploadToSignedUrlParameters = Pick<
+  UploadFileProps,
+  'fileName' | 'fileContent' | 'contentType' | 'cacheControl' | 'knownLength' | 'onUploadProgress'
+> & {
+  signedUrl: UploadUrlResponse;
+}
+
+export type UploadToSignedUrlParameters2 = {
+  signedUrl: UploadUrlResponse;
+  file: FileModel;
+  fileName: string;
+  cacheControl?: string;
+  /** Size of the file in bytes. Helpful when file is an instance of ReadStream in Node.js */
+  knownLength?: number;
+  contentType?: string;
+  signal?: AbortSignal;
+  onUploadProgress?: (event: ProgressEvent | AxiosProgressEvent) => void;
+}
+
+// -------- deprecated ----------
+export type UploadFilePropsLegacy = Pick<
+  UploadFileProps,
+  | 'prefix'
+  | 'cacheControl'
+  | 'isPublic'
+  | 'rewriteMode'
+  | 'maxFileSize'
+  | 'knownLength'
+  | 'waitTillFileAddedInDb'
+> & {
+  name: string;
+  fileModel: ExtendedFileModel;
+  type?: string;
+  ttl?: number;
+  progress?: (event: ProgressEvent | AxiosProgressEvent) => void;
+  abortSignal?: AbortSignal;
+}

package/src/types.ts

@@ -1,30 +1,71 @@
 import type { Token } from '@or-sdk/base';
-import type { AxiosProgressEvent } from 'axios';
-import type { ReadStream } from 'node:fs';
 
-export type FilesConfig = {
+export type * from './types/system-files';
+export type * from './types/upload-files';
+export type * from './types/ttl';
+
+export type { Token };
+
+export type FilesConfigBase = {
   /**
    * token
    */
   token: Token;
-  /**
-   * Url of OneReach service discovery api
-   */
-  discoveryUrl?: string;
+
   /**
    * Account ID for cross-account requests (super admin only)
    */
   accountId?: string;
+}
+
+export type FilesConfigWithDiscovery = FilesConfigBase & {
+  /**
+   * URL of OneReach service discovery API.
+   *
+   * Allows to fetch URLs of needed API's instead of defining them in the constructor.
+   *
+   * @example 'https://discovery.<env>.api.onereach.ai'
+   */
+  discoveryUrl: string;
+
   /**
    * Direct service url, can be used to avoid discovery api call
+   *
+   * Not needed if {@link FilesConfig.discoveryUrl} is defined.
+   *
+   * @example 'https://files-api.svc.<env>.api.onereach.ai'
    */
-  filesApiUrl?: string;
+  filesApiUrl?: never;
+
+  /** @deprecated Use {@link FilesConfig.filesApiUrl} instead */
+  serviceUrl?: never;
+}
+
+export type FilesConfigWithExplicitUrls = FilesConfigBase & {
   /**
-   * @deprecated Use filesApiUrl instead
+   * Direct service url, can be used to avoid discovery api call
+   *
+   * Not needed if {@link FilesConfig.discoveryUrl} is defined.
+   *
+   * @example 'https://files-api.svc.<env>.api.onereach.ai'
    */
+  filesApiUrl: string;
+
+  /** @deprecated Use {@link FilesConfig.filesApiUrl} instead */
   serviceUrl?: string;
+
+  /**
+   * URL of OneReach service discovery API.
+   *
+   * Not needed if {@link FilesConfig.filesApiUrl} is defined.
+   *
+   * @example 'https://discovery.<env>.api.onereach.ai'
+   */
+  discoveryUrl?: never;
 };
 
+export type FilesConfig = FilesConfigWithDiscovery | FilesConfigWithExplicitUrls;
+
 export type GetItemsQuery = {
   prefix: string;
   isPublic?: boolean;
@@ -65,82 +106,3 @@ export type FileItemSelect = {
 export type GetItemsListResponse = {
   items: FileItem[];
 };
-
-export type UploadUrlProps = {
-  key: string;
-  contentType: string;
-  maxFileSize?: number;
-  cacheControl?: string;
-  rewriteMode?: 'rewrite' | 'prevent-rewrite';
-};
-
-export type UploadFields = {
-  key: string;
-  bucket: string;
-  Policy: string;
-  'X-Amz-Date': string;
-  'X-Amz-Signature': string;
-  'X-Amz-Algorithm': string;
-  'X-Amz-Credential': string;
-  'X-Amz-Security-Token': string;
-  'cache-control'?: string;
-};
-
-export type GetUploadUrlDataPayload = UploadUrlProps & {
-  ttl?: string;
-};
-
-export type UploadUrlResponse = {
-  url: string;
-  downloadUrl: string;
-  fields: UploadFields;
-};
-
-export type UploadSystemUrlResponse = {
-  url: string;
-  fields: UploadFields;
-  downloadUrl: string;
-};
-
-/** Buffer and ReadStream only supported in Node.js */
-export type FileModel = File | Blob | Buffer | ReadStream
-
-export type UploadFileProps = {
-  /** mime type of the file */
-  type: string;
-  name: string;
-  fileModel: FileModel;
-  prefix: string;
-  isPublic: boolean;
-  progress?: (event: ProgressEvent | AxiosProgressEvent) => void;
-  rewriteMode?: 'rewrite' | 'prevent-rewrite';
-  ttl?: number;
-  maxFileSize?: number;
-  knownLength?: number;
-  cacheControl?: string;
-  abortSignal?: AbortSignal;
-  waitTillFileAddedInDb?: boolean;
-};
-
-export type UploadSystemFileParams = {
-  prefix: string;
-  file: FileModel;
-  cacheControl?: string;
-  ttl: number;
-  fileName: string;
-  contentType?: string;
-  knownLength?: number;
-  abortSignal?: AbortSignal;
-};
-
-export type UploadToSignedUrlParameters = {
-  signedUrl: UploadUrlResponse;
-  file: FileModel;
-  fileName: string;
-  cacheControl?: string;
-  /** Size of the file in bytes. Helpful when file is an instance of ReadStream in Node.js */
-  knownLength?: number;
-  contentType?: string;
-  signal?: AbortSignal;
-  onUploadProgress?: (event: ProgressEvent | AxiosProgressEvent) => void;
-}

package/tsconfig.types.json

@@ -5,6 +5,7 @@
     "rootDir": "./src",
     "declaration": true,
     "declarationMap": true,
-    "emitDeclarationOnly": true
+    "emitDeclarationOnly": true,
+    "removeComments": false
   }
-}
+}