Reservations

ReservationsService

Dedicated-Mac reservations. A macOS sandbox runs on a Mac the organization has reserved: reserve one here, or let a macOS create buy one (reservation: 'new', or the organization’s auto-reserve). A reservation lasts 24-hour periods, each charged when it starts. Reserving, renewing and turning auto-renew on need the organization’s macos_sandboxes feature capability (otherwise 403 FEATURE_NOT_ENABLED, thrown as FeatureNotEnabledError); listing, reading and turning auto-renew off do not.

Constructors

Constructor

new ReservationsService(http: AxiosInstance): ReservationsService;

Parameters:

http AxiosInstance

Returns:

ReservationsService

Methods

create()

create(options: CreateReservationOptions): Promise<MacReservation>;

Reserve a Mac of model in region. Mac model slug from GET /mac-models. Omitted uses the region’s default model. An unavailable model is never upgraded. The request always carries an Idempotency-Key: idempotencyKey when given, otherwise a random key the SDK generates for this call. Pass your own key if you may retry, so a retry after a lost response returns the same reservation instead of reserving a second Mac. Fails with ConflictError code === 'NO_MAC_AVAILABLE' when no Mac of that model is free in the region.

Parameters:

options CreateReservationOptions

Returns:

Promise<MacReservation>

createBulk()

createBulk(options: CreateReservationsBulkOptions): Promise<MacReservationBatch>;

Reserve count Macs of one model in region in one request. minCount (default count) is the fewest to accept: with fewer Macs free, the request reserves as many as are free, or none, failing with ConflictError code === ‘NO_MAC_AVAILABLE’ when fewer than minCount are free. The request always carries an Idempotency-Key: idempotencyKey when given, otherwise a random key the SDK generates for this call. Pass your own key if you may retry, so a retry after a lost response returns the same reservations instead of reserving more Macs.

Parameters:

options CreateReservationsBulkOptions

Returns:

Promise<MacReservationBatch>

get()

get(id: string): Promise<MacReservation>;

Parameters:

id string

Returns:

Promise<MacReservation>

iter()

iter(options: ListReservationsOptions = {}): AsyncIterable<MacReservation>;

Parameters:

options ListReservationsOptions = {}

Returns:

AsyncIterable<MacReservation>

list()

list(options: ListReservationsOptions = {}): Promise<ListResult<MacReservation>>;

One page of the organization’s reservations.

Parameters:

options ListReservationsOptions = {}

Returns:

Promise<ListResult<MacReservation>>

renew()

renew(id: string, options: RenewReservationOptions = {}): Promise<MacReservation>;

Renew the reservation for its next period, which the server charges. The request always carries an Idempotency-Key: idempotencyKey when given, otherwise a random key the SDK generates for this call. Pass your own key if you may retry, so a retry after a lost response does not pay for a second period.

Parameters:

id string
options RenewReservationOptions = {}

Returns:

Promise<MacReservation>

update()

update(id: string, options: UpdateReservationOptions): Promise<MacReservation>;

Turn the reservation’s auto-renewal on or off. Turning it on needs the organization’s macos_sandboxes feature flag; turning it off works without it, so an organization can stop a reservation renewing. Fails with ConflictError when the reservation is no longer live.

Parameters:

id string
options UpdateReservationOptions

Returns:

Promise<MacReservation>

MacReservation

type MacReservation = Omit<api.MacReservation, 'status' | 'end_reason' | 'origin'> & {
  status: MacReservationStatus
  rawStatus: string
  end_reason?: MacReservationEndReason | null
  rawEndReason?: string | null
  origin: MacReservationOrigin
  rawOrigin: string
}

A dedicated-Mac reservation. Timestamps are RFC 3339 strings.

MacReservationBatch

type MacReservationBatch = Omit<api.MacReservationBatch, 'reservations'> & {
  reservations: MacReservation[]
}

POST /reservations/bulk: requested (the request’s count), reserved, and one reservation per reserved Mac.

MacReservationEndReason

type MacReservationEndReason = (typeof API_MAC_RESERVATION_END_REASONS)[number] | 'unknown'

MacReservationOrigin

type MacReservationOrigin = (typeof API_MAC_RESERVATION_ORIGINS)[number] | 'unknown'

explicit: bought by reservations.create() or a macOS create with reservation: 'new'; auto: bought by the organization’s auto-reserve.

MacReservationStatus

type MacReservationStatus = (typeof API_MAC_RESERVATION_STATUSES)[number] | 'unknown'

CreateReservationOptions

Properties:

region string - Region slug to reserve a Mac in.
model? string - Mac model slug from GET /mac-models. Omitted uses the region’s default model. An unavailable model is never upgraded.
layout? ‘split’ | ‘whole’ - split runs up to two sandboxes on the Mac, whole runs one. Omitted uses the model’s default layout.
idempotencyKey? string - A retry with the same key returns the first request’s reservation instead of reserving (and charging for) a second Mac. Omitted: a random key per call, so pass your own if you may retry.
autoRenew? boolean - Whether the reservation renews itself each period. The server defaults it to the organization’s auto-reserve setting at purchase time.

CreateReservationsBulkOptions

Properties:

region string - Region slug to reserve the Macs in.
count number - How many Macs to reserve, 1 to 100.
minCount? number - The fewest Macs to accept, 1 to count. Omitted means count: all or nothing.
model? string - Mac model slug from GET /mac-models. Omitted uses the region’s default model. An unavailable model is never upgraded.
layout? ‘split’ | ‘whole’ - split runs up to two sandboxes on each Mac, whole runs one. Omitted uses the model’s default layout.
autoRenew? boolean - Whether each reservation renews itself each period. The server defaults it to the organization’s auto-reserve setting at purchase time.
idempotencyKey? string - A retry with the same key returns the first request’s reservations instead of reserving more Macs. Omitted: a random key per call, so pass your own if you may retry.

ListReservationsOptions

Properties:

cursor? string
limit? number

RenewReservationOptions

Properties:

idempotencyKey? string - A retry with the same key returns the reservation without charging another period. Omitted: a random key per call, so pass your own if you may retry.

UpdateReservationOptions

Properties:

autoRenew boolean - Whether the reservation renews itself each period.