Reference

Class: TicketlayerLive

Class: TicketlayerLive in @ticketlayer/live.

@ticketlayer/live / index / TicketlayerLive

@ticketlayer/live - the buyer-facing client for the Ticketlayer Live surface.

The client surface (sales operations + session/queue) is GENERATED from the backstage sales-surface projection + the live-api spec (see client.ts). The only hand-written part is createLiveClient (browser/native ergonomics).

Runs in the browser and React Native (publishable key + X-Live-Session header

pluggable token storage). Web builds may additionally bundle @ticketlayer/elements; native apps use the headless client + webview checkout.

Extended by#

NativeTicketlayerLive

Accessors#

hasSession#

Get Signature#

get hasSession(): boolean;

Defined in: core/liveClient.ts:1023

True once a session has been created/resumed (i.e. a mutation has happened).

Returns

boolean

seating#

Get Signature#

get seating(): SeatingManager;

Defined in: core/liveClient.ts:411

The seat map (TKT-462): the pointer, the token (which never leaves this client), the immutable files and the availability poller. Built on first use. The reservations are the cart's: cart.reserveSeat and friends.

Returns

SeatingManager

session#

Get Signature#

get session(): Readonly<SessionState>;

Defined in: core/liveClient.ts:1018

Returns

Readonly<SessionState>

Constructors#

Constructor#

new TicketlayerLive(client: LiveClient, opts: {
  baseUrl: string;
  domain?: string;
  publishableKey?: string;
  sessionMode: "cookie" | "token";
}): TicketlayerLive;

Defined in: core/liveClient.ts:428

Parameters#

Parameter	Type
`client`	`LiveClient`
`opts`	{ `baseUrl`: `string`; `domain?`: `string`; `publishableKey?`: `string`; `sessionMode`: `"cookie"` \| `"token"`; }
`opts.baseUrl`	`string`
`opts.domain?`	`string`
`opts.publishableKey?`	`string`
`opts.sessionMode`	`"cookie"` \| `"token"`

Returns#

TicketlayerLive

Methods#

emit()#

emit(event: LiveEvent, payload?: unknown): void;

Defined in: core/liveClient.ts:1014

Push an event onto the shared bus. Used by Elements/host to raise UI intents (e.g. ui:checkout-requested) that the host app acts on - the SDK relays but does not render UI itself.

Parameters#

Parameter	Type
`event`	`LiveEvent`
`payload?`	`unknown`

Returns#

void

ensureSession()#

ensureSession(): Promise<void>;

Defined in: core/liveClient.ts:1033

Create the Live session on demand and hydrate state - idempotent and single-flight. Called lazily before the first mutation (cart/login); NOT on page load, so browsing never creates a session. Channel is identified by the publishable key (embed) or the storefront domain (hosted).

Returns#

Promise<void>

getSessionToken()#

getSessionToken(): Promise<string | null>;

Defined in: core/liveClient.ts:1102

The current session token (token mode), for handing off to an embed iframe.

Returns#

Promise<string | null>

off()#

off(event: LiveEvent, handler: (payload?: unknown) => void): void;

Defined in: core/liveClient.ts:1006

Parameters#

Parameter	Type
`event`	`LiveEvent`
`handler`	(`payload?`: `unknown`) => `void`

Returns#

void

on()#

on(event: LiveEvent, handler: (payload?: unknown) => void): () => void;

Defined in: core/liveClient.ts:1003

Subscribe to a state event or UI intent; returns an unsubscribe fn.

Parameters#

Parameter	Type
`event`	`LiveEvent`
`handler`	(`payload?`: `unknown`) => `void`

Returns#

() => void

refreshSession()#

refreshSession(): Promise<void>;

Defined in: core/liveClient.ts:1107

Re-read session state (customer, auth, cart) from the live-api session.

Returns#

Promise<void>

request()#

request(
   method: "POST" | "GET" | "DELETE" | "PATCH", 
   path: string, 
   body?: unknown, 
   options?: {
  seat?: boolean;
}
): Promise<unknown>;

Defined in: core/liveClient.ts:916

A call to Live that the generated client does not have yet (the seat map routes reach it when its spec is next generated): the same credentials, TL-Version and TL-Client as every generated call, the JSend envelope unwrapped. A failure throws LiveAPIError; with seat, the typed seat error, carrying whatever the envelope said beside the code.

Parameters#

Parameter	Type
`method`	`"POST"` \| `"GET"` \| `"DELETE"` \| `"PATCH"`
`path`	`string`
`body?`	`unknown`
`options?`	{ `seat?`: `boolean`; }
`options.seat?`	`boolean`

Returns#

Promise<unknown>

resume()#

resume(token: string): Promise<void>;

Defined in: core/liveClient.ts:1095

Resume an EXISTING session by token instead of bootstrapping a new one. Used by the embedded checkout iframe: the third-party page hands off its session token so the iframe sees the same cart/channel (token transport).

Parameters#

Parameter	Type
`token`	`string`

Returns#

Promise<void>

resumeIfExists()#

resumeIfExists(): Promise<boolean>;

Defined in: core/liveClient.ts:1078

Rehydrate an ALREADY-EXISTING session (hosted/cookie transport) without creating one. On a page load/refresh the client is lazily session-less, but a returning visitor may still hold the live_session cookie with a cart server-side. This probes GET /session (a cheap read - it 401s when no session exists, and never writes one): on success it binds this client to that session and pulls the cart back in; on 401 it stays session-less so browsing still creates no session. Marking _sessionStarted on success is load-bearing - otherwise the next mutation's ensureSession() would POST a fresh session and orphan the existing cart.

Returns#

Promise<boolean>

true if an existing session was resumed.

Properties#

auth#

readonly auth: {
  authenticated: boolean;
  customer: unknown;
  exchange: (proof: 
     | string
     | {
     assertion?: string;
     code?: string;
     email?: string;
     phone?: string;
     type: string;
  }) => Promise<unknown>;
  logout: () => Promise<void>;
  requestMagicLink: (contact: {
     email?: string;
     phone?: string;
  }) => Promise<unknown>;
};

Defined in: core/liveClient.ts:329

authenticated#

readonly authenticated: boolean;

customer#

readonly customer: unknown;

exchange#

exchange: (proof: 
  | string
  | {
  assertion?: string;
  code?: string;
  email?: string;
  phone?: string;
  type: string;
}) => Promise<unknown>;

Exchange a sign-in proof for a customer on this session. A bare string is a magic_link code on its own, which is what the long token a sign-in link carries is. A 6-digit code typed out of the email or text goes with the email or phone it was sent to, so the API checks it against that contact's one live code; without it the code is refused.

Parameters

Parameter	Type
`proof`	\| `string` \| { `assertion?`: `string`; `code?`: `string`; `email?`: `string`; `phone?`: `string`; `type`: `string`; }

Returns

Promise<unknown>

logout#

logout: () => Promise<void>;

Returns

Promise<void>

requestMagicLink#

requestMagicLink: (contact: {
  email?: string;
  phone?: string;
}) => Promise<unknown>;

Parameters

Parameter	Type
`contact`	{ `email?`: `string`; `phone?`: `string`; }
`contact.email?`	`string`
`contact.phone?`	`string`

Returns

Promise<unknown>

cart#

readonly cart: {
  add: (item: CartItemInput) => Promise<unknown>;
  addGiftCard: (choice: GiftCardChoice) => Promise<unknown>;
  applyCode: (code: string) => Promise<unknown>;
  checkout: (opts?: {
     customerNotes?: string;
  }) => Promise<unknown>;
  choose: (choices: CartChoices) => Promise<unknown>;
  current: unknown;
  ensure: () => Promise<string>;
  holders: () => Promise<unknown>;
  id: string | null;
  options: () => Promise<unknown>;
  quote: () => Promise<unknown>;
  refresh: () => Promise<unknown>;
  releaseSeat: (occurrenceId: string, seat: number) => Promise<unknown>;
  remove: (itemId: string) => Promise<unknown>;
  removeCode: (codeId: string) => Promise<unknown>;
  removeGiftCard: (giftCardId: string) => Promise<unknown>;
  reserveSeat: (occurrenceId: string, seat: number, ticketTypeId?: string) => Promise<unknown>;
  reserveSeats: (occurrenceId: string, seats: number[], ticketTypeId?: string) => Promise<unknown>;
  setHolders: (plan: CartHolderPlan) => Promise<unknown>;
  setSeatType: (occurrenceId: string, seat: number, ticketTypeId: string) => Promise<unknown>;
};

Defined in: core/liveClient.ts:204

add#

add: (item: CartItemInput) => Promise<unknown>;

Parameters

Parameter	Type
`item`	`CartItemInput`

Returns

Promise<unknown>

addGiftCard#

addGiftCard: (choice: GiftCardChoice) => Promise<unknown>;

Put a gift card in the cart (P9), making a cart if there is none; resolves with the cart, whose giftCards lists it. The quote counts gift cards under totals.giftCards.

Parameters

Parameter	Type
`choice`	`GiftCardChoice`

Returns

Promise<unknown>

applyCode#

applyCode: (code: string) => Promise<unknown>;

Apply a code, by the text the buyer typed, to the cart, making one if there is none. Its effects are the cart's and its order's; nothing is granted to the buyer, so a guest can use one. Resolves with the cart, whose codes lists it.

Parameters

Parameter	Type
`code`	`string`

Returns

Promise<unknown>

checkout#

checkout: (opts?: {
  customerNotes?: string;
}) => Promise<unknown>;

Parameters

Parameter	Type
`opts?`	{ `customerNotes?`: `string`; }
`opts.customerNotes?`	`string`

Returns

Promise<unknown>

choose#

choose: (choices: CartChoices) => Promise<unknown>;

Choose delivery and payment. cart:quoting goes out with the choices first, then cart:quoted with the re-priced quote, which this also resolves with. A method the cart is not offered is refused with 409 PAYMENT_METHOD_NOT_OFFERED; cart:quoted then carries the quote as it stood, so nothing waits on a price that is not coming.

Parameters

Parameter	Type
`choices`	`CartChoices`

Returns

Promise<unknown>

current#

readonly current: unknown;

ensure#

ensure: () => Promise<string>;

Returns

Promise<string>

holders#

holders: () => Promise<unknown>;

Who each unit is for (P8): the holders the cart makes ("Guest 1" until named), where each add-on goes (how: placed by the buyer, automatic or still unassigned) and, signed in, the buyer's holders from earlier bookings. Null when there is no cart.

Returns

Promise<unknown>

id#

readonly id: string | null;

options#

options: () => Promise<unknown>;

The delivery and payment methods the cart can choose, each with what choosing it adds to the total and why an unavailable one is not (TKT-655). Null when there is no cart.

Returns

Promise<unknown>

quote#

quote: () => Promise<unknown>;

The cart priced with the choices made so far: every fee with its kind and display, the totals and the headline. Published as cart:quoted. Null when there is no cart.

Returns

Promise<unknown>

refresh#

refresh: () => Promise<unknown>;

Returns

Promise<unknown>

releaseSeat#

releaseSeat: (occurrenceId: string, seat: number) => Promise<unknown>;

Give a held seat back.

Parameters

Parameter	Type
`occurrenceId`	`string`
`seat`	`number`

Returns

Promise<unknown>

remove#

remove: (itemId: string) => Promise<unknown>;

Parameters

Parameter	Type
`itemId`	`string`

Returns

Promise<unknown>

removeCode#

removeCode: (codeId: string) => Promise<unknown>;

Take a code off the cart by its codeId; resolves with the cart.

Parameters

Parameter	Type
`codeId`	`string`

Returns

Promise<unknown>

removeGiftCard#

removeGiftCard: (giftCardId: string) => Promise<unknown>;

Take a gift card out of the cart by its id (cgc_...); resolves with the cart.

Parameters

Parameter	Type
`giftCardId`	`string`

Returns

Promise<unknown>

reserveSeat#

reserveSeat: (occurrenceId: string, seat: number, ticketTypeId?: string) => Promise<unknown>;

Reserve one seat by its index (contract v1 6.1), on the category's default ticket type unless one is named. Resolves with the cart. A refusal rejects with SeatUnavailableError, SingleSeatGapError, PlanVersionChangedError or SeatLimitError, and is also announced on the bus (seats:unavailable, seats:gap, seats:plan-changed, seats:limit), so every seat element hears it.

Parameters

Parameter	Type
`occurrenceId`	`string`
`seat`	`number`
`ticketTypeId?`	`string`

Returns

Promise<unknown>

reserveSeats#

reserveSeats: (occurrenceId: string, seats: number[], ticketTypeId?: string) => Promise<unknown>;

Reserve several seats in one write, all or none (contract v1 6.1: one POST with every seat): a best available option, whose seats may fill a gap that reserving them one at a time would refuse as a single seat gap halfway. The refusals and the bus are reserveSeat's.

Parameters

Parameter	Type
`occurrenceId`	`string`
`seats`	`number`[]
`ticketTypeId?`	`string`

Returns

Promise<unknown>

setHolders#

setHolders: (plan: CartHolderPlan) => Promise<unknown>;

Name holders and place add-ons; resolves with the holders as saved. The surface refuses what checkout would (409 ADD_ON_HOLDER_MISMATCH, ADD_ON_LIMIT_REACHED, ADD_ON_PARENT_REQUIRED).

Parameters

Parameter	Type
`plan`	`CartHolderPlan`

Returns

Promise<unknown>

setSeatType#

setSeatType: (occurrenceId: string, seat: number, ticketTypeId: string) => Promise<unknown>;

Change a held seat's ticket type, keeping the reservation.

Parameters

Parameter	Type
`occurrenceId`	`string`
`seat`	`number`
`ticketTypeId`	`string`

Returns

Promise<unknown>

client#

readonly client: LiveClient;

Defined in: core/liveClient.ts:174

The underlying generated client (escape hatch for un-wrapped calls).

concierge#

readonly concierge: {
  send: (request: ConciergeRequest) => Promise<ConciergeResponse>;
};

Defined in: core/liveClient.ts:426

Live's Concierge routes (/v1/concierge/*), as a transport for tl-concierge: what to send is the element's, how it travels is this. Hand-written beside the generated client because a turn is a stream, and because the routes are Live's own rather than the sales projection the generator lifts.

send#

send: (request: ConciergeRequest) => Promise<ConciergeResponse>;

Parameters

Parameter	Type
`request`	`ConciergeRequest`

Returns

Promise<ConciergeResponse>

credit#

readonly credit: {
  activity: (storedValueAccountId: string, page?: {
     cursor?: string;
     limit?: number;
  }) => Promise<unknown>;
  mine: () => Promise<unknown>;
};

Defined in: core/liveClient.ts:297

The signed-in buyer's account credit (P9).

activity#

activity: (storedValueAccountId: string, page?: {
  cursor?: string;
  limit?: number;
}) => Promise<unknown>;

What has moved on one of those balances, newest first, a page at a time (GET /sales/my-credit/{id}/activity): { credit, movements, nextCursor }. Pass nextCursor back as cursor for the next page.

Parameters

Parameter	Type
`storedValueAccountId`	`string`
`page?`	{ `cursor?`: `string`; `limit?`: `number`; }
`page.cursor?`	`string`
`page.limit?`	`number`

Returns

Promise<unknown>

mine#

mine: () => Promise<unknown>;

Each open credit balance (GET /sales/my-credit); needs a signed-in buyer.

Returns

Promise<unknown>

events#

readonly events: {
  get: (eventId: string) => Promise<unknown>;
  list: () => Promise<unknown>;
};

Defined in: core/liveClient.ts:202

get#

get: (eventId: string) => Promise<unknown>;

Parameters

Parameter	Type
`eventId`	`string`

Returns

Promise<unknown>

list#

list: () => Promise<unknown>;

Returns

Promise<unknown>

giftCards#

readonly giftCards: {
  balance: (code: string) => Promise<unknown>;
  products: () => Promise<unknown>;
};

Defined in: core/liveClient.ts:287

Gift cards this organisation sells, and what is on one (P9). Neither needs a session.

balance#

balance: (code: string) => Promise<unknown>;

What is on a gift card, by its code. The code goes in the request body and nowhere else; the surface limits look-ups (429 past ten a minute).

Parameters

Parameter	Type
`code`	`string`

Returns

Promise<unknown>

products#

products: () => Promise<unknown>;

The gift cards on sale.

Returns

Promise<unknown>

orders#

readonly orders: {
  activateWristband: (orderId: string, slotId: string, uid: string) => Promise<unknown>;
  assignAddOn: (orderId: string, assignment: AddOnAssignment) => Promise<unknown>;
  get: (orderId: string) => Promise<unknown>;
  holder: (orderId: string, slotId: string) => Promise<unknown>;
  holderLink: (orderId: string, slotId: string) => Promise<unknown>;
  holders: (orderId: string) => Promise<unknown>;
  mine: () => Promise<unknown>;
  nameHolder: (orderId: string, slotId: string, input: HolderNameInput) => Promise<unknown>;
  requestRefund: (orderId: string, request: RefundRequestInput) => Promise<unknown>;
  ticketPdf: (orderId: string, passId: string) => Promise<Blob>;
  useHolderLink: (orderId: string, holderAccessToken: string) => Promise<void>;
};

Defined in: core/liveClient.ts:347

activateWristband#

activateWristband: (orderId: string, slotId: string, uid: string) => Promise<unknown>;

Activate the wristband posted to a holder, by the UID the phone read from it; resolves with the band's encoding once the surface says it scans. 409 WRISTBAND_ACTIVATION_MISMATCH for another band, WRISTBAND_NOT_AWAITING_ACTIVATION when none was posted to them.

Parameters

Parameter	Type
`orderId`	`string`
`slotId`	`string`
`uid`	`string`

Returns

Promise<unknown>

assignAddOn#

assignAddOn: (orderId: string, assignment: AddOnAssignment) => Promise<unknown>;

Put an add-on on a holder, or move it; resolves with the holders. 409 ADD_ON_HOLDER_MISMATCH, ADD_ON_LIMIT_REACHED, NOT_AN_ADD_ON, ENTITLEMENT_IN_USE or PASS_CHANGE_CLOSED when it cannot go.

Parameters

Parameter	Type
`orderId`	`string`
`assignment`	`AddOnAssignment`

Returns

Promise<unknown>

get#

get: (orderId: string) => Promise<unknown>;

Parameters

Parameter	Type
`orderId`	`string`

Returns

Promise<unknown>

holder#

holder: (orderId: string, slotId: string) => Promise<unknown>;

One holder of the booking, with their pass and add-ons: the booker for any of them, or a named guest for themselves through their own link (useHolderLink).

Parameters

Parameter	Type
`orderId`	`string`
`slotId`	`string`

Returns

Promise<unknown>

holderLink#

holderLink: (orderId: string, slotId: string) => Promise<unknown>;

Send to guest: the booker mints one holder's own link (backstage #251). Resolves with holderAccessToken, slotId, passId and expiresAt (30 days); with it that guest reads and names themselves and downloads their own pass, and nothing else. Booker only.

Parameters

Parameter	Type
`orderId`	`string`
`slotId`	`string`

Returns

Promise<unknown>

holders#

holders: (orderId: string) => Promise<unknown>;

Manage my booking (P8): the booking's holders with their passes and add-ons, and the add-ons still to place with the holders each can go to. Needs order access (the session's, since checkout or POST /session/order-access), as reading the order does.

Parameters

Parameter	Type
`orderId`	`string`

Returns

Promise<unknown>

mine#

mine: () => Promise<unknown>;

Returns

Promise<unknown>

nameHolder#

nameHolder: (orderId: string, slotId: string, input: HolderNameInput) => Promise<unknown>;

Name one of the booking's holders; resolves with the holders. Once the pass is issued the event's pass policy applies (409 PASS_FROZEN, PASS_CHANGE_NOT_ALLOWED, PASS_CHANGE_LIMIT_REACHED, PASS_CHANGE_CLOSED).

Parameters

Parameter	Type
`orderId`	`string`
`slotId`	`string`
`input`	`HolderNameInput`

Returns

Promise<unknown>

requestRefund#

requestRefund: (orderId: string, request: RefundRequestInput) => Promise<unknown>;

Ask for a refund or an exchange on an order, with where the money should go (refundTo); resolves with the request.

Parameters

Parameter	Type
`orderId`	`string`
`request`	`RefundRequestInput`

Returns

Promise<unknown>

ticketPdf#

ticketPdf: (orderId: string, passId: string) => Promise<Blob>;

Parameters

Parameter	Type
`orderId`	`string`
`passId`	`string`

Returns

Promise<Blob>

useHolderLink#

useHolderLink: (orderId: string, holderAccessToken: string) => Promise<void>;

Open a booking as the named guest whose link this page was given: the token goes with holder, nameHolder and ticketPdf for this order, and with nothing else. Starts the session those calls need.

Parameters

Parameter	Type
`orderId`	`string`
`holderAccessToken`	`string`

Returns

Promise<void>

payments#

readonly payments: {
  begin: (orderId: string, opts?: {
     paymentType?: string;
     returnUrl?: string;
  }) => Promise<unknown>;
};

Defined in: core/liveClient.ts:402

begin#

begin: (orderId: string, opts?: {
  paymentType?: string;
  returnUrl?: string;
}) => Promise<unknown>;

Parameters

Parameter	Type
`orderId`	`string`
`opts?`	{ `paymentType?`: `string`; `returnUrl?`: `string`; }
`opts.paymentType?`	`string`
`opts.returnUrl?`	`string`

Returns

Promise<unknown>

queue#

readonly queue: {
  join: () => Promise<unknown>;
  status: () => Promise<unknown>;
};

Defined in: core/liveClient.ts:405

join#

join: () => Promise<unknown>;

Returns

Promise<unknown>

status#

status: () => Promise<unknown>;

Returns

Promise<unknown>

tenders#

readonly tenders: {
  applyCredit: (storedValueAccountId: string) => Promise<TenderView>;
  applyGiftCard: (code: string) => Promise<TenderView>;
  clear: () => void;
  list: () => TenderView[];
  remove: (tenderId: string) => void;
  settle: (orderId: string) => Promise<TenderSettlement>;
};

Defined in: core/liveClient.ts:313

Account credit and gift cards applied at checkout and held until the order is paid (P9). tenders:changed carries the list whenever it moves. The order is paid by settle(orderId) first, then by card for what is still due (payments.begin). See core/tenders.ts.

applyCredit#

applyCredit: (storedValueAccountId: string) => Promise<TenderView>;

Hold one of the buyer's credit balances, by its id (sva_...).

Parameters

Parameter	Type
`storedValueAccountId`	`string`

Returns

Promise<TenderView>

applyGiftCard#

applyGiftCard: (code: string) => Promise<TenderView>;

Check a gift card's code and hold it. Refused when it cannot pay this cart.

Parameters

Parameter	Type
`code`	`string`

Returns

Promise<TenderView>

clear#

clear: () => void;

Returns

void

list#

list: () => TenderView[];

Returns

TenderView[]

remove#

remove: (tenderId: string) => void;

Let go of a held tender before paying. Nothing was spent.

Parameters

Parameter	Type
`tenderId`	`string`

Returns

void

settle#

settle: (orderId: string) => Promise<TenderSettlement>;

Spend what is held on the order, in the order applied; resolves with what was spent and what is still due for the card. Publishes tenders:settled.

Parameters

Parameter	Type
`orderId`	`string`

Returns

Promise<TenderSettlement>

theme#

readonly theme: {
  apply: () => Promise<unknown>;
  get: () => Promise<unknown>;
};

Defined in: core/liveClient.ts:203

apply#

apply: () => Promise<unknown>;

Returns

Promise<unknown>

get#

get: () => Promise<unknown>;

Returns

Promise<unknown>