Node Popular Man

    @uploadcare/upload-client
    TypeScript icon, indicating that this package has built-in type declarations

    6.2.1 • Public • Published

    Uploadcare Upload Client

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

    API Reference

    Build Status NPM version GitHub release  Uploadcare stack on StackShare

    Install

    npm install @uploadcare/upload-client

    Usage

    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:

    client
      .uploadFile(fileData)
      .then(file => console.log(file.uuid))

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

    const fileURL = 'https://example.com/file.jpg'
    
    client
      .uploadFile(fileURL)
      .then(file => console.log(file.uuid))

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

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

    You can track uploading progress:

    const fileUUID = 'edfdf045-34c0-4087-bbdd-e3834921f890'
    const onProgress = ({ isComputable, value }) => {
      console.log(isComputable, value)
    }
    
    client
      .uploadFile(fileUUID, { onProgress })
      .then(file => console.log(file.uuid))

    Note that isComputable flag can be false is some cases of uploading from the URL. If we can't calculate the file size, progress info will look like { isComputable: false } without a value. Successful uploading progress will be always { isComputable: true, value: 1 }.

    You can cancel file uploading and track this event:

    const fileUUID = 'edfdf045-34c0-4087-bbdd-e3834921f890'
    const abortController = new AbortController()
    
    client
      .uploadFile(fileUUID, { signal: abortController.signal })
      .then(file => console.log(file.uuid))
      .catch(error => {
        if (error.isCancel) {
          console.log(`File uploading was canceled.`)
        }
      })
    
    // Cancel uploading
    abortController.abort()

    List of all available UploadClient API methods:

    interface UploadClient {
      updateSettings(newSettings: Settings = {}): void
    
      getSettings(): Settings
    
      base(
        file: Blob | File | Buffer | ReactNativeAsset,
        options: BaseOptions
      ): Promise<BaseResponse>
    
      info(uuid: Uuid, options: InfoOptions): Promise<FileInfo>
    
      fromUrl(sourceUrl: Url, options: FromUrlOptions): Promise<FromUrlResponse>
    
      fromUrlStatus(
        token: Token,
        options: FromUrlStatusOptions
      ): Promise<FromUrlStatusResponse>
    
      group(uuids: Uuid[], options: GroupOptions): Promise<GroupInfo>
    
      groupInfo(id: GroupId, options: GroupInfoOptions): Promise<GroupInfo>
    
      multipartStart(
        size: number,
        options: MultipartStartOptions
      ): Promise<MultipartStartResponse>
    
      multipartUpload(
        part: Buffer | Blob,
        url: MultipartPart,
        options: MultipartUploadOptions
      ): Promise<MultipartUploadResponse>
    
      multipartComplete(
        uuid: Uuid,
        options: MultipartCompleteOptions
      ): Promise<FileInfo>
    
      uploadFile(
        data: Blob | File | Buffer | ReactNativeAsset | Url | Uuid,
        options: FileFromOptions
      ): Promise<UploadcareFile>
    
      uploadFileGroup(
        data: (Blob | File | Buffer | ReactNativeAsset)[] | Url[] | Uuid[],
        options: FileFromOptions & GroupFromOptions
      ): Promise<UploadcareGroup>
    }

    You can import only needed methods directly, without UploadClient wrapper:

    import {
      uploadFile,
      uploadFromUrl,
      uploadDirect,
      uploadFromUploaded,
      uploadMultipart,
      uploadFileGroup
    } from '@uploadcare/upload-client'

    Low-Level API

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

    import { base } from '@uploadcare/upload-client'
    
    const onProgress = ({ isComputable, value }) => console.log(isComputable, value)
    const abortController = new AbortController()
    
    base(fileData, { onProgress, signal: abortController.signal }) // fileData must be `Blob` or `File` or `Buffer`
      .then(data => console.log(data.file))
      .catch(error => {
        if (error.isCancel) {
          console.log(`File uploading was canceled.`)
        }
      })
    
    // Also you can cancel upload:
    abortController.abort()

    List of all available API methods:

    base(
      file: Blob | File | Buffer | ReactNativeAsset,
      options: BaseOptions
    ): Promise<BaseResponse>
    info(uuid: Uuid, options: InfoOptions): Promise<FileInfo>
    fromUrl(sourceUrl: Url, options: FromUrlOptions): Promise<FromUrlResponse>
    fromUrlStatus(
      token: Token,
      options: FromUrlStatusOptions
    ): Promise<FromUrlStatusResponse>
    group(uuids: Uuid[], options: GroupOptions): Promise<GroupInfo>
    groupInfo(id: GroupId, options: GroupInfoOptions): Promise<GroupInfo>
    multipartStart(
      size: number,
      options: MultipartStartOptions
    ): Promise<MultipartStartResponse>
    multipartUpload(
      part: Buffer | Blob | File,
      url: MultipartPart,
      options: MultipartUploadOptions
    ): Promise<MultipartUploadResponse>
    multipartComplete(
      uuid: Uuid,
      options: MultipartCompleteOptions
    ): Promise<FileInfo>

    Settings

    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 (https://ucarecdn.com/) or your custom CNAME.

    Defaults to https://ucarecdn.com/.

    baseURL: string

    API base URL.

    Defaults to https://upload.uploadcare.com

    fileName: string

    You can specify an original filename. It could useful when file input does not contain filename.

    Defaults to original.

    store: boolean

    Forces files uploaded with UploadClient to be stored or not. For instance, you might want to turn this off 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.

    userAgent: string | CustomUserAgentFn

    type CustomUserAgentOptions = {
      publicKey: string
      libraryName: string
      libraryVersion: string
      languageName: string
      integration?: string
    }
    
    type CustomUserAgentFn = (options: CustomUserAgentOptions) => string

    X-UC-User-Agent header value.

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

    integration: string

    Integration value passed to the X-UC-User-Agent header. May be overrided with the custom user agent string or function.

    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 that the 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.

    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.

    retryNetworkErrorMaxTimes: number

    Sets the maximum number of attempts to retry requests that failed with a network error.

    Defaults to 3.

    The delay between attempts equals attempt number, i.e.

    • first attempt - 1 second delay
    • second attempt - 2 seconds delay
    • third attempt - 3 seconds delay
    • ...

    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.

    contentType: string

    This option is useful when file input does not contain content type.

    Defaults to application/octet-stream.

    metadata: Metadata

    type Metadata = {
      [key: string]: string
    }

    Metadata is additional, arbitrary data, associated with uploaded file.

    Non-string values will be converted to string. undefined values will be ignored.

    See docs and REST API for details.

    React Native

    Prepare

    To be able to use @uploadcare/upload-client with React Native, you need to install react-native-url-polyfill.

    To prevent Error: Cannot create URL for blob errors you need to configure your Android app schema to accept blobs - have a look at this pull request for an example: 5985d7e.

    1. Add the following code to the application section of your AndroidManifest.xml:
    <provider
      android:name="com.facebook.react.modules.blob.BlobProvider"
      android:authorities="@string/blob_provider_authority"
      android:exported="false"
    />
    1. Add the following code to the android/app/src/main/res/values/strings.xml:
    <resources>
      <string name="app_name">MY_REACT_NATIVE_APP_NAME</string>
      <string name="blob_provider_authority">com.detox.blob</string>
    </resources>

    Usage

    You can use ReactNativeAsset as an input to the @uploadcare/upload-client like this:

    type ReactNativeAsset = {
      uri: string
      type: string
      name?: string
    }
    const asset = { uri: 'URI_TO_FILE', name: 'file.txt', type: 'text/plain' }
    uploadFile(asset, { publicKey: 'YOUR_PUBLIC_KEY' })

    Or Blob like this:

    const uri = 'URI_TO_FILE'
    const blob = await fetch(uri).then((res) => res.blob())
    uploadFile(blob, {
      publicKey: 'YOUR_PUBLIC_KEY',
      fileName: 'file.txt',
      contentType: 'text/plain'
    })

    Testing

    npm run test
    

    By default, tests runs with mock server, but you can run tests with production environment.

    Run test on production servers:

    npm run test:production

    Run test with mock server (mock server starts automaticaly):

    npm run test

    Run mock server:

    npm run mock:start
    

    And then you can run test:

    npm run test:jest
    

    Security issues

    If you think you ran into something in Uploadcare libraries that might have security implications, please hit us up at bugbounty@uploadcare.com or Hackerone.

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

    Feedback

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

    Install

    npm i @uploadcare/upload-client

    DownloadsWeekly Downloads

    8,326

    Version

    6.2.1

    License

    MIT

    Unpacked Size

    204 kB

    Total Files

    7

    Last publish

    Collaborators

    • rsedykh
    • uploadcare-user
    • nd0ut