Neutron Polarization Manipulator

    TypeScript icon, indicating that this package has built-in type declarations

    0.0.6 • Public • Published

    Uploadcare Upload Client

    This is an Uploadcare Upload API wrapper to work with Node.js and browser.

    Build Status NPM version GitHub release  Uploadcare stack on StackShare


    npm install @uploadcare/upload-client --save


    High-Level API

    To access the High-Level API, you need to create an instance of UploadClient providing the necessary settings. Specifying YOUR_PUBLIC_KEY is mandatory: it points to the specific Uploadcare project:

    import UploadClient from '@uploadcare/upload-client'
    const client = new UploadClient({publicKey: 'YOUR_PUBLIC_KEY'})

    Once the UploadClient instance is created, you can start using the wrapper to upload files from binary data:

    const fileUpload = client.fileFrom(fileData)
      .then(file => console.log(file.uuid))

    Another option is uploading files from URL, via the fileFrom method:

    const fileURL = ''
    const fileUpload = client.fileFrom(fileURL)
      .then(file => console.log(file.uuid))

    You can also use the fileFrom method to get previously uploaded files via their UUIDs:

    const fileUUID = 'edfdf045-34c0-4087-bbdd-e3834921f890'
    const fileUpload = client.fileFrom(fileUUID)
      .then(file => console.log(file.uuid))

    You can track uploading progress:

    const fileUUID = 'edfdf045-34c0-4087-bbdd-e3834921f890'
    const onProgress = (progress) => {
      console.log(progress.uploaded.loaded /
    const fileUpload = client.fileFrom(fileUUID, {}, {onProgress})
      .then(file => console.log(file.uuid))

    Or set callback function that will be called when file was uploaded:

    const fileUUID = 'edfdf045-34c0-4087-bbdd-e3834921f890'
    const onUploaded = (uuid) => console.log(`File "${uuid}" was uploaded.`)
    const fileUpload = client.fileFrom(fileUUID, {}, {onUploaded})
      .then(file => console.log(file.uuid))

    Or when file is ready on CDN:

    const fileUUID = 'edfdf045-34c0-4087-bbdd-e3834921f890'
    const onReady = (file) => console.log(`File "${file.uuid}" is ready on CDN.`)
    const fileUpload = client.fileFrom(fileUUID, {}, {onReady})
      .then(file => console.log(file.uuid))

    You can cancel file uploading and track this event:

    const fileUUID = 'edfdf045-34c0-4087-bbdd-e3834921f890'
    const onCancel = () => console.log(`File uploading was canceled.`)
    const fileUpload = client.fileFrom(fileUUID, {}, {onCancel})
      .then(file => console.log(file.uuid))
    // Cancel uploading

    List of all available high level API methods:

    interface UploadClientInterface {
      updateSettings(newSettings: SettingsInterface): void;
      getSettings(): SettingsInterface;
        data: FileData | Url | Uuid,
        settings?: SettingsInterface,
        hooks?: LifecycleHooksInterface<UploadcareFileInterface>,
      ): UploadInterface<UploadcareFileInterface>;
        data: FileData[] | Url[] | Uuid[],
        settings?: SettingsInterface,
        hooks?: LifecycleHooksInterface<UploadcareGroupInterface>,
      ): UploadInterface<UploadcareGroupInterface>;

    Middle-Level API

    Also, you can use wrappers around low level to call the API endpoints:

    import UploadClient from '@uploadcare/upload-client'
    const client = new UploadClient({publicKey: 'YOUR_PUBLIC_KEY'})
    const onProgress = (progressEvent) => console.log(progressEvent.loaded /
    // and set callback to track cancel event:
    const onCancel = () => console.log('File upload was canceled.')
    const directUpload = client.api.base(fileData, {}, {onProgress, onCancel}) // fileData must be `Blob` or `File` or `Buffer`
      .then(data => console.log(data.file))
    // Also you can cancel upload:

    List of all available API methods:

    interface UploadAPIInterface {
      request(options: RequestOptionsInterface): Promise<RequestResponse>;
        data: FileData,
        settings?: SettingsInterface,
        hooks?: BaseHooksInterface,
      ): BaseThenableInterface<BaseResponse>;
        uuid: Uuid,
        settings?: SettingsInterface,
        hooks?: CancelHookInterface,
      ): CancelableThenableInterface<FileInfoInterface>;
        sourceUrl: Url,
        settings?: SettingsInterface,
        hooks?: CancelHookInterface,
      ): CancelableThenableInterface<FromUrlResponse>;
        token: Token,
        settings?: SettingsInterface,
        hooks?: CancelHookInterface,
      ): CancelableThenableInterface<FromUrlStatusResponse>;
        files: Uuid[],
        settings?: SettingsInterface,
        hooks?: CancelHookInterface,
      ): CancelableThenableInterface<GroupInfoInterface>;
        id: GroupId,
        settings?: SettingsInterface,
        hooks?: CancelHookInterface
      ): CancelableThenableInterface<GroupInfoInterface>;
        file: FileData,
        settings: SettingsInterface,
        hooks?: CancelHookInterface,
      ): CancelableThenableInterface<MultipartStartResponse>;
        file: FileData,
        parts: MultipartPart[],
        settings: SettingsInterface,
        hooks?: CancelHookInterface,
      ): BaseThenableInterface<any>;
        uuid: Uuid,
        settings: SettingsInterface,
        hooks?: CancelHookInterface,
      ): CancelableThenableInterface<FileInfoInterface>;

    Low-Level API

    The Low-Level API is accessible via api.request(), here's the basic example,

    import UploadClient from '@uploadcare/upload-client'
    const client = new UploadClient({publicKey: 'YOUR_PUBLIC_KEY'})
      path: 'info',
      query: {
        pub_key: `YOUR_PUBLIC_KEY`,
        file_id: `6db2621d-3ca4-4edc-9c67-832b641fae85`,
      .then(response => console.log(


    publicKey: string

    The main use of a publicKey is to identify a target project for your uploads. It is required when using Upload API.

    baseCDN: string

    Defines your schema and CDN domain. Can be changed to one of the predefined values ( or your custom CNAME.

    Defaults to

    baseURL: string

    API base URL.

    Defaults to

    fileName: string

    You can specify an original filename.

    Defaults to original.

    doNotStore: boolean

    Forces files uploaded with a UploadClient not to be stored. For instance, you might want to turn this on when automatic file storing is enabled in your project, but you do not want to store files uploaded with a particular instance.

    secureSignature: string

    In case you enable signed uploads for your project, you’d need to provide the client with secureSignature and secureExpire params.

    The secureSignature is an MD5 hex-encoded hash from a concatenation of API secret key and secureExpire.

    secureExpire: string

    Stands for the Unix time to which the signature is valid, e.g., 1454902434.

    integration: string

    X-UC-User-Agent header value.

    Defaults to UploadcareUploadClient/${version}${publicKey} (JavaScript${integration})

    checkForUrlDuplicates: boolean

    Runs the duplicate check and provides the immediate-download behavior.

    saveUrlForRecurrentUploads: boolean

    Provides the save/update URL behavior. The parameter can be used if you believe a sourceUrl will be used more than once. Using the parameter also updates an existing reference with a new sourceUrl content.

    source: string

    Defines the upload source to use, can be set to local, url, etc.

    jsonpCallback: string

    Sets the name of your JSONP callback function to create files group from a set of files by using their UUIDs.

    pollingTimeoutMilliseconds: number

    Internally, Upload Client implements polling to ensure that a file s available on CDN or has finished uploading from URL.

    Defaults to 10000 milliseconds (10 seconds).

    maxContentLength: number

    maxContentLength defines the maximum allowed size (in bytes) of the HTTP response content.

    Defaults to 52428800 bytes (50 MB).

    retryThrottledRequestMaxTimes: number

    Sets the maximum number of attempts to retry throttled requests.

    Defaults to 1.

    multipartChunkSize: number

    This option is only applicable when handling local files. Sets the multipart chunk size.

    Defaults to 5242880 bytes (5 MB).

    multipartMinFileSize: number

    This option is only applicable when handling local files. Sets the multipart uploading file size threshold: larger files will be uploaded in the Multipart mode rather than via Direct Upload. The value is limited to the range from 10485760 (10 MB) to 104857600 (100 MB).

    Defaults to 26214400 (25 MB).

    multipartMinLastPartSize: number

    This option is only applicable when handling local files. Set the minimum size of the last multipart part.

    Defaults to 1048576 bytes (1 MB).

    maxConcurrentRequests: number

    Allows specifying the number of concurrent requests.

    Defaults to 4.


    npm run test

    By default, the testing environment is production, but you can run test with local environment. It requires starting a mock server to run tests.

    To start a mock server you need to run next command:

    npm run mock:start

    and after that you can run:

    NODE_ENV=development npm run test

    Security issues

    If you think you ran into something in Uploadcare libraries which might have security implications, please hit us up at or Hackerone.

    We'll contact you personally in a short time to fix an issue through co-op and prior to any public disclosure.


    Issues and PRs are welcome. You can provide your feedback or drop us a support request at


    npm i @jeetiss/upload

    DownloadsWeekly Downloads






    Unpacked Size

    119 kB

    Total Files


    Last publish


    • jeetiss