Portive Client

Upload API

Upload a file or image to the Portive cloud.

Stages of an Upload

When a file is uploaded using the uploadFile method, it goes through several stages:

1. Fetch Policy: An API call is made to an API endpoint to request an Upload Policy. This contains the information needed to directly upload a file securely to an upload endpoint.
2. Send File: The file is sent using the information from the upload policy. The majority of the time in an upload is spent sending the file.
3. Progress: While the file is sending, we intermittently send progress reports using a callback. This can be used to show the progress of an upload using something like a progress bar.
4. Success: The file is finished successfully uploading.

If it any point the upload fails, an Error is returned.

uploadFile

uploadFile Method

The method used to upload a file to the Portive cloud.

uploadFile is an async function that returns the final upload state which can be either a success or an error. A number of callbacks can be passed in as options during different stages in the upload.

function uploadFile(options: {
  client: Client
  file: File
  // before we get the upload policy
  onBeforeFetch?: (e: UploadBeforeFetchEvent) => void
  // once we start uploading to AWS S3
  onBeforeSend?: (e: UploadBeforeSendEvent) => void
  // progress updates
  onProgress?: (e: UploadProgressEvent) => void
  // error
  onError?: (e: UploadErrorEvent) => void
  // success
  onSuccess?: (e: UploadSuccessEvent) => void
  // Called on `error` or `success` event
  onFinish?: (e: UploadFinishEvent) => void
}): Promise<UploadFinishEvent> {}

uploadFile Return Value

The uploadFile method returns a Promise<UploadFinishEvent> which represents either an error during the upload or a successful upload.

type UploadFinishEvent = UploadErrorEvent | UploadSuccessEvent

type UploadErrorEvent = {
  type: "error"
  message: string
  file: File
  clientFile: ClientFile
  // Note: Omit `hostedFile` because error may come before it is available
}

type UploadSuccessEvent = {
  type: "success"
  file: File
  clientFile: ClientFile
  hostedFile: HostedFileInfo
}

uploadFile Options

client: Client

Required instance of a Client object created using the createClient method

file: File

Required instance of a File object.

The most common place to get one is from an <input type="file"> Element.

HTML Example:

<input id="fileinput" type="file" />
<script>
  const input = document.getElementById("fileInput")
  input.onchange = function (e) {
    // get the file
    const file = e.target.files[0]
  }
</script>

React Example:

function MyComponent() {
  function onChange(e) {
    // get the file
    const file = e.target.files[0]
  }
  return <input type="file" onChange={onChange}>
}

onBeforeFetch?: (event) => void

Called when the upload method is first executed. This callback is called before fetching the upload policy which is required for uploading the file to the servers but after the file has been determined to be either of type image or of type generic (not an image). If the file is determined to be an image, we have also figured it's width and height. All this information can be found in the clientFile object which is part of the UploadBeforeFetchEvent.

type onBeforeFetch = (e: UploadBeforeFetchEvent) => void

export type UploadBeforeFetchEvent = {
  type: "beforeFetch"
  file: File
  clientFile: ClientFile
  // `hostedFile` does not exist until after we get the upload policy
}

onBeforeSend?: (event) => void

Called after the upload policy has been fetched and right before sending the upload to the server. At this point, the destination url is known and is provided as part of the hostedFile object.

type onBeforeSend = (e: UploadBeforeSendEvent) => void

export type UploadBeforeSendEvent = {
  type: "beforeSend"
  file: File
  clientFile: ClientFile
  hostedFile: HostedFileInfo
}

onProgress?: (event) => void

Called intermmitently during the upload. This event can be used to show a progress bar using the senteBytes and `totalBytes

type onProgress = (e: UploadProgressEvent) => void

export type UploadProgressEvent = {
  type: "progress"
  file: File
  clientFile: ClientFile
  hostedFile: HostedFileInfo
  sentBytes: number
  totalBytes: number
}

onError?: (event) => void

Called if there is an error anytime during the upload process.

type onError = (e: UploadErrorEvent) => void

export type UploadErrorEvent = {
  type: "error"
  message: string
  file: File
  clientFile: ClientFile
  // Note: Omit `hostedFile` because error may come before it is available
}

onSuccess?: (event) => void

Called after a successful upload. At this point, the file exists on the cloud servers.

type onSuccess = (e: UploadSuccessEvent) => void

export type UploadSuccessEvent = {
  type: "success"
  file: File
  clientFile: ClientFile
  hostedFile: HostedFileInfo
}

onFinish?: (event) => void

Called when there is either an error or a successful upload. This method is like a finally in a try/catch statement. Whether there is an error or not, the onFinish callback gets called. It is called either with an UploadErrorEvent or an UploadSuccessEvent.

type onFinish = (e: UploadErrorEvent | UploadSuccessEvent) => void