Offer

Offer is a type returned from many API calls that handle sensitive user data, or calls that require certain permissions to achieve.

Offer values detail the result of an asynchronous user operation, such as displaying a share sheet, copying a photo to a photo album, or creating a new contact.

These operations are mostly user-cancellable, and subject to various edge-cases. Offer helps here by abstracting this away into a common interface that can be inspected and used to display information to the user.

Properties

Offer.cancelled: boolean

Indicates if the user or the operating system cancelled the operation.

Offer.userCancelled: boolean

Indicates if the user directly cancelled the operation. Equivalent to:

offer.cancelled && offer.cancellationReason === os.OfferCancellationReason.UserCancelled

Offer.details: object|undefined

If the Offer was cancelled, returns undefined. Otherwise, relevant data from the operation will be stored here. For details on what properties you can access here, see the documentation for the offer methods themselves.

Offer.cancellationReason: string|undefined

If the Offer succeeded, returns undefined. Otherwise, returns one of the following properties from the os.OfferCancellationReason enum:

  • UserCancelled - when the user presses a ‘Cancel’ or ‘Back’ button
  • OsInterrupted - when the device interrupts the request, e.g. a phone call
  • OutOfSpace - when the device does not have enough storage space to complete the request
  • RequestFailed - when a request failed, e.g. losing your internet connection when saving a file to cloud storage
  • PermissionDenied - when a user has denied permission to the application for this offer, or if permission has not been requested yet

Note that not all of these would be returned from each offer method, for details on which properties are returned, see the documentation for the offer methods themselves.

Offer.localisedCancellationReason: string|undefined

If the Offer succeeded, returns undefined. Otherwise, returns a user-friendly description of the reason behind the cancellation.

Example

const fs = require('fs')
const os = require('os')
const path = require('path')

const localPath = path.join(os.homeDirectory, 'abc.pdf')
const documentsDir = fs.Location.Documents

const offer = await fs.offerCopyToLocation(documentsDir, localPath)

if (offer.cancelled && !offer.userCancelled) {
  const alertContent = `We weren't able to save your document as ${offer.localisedFailureReason}. Do you want to try again?`
  window.confirm(alertContent, (shouldRetry) => {})
}