This is an Uploadcare Upload API wrapper to work with Node.js and browser.
npm install @uploadcare/upload-clientTo 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 = ({ value }) => {
console.log(value)
}
client
.uploadFile(fileUUID, { onProgress })
.then(file => console.log(file.uuid))You can cancel file uploading and track this event:
const fileUUID = 'edfdf045-34c0-4087-bbdd-e3834921f890'
const controller = new CancelController()
client
.uploadFile(fileUUID, { cancel: controller })
.then(file => console.log(file.uuid))
.catch(error => {
if (error.isCancel) {
console.log(`File uploading was canceled.`)
}
})
// Cancel uploading
controller.cancel()List of all available UploadClient API methods:
interface UploadClient {
updateSettings(newSettings: Settings = {}): void
getSettings(): Settings
base(
file: NodeFile | BrowserFile,
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: NodeFile | BrowserFile | Url | Uuid,
options: FileFromOptions
): Promise<UploadcareFile>
uploadFileGroup(
data: (NodeFile | BrowserFile)[] |<
8000
/span> Url[] | Uuid[],
options: FileFromOptions & GroupFromOptions
): Promise<UploadcareGroup>
}Also, you can use low-level wrappers to call the API endpoints directly:
import { base, CancelController } from '@uploadcare/upload-client'
const onProgress = ({ value }) => console.log(value)
const cancelController = new CancelController()
base(fileData, { onProgress, cancel: cancelController }) // 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:
cancelController.cancel()List of all available API methods:
base(
file: NodeFile | BrowserFile,
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>multipart(
file: File | Buffer | Blob,
options: MultipartOptions
): Promise<FileInfo>The main use of a publicKey is to identify a target project for your uploads.
It is required when using Upload API.
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/.
API base URL.
Defaults to https://upload.uploadcare.com
You can specify an original filename.
Defaults to original.
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.
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.
Stands for the Unix time to which the signature is valid, e.g., 1454902434.
X-UC-User-Agent header value.
Defaults to UploadcareUploadClient/${version}/${publicKey} (JavaScript; ${integration})
Runs the duplicate check and provides the immediate-download behavior.
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.
Defines the upload source to use, can be set to local, url, etc.
Sets the name of your JSONP callback function to create files group from a set of files by using their UUIDs.
maxContentLength defines the maximum allowed size (in bytes) of the HTTP
response content.
Defaults to 52428800 bytes (50 MB).
Sets the maximum number of attempts to retry throttled requests.
Defaults to 1.
This option is only applicable when handling local files. Sets the multipart chunk size.
Defaults to 5242880 bytes (5 MB).
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).
This option is only applicable when handling local files. Set the minimum size of the last multipart part.
Defaults to 1048576 bytes (1 MB).
Allows specifying the number of concurrent requests.
Defaults to 4.
This setting is needed for correct multipart uploads.
Defaults to application/octet-stream.
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:productionRun test with mock server (mock server starts automaticaly):
npm run testRun mock server:
npm run mock:start
And then you can run test:
npm run test:jest
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.
Issues and PRs are welcome. You can provide your feedback or drop us a support request at hello@uploadcare.com.