seatsio
v84.2.0
Published
Official JavaScript and Node.JS client library for the Seats.io REST API
Downloads
10,766
Keywords
Readme
seatsio-js, the official Seats.io JS SDK
This is the official JavaScript client library for the Seats.io V2 REST API.
[!IMPORTANT] ❗️ Read This First!
seatsio-js
requires your seats.io secret key. This key carries many privileges, including creating events, booking and releasing seats, and more. If you use this lib in a browser, you are exposing your secret key to your user.This means you can only use
seatsio-js
:
- on the server (Node), just like any other seats.io API client library
- in the browser, in a secure, password-protected backoffice application for administrators. Never, ever on pages that are accessible by your customers or ticket buyers.
👉 Only use this in browser code if you know what you're doing. You have been warned :)
Installing
For Node, you can install using yarn or npm:
yarn add seatsio
# or
npm install seatsio --save
Usage
General instructions
To use this library, you'll need to create a SeatsioClient
:
import { SeatsioClient, Region } from 'seatsio'
let client = new SeatsioClient(Region.EU(), <WORKSPACE SECRET KEY>)
...
You can find your workspace secret key in the settings section of the workspace. It is important that you keep your secret key private and not expose it in-browser calls unless it is password protected.
The region should correspond to the region of your account:
Region.EU()
: EuropeRegion.NA()
: North-AmericaRegion.SA()
: South-AmericaRegion.OC()
: Oceania
If you're unsure about your region, have a look at your company settings page.
Creating a chart and an event
import { SeatsioClient, Region } from 'seatsio'
let client = new SeatsioClient(Region.EU(), <WORKSPACE SECRET KEY>)
let chart = await client.charts.create()
let event = await client.events.create(chart.key)
console.log(`Created a chart with key ${chart.key} and an event with key: ${event.key}`)
Creating multiple events
import { SeatsioClient, Region, Events } from 'seatsio'
let client = new SeatsioClient(Region.EU(), <WORKSPACE SECRET KEY>)
let chart = await client.charts.create()
let events = await client.events.createMultiple(chart.key, [ Events.eventCreationParams(), Events.eventCreationParams('aSpecificEventKey') ])
for (const event of events) {
console.log(`Created an event with key: ${event.key}`)
}
Booking objects
Booking an object changes its status to booked
. Booked seats are not selectable on a rendered chart.
https://docs.seats.io/docs/api-book-objects.
import { SeatsioClient, Region } from 'seatsio'
let client = new SeatsioClient(Region.EU(), <WORKSPACE SECRET KEY>)
await client.events.book(<AN EVENT KEY>, ['A-1', 'A-2'])
Booking objects that are on HOLD
import { SeatsioClient, Region } from 'seatsio'
let client = new SeatsioClient(Region.EU(), <WORKSPACE SECRET KEY>)
await client.events.book(<AN EVENT KEY>, ["A-1", "A-2"], <A HOLD TOKEN>)
Booking general admission (GA) areas
Either
import { SeatsioClient, Region } from 'seatsio'
let client = new SeatsioClient(Region.EU(), <WORKSPACE SECRET KEY>)
await client.events.book(<AN EVENT KEY>, ["GA1", "GA1", "GA1"])
Or:
import { SeatsioClient, Region } from 'seatsio'
let client = new SeatsioClient(Region.EU(), <WORKSPACE SECRET KEY>)
await client.events.book(<AN EVENT KEY>, {"objectId": "GA1", "quantity" : 3})
Releasing objects
Releasing objects changes its status to free
. Free seats are selectable on a rendered chart.
https://docs.seats.io/docs/api-release-objects.
import { SeatsioClient, Region } from 'seatsio'
let client = new SeatsioClient(Region.EU(), <WORKSPACE SECRET KEY>)
await client.events.release(<AN EVENT KEY>, ["A-1", "A-2"])
Changing object status
Changes the object status to a custom status of your choice. If you need more statuses than just booked and free, you can use this to change the status of a seat, table or booth to your own custom status.
https://docs.seats.io/docs/api-custom-object-status
import { SeatsioClient, Region } from 'seatsio'
let client = new SeatsioClient(Region.EU(), <WORKSPACE SECRET KEY>)
await client.events.changeObjectStatus(<AN EVENT KEY>, ["A-1", "A-2"], "unavailable")
Listing status changes
statusChanges
method returns a Lister
. You can use statusChanges().all()
, which returns an AsyncIterator, in a for await
loop to iterate over all status changes.
for await (let statusChange of client.events.statusChanges(<AN EVENT KEY>).all()) {
//Do something with the status change
}
You can alternatively use the paginated methods to retrieve status changes. To list status changes that comes after or before a given status change, you can use statusChanges().pageAfter()
and statusChanges().pageBefore()
methods.
await client.events.statusChanges(<AN EVENT KEY>).firstPage(<OPTIONAL parameters>, <OPTIONAL pageSize>)
await client.events.statusChanges(<AN EVENT KEY>).pageAfter(<A STATUS CHANGE ID>, <OPTIONAL parameters>, <OPTIONAL pageSize>)
await client.events.statusChanges(<AN EVENT KEY>).pageBefore(<A STATUS CHANGE ID>, <OPTIONAL parameters>, <OPTIONAL pageSize>)
You can also pass an optional parameter to filter, sort or order status changes. For this parameter, you can you use the helper class called StatusChangesParams
.
const {StatusChangesParams} = require('seatsio')
let parameter = new StatusChangesParams().withFilter('testFilter')
let parameter = new StatusChangesParams().sortByObjectLabel()
let parameter = new StatusChangesParams().sortByDate()
let parameter = new StatusChangesParams().sortByStatus()
let parameter = new StatusChangesParams().sortDescending()
let parameter = new StatusChangesParams().sortAscending()
A combination of filter, sorting order and sorting option is also possible.
let parameter = new StatusChangesParams().withFilter('testFilter').sortByStatus().sortAscending()
Retrieving object category and status (and other information)
import { SeatsioClient, Region } from 'seatsio'
let client = new SeatsioClient(Region.EU(), <WORKSPACE SECRET KEY>)
let objectInfos = await client.events.retrieveObjectInfos(event.key, ['A-1', 'A-2'])
console.log(objectInfos['A-1'].categoryKey)
console.log(objectInfos['A-1'].categoryLabel)
console.log(objectInfos['A-1'].status)
console.log(objectInfos['A-2'].categoryKey)
console.log(objectInfos['A-2'].categoryLabel)
console.log(objectInfos['A-2'].status)
Event reports
Want to know which seats of an event are booked, and which ones are free? That’s where reporting comes in handy.
The report types you can choose from are:
- byStatus
- byCategoryLabel
- byCategoryKey
- byLabel
- byOrderId
https://docs.seats.io/docs/api-event-reports
import { SeatsioClient, Region } from 'seatsio'
let client = new SeatsioClient(Region.EU(), <WORKSPACE SECRET KEY>)
await client.eventReports.byStatus(<AN EVENT KEY>, <OPTIONAL FILTER>)
Listing all charts
You can list all charts using listAll()
method which returns an asynchronous iterator AsyncIterator
. You can use for await
loop to retrieve all charts.
import { SeatsioClient, Region } from 'seatsio'
let client = new SeatsioClient(Region.EU(), <WORKSPACE SECRET KEY>)
for await(let chart of client.charts.listAll()){
console.log(`Chart key: ${chart.key}`)
}
Listing charts page by page
E.g. to show charts in a paginated list on a dashboard.
Each page contains an items
array of charts, and nextPageStartsAfter
and previousPageEndsBefore
properties. Those properties are the chart IDs after which the next page starts or the previous page ends.
// ... user initially opens the screen ...
let firstPage = client.charts.listFirstPage();
firstPage.items.forEach(chart => console.log(`Chart key: ${chart.key}`));
// ... user clicks on 'next page' button ...
let nextPage = client.charts.listPageAfter(firstPage.nextPageStartsAfter);
nextPage.items.forEach(chart => console.log(`Chart key: ${chart.key}`));
// ... user clicks on 'previous page' button ...
let previousPage = client.charts.listPageBefore(nextPage.previousPageEndsBefore);
previousPage.items.forEach(chart => console.log(`Chart key: ${chart.key}`));
Creating a workspace
import { SeatsioClient, Region } from 'seatsio'
let client = new SeatsioClient(Region.EU(), <COMPANY ADMIN KEY>)
await client.workspaces.create('a workspace');
Creating a chart and an event with the company admin key
import { SeatsioClient, Region } from 'seatsio'
let client = new SeatsioClient(Region.EU(), <COMPANY ADMIN KEY>, <WORKSPACE PUBLIC KEY>)
let chart = await client.charts.create()
let event = await client.events.create(chart.key)
console.log(`Created a chart with key ${chart.key} and an event with key: ${event.key}`)
Listing categories
import { SeatsioClient, Region } from 'seatsio'
let client = new SeatsioClient(Region.EU(), <COMPANY ADMIN KEY>, <WORKSPACE PUBLIC KEY>)
let categoryList = await client.charts.listCategories("the chart key")
for (const category of categoryList) {
console.log(category.label)
}
Updating a category
import { SeatsioClient, Region } from 'seatsio'
let client = new SeatsioClient(Region.EU(), <COMPANY ADMIN KEY>, <WORKSPACE PUBLIC KEY>)
await client.charts.updateCategory(chart.key, 1, new CategoryUpdateParams()
.withLabel('New label').withColor('#bbbbbb').withAccessible(true))```
Error Handling
When an API call results in an error, a rejected promise is returned with a value that looks like
{
"errors": [{ "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded" }],
"messages": ["Rate limit exceeded"],
"requestId": "123456",
"status": 429
}
Rate limiting - exponential backoff
This library supports exponential backoff.
When you send too many concurrent requests, the server returns an error 429 - Too Many Requests
. The client reacts to this by waiting for a while, and then retrying the request.
If the request still fails with an error 429
, it waits a little longer, and try again. By default this happens 5 times, before giving up (after approximately 15 seconds).
To change the maximum number of retries, create the SeatsioClient
as follows:
import { SeatsioClient, Region } from 'seatsio'
let client = new SeatsioClient(Region.EU(), <WORKSPACE SECRET KEY>).setMaxRetries(3)
Passing in 0 disables exponential backoff completely. In that case, the client will never retry a failed request.
TypeScript
Since v76, this package contains TypeScript definitions.