WIP

Installation

yarn add @airlst/sdk

Usage

Set API key

import { Api } from '@airlst/sdk'

Api.setApiKey('YOUR_API_KEY')

Methods

Currently available methods:

Event methods

Get all company events

Important: This method requires that API key must be company bound!

import { Event } from '@airlst/sdk'

const { data } = await new Event().list()

Get single event with UUID

import { Event } from '@airlst/sdk'

const { data } = await new Event().get('event-uuid')

Get temporary signed url to upload file directly to cloud storage

import { Guest } from '@airlst/sdk'

await new Event().generateTemporaryUploadUrl(eventUuid, fileMimeType, false);

Create temporary upload which can be attached to a guest extended field using upload uuid

import { Guest } from '@airlst/sdk'

await new Event().saveTemporaryUpload(eventUuid, temporaryUrlData, fileName, fileSize, fileMimeType, false);

Guest methods

List all guests

import { Guest } from '@airlst/sdk'

const { data } = await new Guest('event-uuid').list({ page: 2, search: 'John' })

Method accepts following parameters:

| Parameter | Type | Description | |----------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | page | number | Page number | | perPage | number | Number of items per page | | search | string | Quick search | | filters | array | Filters arrays | | filters.*.field | string | Filter field e.g: extended_fields->field1, booking:extended_fields->field1 | | filters.*.value | string | Filter field value | | filters.*.operator | string | Filter field operator. Optional. One of: eq (equal), neq (not equal), like, gt (greater than), gte (greater than or equal), lt (less than), lte (less than or equal). If operator is not provided eq will be used as default | | sorts | array | Sorts array | | sorts.*.field | string | Sort field | | sorts.*.direction | string | Sort field direction. One of: asc (ascending), desc (descending) | | sorts.*.order | number | Sort field order. Optional. Defines order/priority of the sort when sorting by multiple fields |

Validate guest code

import { Guest } from '@airlst/sdk'

const { data } = await new Guest('event-uuid').validatedCode('guest-code')

Get guest with code

import { Guest } from '@airlst/sdk'

const { data } = await new Guest('event-uuid').get('guest-code')

Create a new guest

import { Guest } from '@airlst/sdk'

const { data } = await new Guest('event-uuid').create({
  status: 'confirmed',
  contact: {
    first_name: 'John',
    last_name: 'Doe',
  }
})

Create a guest linked to an existing contact

Pass contact_id or contact_code instead of contact to attach the guest to a contact that already exists, rather than creating a new one. The contact must belong to the event's company.

Use contact_code when you authenticated the contact by code and never resolved its id — it is the same code Contact.get() takes and returns. Otherwise use contact_id, which Contact.get() also returns as data.contact.id.

contact, contact_id and contact_code are mutually exclusive — sending any pair fails validation. To correct the contact's data as well, create the guest and then call update() with the contact fields.

import { Guest } from '@airlst/sdk'

const { data } = await new Guest('event-uuid').create({
  status: 'confirmed',
  contact_code: 'QOI1U9GX',
  companions: [
    { contact_id: 'another-contact-uuid' },
    { contact: { first_name: 'Jane', last_name: 'Doe' } },
  ]
})

GuestManager.create() accepts both as well. Neither is accepted by createCompanion() or createRecommendation() — those endpoints do not support them.

Create a new companion guest

import { Guest } from '@airlst/sdk'

const { data } = await new Guest('event-uuid').createCompanion('guest-code', {
  contact: {
    first_name: 'John',
    last_name: 'Doe',
  }
})

Update existing guest

import { Guest } from '@airlst/sdk'

const { data } = await new Guest('event-uuid').update('guest-code', { status: 'confirmed' })

Update multiple guests

import { Guest } from '@airlst/sdk'

// Target specific guests by code
await new Guest('event-uuid').updateGuests({
  guests: ['ABCD1234', 'ABCD2345'],
  status: 'confirmed',
})

// Or target every guest, optionally narrowed by filters
await new Guest('event-uuid').updateGuests({
  guests: 'all',
  filters: { status: 'invited' },
  status: 'confirmed',
})

Archive guest

import { Guest } from '@airlst/sdk'

await new Guest('event-uuid').archive('guest-code')

Restore an archived guest

import { Guest } from '@airlst/sdk'

const { data } = await new Guest('event-uuid').restore('guest-code')

Delete guest

import { Guest } from '@airlst/sdk'

await new Guest('event-uuid').delete('guest-code')

Check in a guest

import { Guest } from '@airlst/sdk'

const { data } = await new Guest('event-uuid').checkin('guest-code', {
  type: Guest.CheckinType.CHECK_IN,
  device: 'Mobile',
  location: 'Munich',
  timestamp: Math.round(+new Date() / 1000),
})

Create recommendation

import { Guest } from '@airlst/sdk'

const { data } = await new Guest('event-uuid').createRecommendation('guest-code', {
    status: 'confirmed',
    contact: {
      first_name: 'John',
      last_name: 'Doe',
    }
  })

GuestManager methods

The GuestManager class provides the same functionality as Guest but is designed for managing guest managers. It has all the same methods as Guest, with the key difference being that the list() method uses a different endpoint and returns GuestManagerInterface objects which include a managed_guests array instead of guest_managers.

List all guest managers

import { GuestManager } from '@airlst/sdk'

const { data } = await new GuestManager('event-uuid').list({ page: 2, search: 'John' })

Method accepts the same parameters as Guest list method (see Guest methods section above).

All other methods

GuestManager supports all the same methods as Guest:

import { GuestManager } from '@airlst/sdk'

// Validate guest manager code
const { data } = await new GuestManager('event-uuid').validateCode('guest-manager-code')

// Get guest manager with code
const { data } = await new GuestManager('event-uuid').get('guest-manager-code')

// Create a new guest manager
const { data } = await new GuestManager('event-uuid').create({
  status: 'confirmed',
  contact: {
    first_name: 'John',
    last_name: 'Doe',
  }
})

// Update existing guest manager
const { data } = await new GuestManager('event-uuid').update('guest-manager-code', { status: 'confirmed' })

// Check in a guest manager
const { data } = await new GuestManager('event-uuid').checkin('guest-manager-code', {
  type: GuestManager.CheckinType.CHECK_IN,
  device: 'Mobile',
  location: 'Munich',
  timestamp: Math.round(+new Date() / 1000),
})

// And all other methods: createCompanion, archive, restore, delete, createRecommendation, getAttachments, getAttachmentSignedUrl

GuestGroup methods

List all guest groups

Returns the array of guest groups directly (unwrapped). Each group's name is a locale→string map.

import { GuestGroup } from '@airlst/sdk'

const guestGroups = await new GuestGroup('event-uuid').list()
// [{ id: '...', name: { 'en-GB': 'VIP', 'de-DE': 'VIP' } }, ...]

Email Template methods

Retrieve all email templates for the event

import { EmailTemplate } from '@airlst/sdk'

const { data } = await new EmailTemplate('event-uuid').list()

Send email template to selected guests

import { EmailTemplate } from '@airlst/sdk'

await new EmailTemplate('event-uuid').send('email-template-uuid',{
  guests:[
    "guest-code-1",
    "guest-code-2"
    ]
})

Contact methods

Validate guest code

import { Contact } from '@airlst/sdk'

const { data } = await new Contact().validateCode('contact-code')

Get contact with code

import { Contact } from '@airlst/sdk'

const { data } = await new Contact().get('contact-code')

Get events for the contact

import { Contact } from '@airlst/sdk'

const { data } = await new Contact().getEvents('contact-code')

Update contact master data

Updates a contact's master data by code — native fields and extended_fields — without creating a guest or registration. All fields are optional: native fields are overwritten when present, and extended_fields are merged key by key (existing keys are preserved). Returns the updated contact, same shape as get().

import { Contact } from '@airlst/sdk'

const { data } = await new Contact().update('contact-code', {
  contact: {
    first_name: 'Jane',
    mobile: '+4915212345678',
    extended_fields: { stammdaten_saved: true },
  },
})

Get all guest attachments

import { Guest } from '@airlst/sdk'

await new Guest('event-uuid').getAttachments('guest-code')

Get attachment signed downloadable URL

Note: The generated URL will be valid for 10 minutes

import { Guest } from '@airlst/sdk'

await new Guest('event-uuid').getAttachmentSignedUrl('guest-code','attachment-uuid')

Bookables methods

Get list of bookable groups

import { Bookable } from '@airlst/sdk'

const { data } = await new Bookable('event-uuid').listGroups()

Get list of bookable objects for group

import { Bookable } from '@airlst/sdk'

const { data } = await new Bookable('event-uuid').listBookables('bookable-group-uuid')

Get list of availabilities for bookable object

import { Bookable } from '@airlst/sdk'

const { data } = await new Bookable('event-uuid').listAvailabilities('bookable-group-uuid', 'bookable-object-uuid', {
  start_date: '2025-01-02',
  end_date: '2025-02-03',
  // Optional: resolve the guest's group to compute guest-specific remaining capacity
  guest_code: 'guest-code'
})

Every datetime in the response is an absolute UTC instant, never event-local wall clock. The response publishes the event timezone as data.timezone (e.g. Europe/Berlin) — the same value is also on EventInterface — so you can render those instants and convert a wall-clock time picked by a user back to UTC without a second request.

For a slot-based FLEXIBLE bookable, each availability also carries the slot configuration so you can derive the bookable slots yourself: convert starts_at into data.timezone, step duration_minutes + buffer_minutes in that local wall clock until the window closes, then convert each slot boundary back to UTC — which is how the server generates them. Each slot covers [slot_start, slot_start + duration_minutes) and seats capacity_per_slot units. A window whose closing time is not after its opening time (e.g. 22:00–06:00, or 00:00–00:00 for 24/7) runs past midnight, and every day of the availability repeats the full window. Book each slot as its own line_items entry via addOrderLineItem().

Step in local time, not in UTC. Across a DST transition inside the window, consecutive slots are not a fixed number of UTC minutes apart, so a UTC-stepped grid diverges from the server's.

duration_minutes is the mode signal — it is null for every non-slot availability. Do not detect slot mode from buffer_minutes or capacity_per_slot: those always carry their defaults (0 / 1).

Each availability also carries the price for its own pricing model, so you never have to hardcode a price in the frontend. At most one of the three fields is populated; the others are null:

| Field | Populated for | Shape | | --- | --- | --- | | per_item_price | quantity-based (FIXED) | { [guestGroupId]: Price } — per item, multiply by the quantity | | per_duration_price | slot-based (FLEXIBLE with duration_minutes) | { [guestGroupId]: { [minutes]: Price } } — per slot; does not scale with the slot length | | per_night_price | per-night (NIGHTS) | { [guestGroupId]: { [YYYY-MM-DD]: Price } } — per night, sum the stay |

net, gross and vat are integers in minor units (cents) with gross inclusive of VAT, and vat_rate is a percentage. The outer key is the availability's own guest group, or 00000000-0000-0000-0000-000000000000 for a row that applies to every group without a specific price. A legacy FLEXIBLE availability with no duration_minutes has no per-duration price and reports null.

Create reservation

import { Bookable } from '@airlst/sdk'

const { data } = await new Bookable('event-uuid').createReservation('bookable-group-uuid', {
    guest_code: 'guest-code',
    reservations: [
      {
        bookable_id: 'bookable-object-uuid',
        // Required unless the bookable is an add-on with a FIXED availability type, which has no
        // date window. For those, omit both — any dates sent are ignored and the reservation is
        // stored without them.
        starts_at: '2025-02-04 13:20:00',
        ends_at: '2025-02-04 13:40:00',
        quantity: 1,
        // Reservation-scoped extended fields, keyed by field key. Only keys defined on the
        // bookable group for the `bookableReservation` model are accepted.
        extended_fields: { test_field: 'probeA123' }
      }
    ]
})

Delete reservation

import { Bookable } from '@airlst/sdk'

await new Bookable('event-uuid').deleteReservation('guest-code', 'reservation-uuid')

Get or create a booking's CART carrier order

import { Bookable } from '@airlst/sdk'

const { data } = await new Bookable('event-uuid').createOrder({
  booking_id: 'booking-uuid'
})

Get list of a booking's CART carrier orders

import { Bookable } from '@airlst/sdk'

const { data } = await new Bookable('event-uuid').listOrders('booking-uuid')

Show a carrier order with its line items and add-on reservations

import { Bookable } from '@airlst/sdk'

const { data } = await new Bookable('event-uuid').getOrder('order-uuid')

Add add-on allocation line items to a carrier order

Pass line_items to allocate any number of add-ons in one request. Entries are independent, so a single call can book several slots of a slot-based FLEXIBLE add-on (e.g. 20 hourly shifts of stand security), book non-contiguous slots, mix different add-ons and use a different quantity per entry.

The payload is applied all-or-nothing: if any entry is invalid or unavailable, nothing is held and the request fails with 422 naming the rejected entry (Line item 1: …). At most 50 entries per request.

start_at and end_at are absolute instants, never event-local wall clock. Send UTC (…Z) or an explicit offset (2026-06-03T11:00:00+02:00), which is stored as the same instant; a value carrying no zone at all is read as UTC. To book a wall-clock time, convert it from the event timezone first — listAvailabilities() returns it as data.timezone. Sending 23:00 for a 23:00 event-local slot in a UTC+2 event books a different slot, or none.

import { Bookable } from '@airlst/sdk'

const { data } = await new Bookable('event-uuid').addOrderLineItem('order-uuid', {
  guest_code: 'guest-code',
  line_items: [
    {
      addon_id: 'addon-uuid',
      // Required unless the add-on has a FIXED availability type. For a slot-based FLEXIBLE add-on
      // these must be the boundaries of one slot — a range spanning several slots is rejected, so
      // send one entry per slot. Read duration_minutes / buffer_minutes / capacity_per_slot from
      // listAvailabilities() to work out the slots.
      start_at: '2026-06-03T09:00:00Z',
      end_at: '2026-06-03T10:00:00Z',
      quantity: 1
    },
    {
      addon_id: 'addon-uuid',
      start_at: '2026-06-03T10:00:00Z',
      end_at: '2026-06-03T11:00:00Z',
      quantity: 1,
      // Reservation-scoped extended fields, keyed by field key. Only keys defined on the add-on's
      // bookable group for the `bookableReservation` model are accepted, and each value is validated
      // against its field definition. For NIGHTS add-ons the values are written to every per-night
      // reservation.
      extended_fields: { test_field: 'probeA123' }
    }
  ]
})
// data.reservation_ids => ['reservation-uuid', ...] (flat, in submission order)
// data.line_items => [{ index: 0, reservation_ids: [...] }, { index: 1, reservation_ids: [...] }]

The previous single-item body (addon_id / start_at / end_at / quantity / extended_fields at the top level) still works unchanged, but is deprecated in favour of line_items:

const { data } = await new Bookable('event-uuid').addOrderLineItem('order-uuid', {
  guest_code: 'guest-code',
  addon_id: 'addon-uuid',
  quantity: 1
})

Delete an add-on allocation line item and release its contingent

import { Bookable } from '@airlst/sdk'

await new Bookable('event-uuid').deleteOrderLineItem('order-uuid', 'line-item-uuid')

Bulk-delete add-on allocation line items in one request

Removes several line items at once. A slot-based add-on holds one line item per slot, so this clears a whole time range in a single call instead of one deleteOrderLineItem() per slot. Read the ids from getOrder(). Up to 100 ids per request; the call is all-or-nothing.

deleted_line_item_ids is the authoritative list of what was removed — it can name more ids than the request when a NIGHTS add-on releases the whole contiguous stay.

import { Bookable } from '@airlst/sdk'

const { data } = await new Bookable('event-uuid').bulkDeleteOrderLineItems('order-uuid', {
  line_item_ids: ['line-item-uuid-1', 'line-item-uuid-2']
})

console.log(data.deleted_count, data.deleted_line_item_ids)

Bulk-assign an add-on to many guests

Assigns a single add-on selection to many guests at once. Processing is asynchronous, so the call resolves with no content once the batch has been queued.

import { Bookable } from '@airlst/sdk'

await new Bookable('event-uuid').assignBookables({
  // Either an explicit list of guest codes, or the string 'all'
  guests: ['ABCD1234', 'ABCD2345'],
  // Optional: only applied when guests is 'all'
  filters: {
    status: 'confirmed',
    guest_group_id: 'guest-group-uuid'
  },
  bookable_group_id: 'bookable-group-uuid',
  // Must also include every flexible add-on referenced in selected_slots
  selected_bookable_objects: ['bookable-object-uuid'],
  // For FLEXIBLE add-ons: one reservation is created per slot
  selected_slots: [
    {
      bookable_id: 'bookable-object-uuid',
      start_at: '2026-06-03 09:00:00',
      end_at: '2026-06-03 09:30:00'
    }
  ],
  // Required when a NIGHTS add-on is selected (end_date = excluded check-out day)
  start_date: '2026-06-03',
  end_date: '2026-06-06'
})