SDK reference

The SeatBuilder browser SDK renders an interactive seat map inside your page and manages seat selection and holds against the SeatBuilder API. You embed it by calling SeatBuilder.render(config), which returns a ChartInstance you can drive imperatively. The SDK authenticates with your public key (pk_live_… / pk_test_…) — the browser render credential — so it is safe to ship in client code.

This page is the canonical, hand-authored reference. The full auto-generated type reference is linked at the bottom.

Configuration (SdkConfig)

Pass a single config object to SeatBuilder.render(). Every field below is transcribed from packages/sdk/src/types.ts.

Localization (language and messages)

Every built-in string the SDK renders — status-legend labels, seat/GA tooltips, the GA "N left" / "Sold out" text, the hold-warning, hold-expired, and connection-lost banners, and the GA quantity picker — is drawn from a typed string catalog. Set language to pick a shipped catalog, and/or pass messages to override individual keys:

SeatBuilder.render({
  container: '#chart',
  apiUrl: 'https://seatbuilder.org',
  publicKey: 'pk_live_…',
  eventKey: 'my-event',
  language: 'vi',
  messages: { sold: 'Đã bán' },
});

Resolution is per-key: an override wins over the language catalog, which wins over the en fallback. A missing or blank value can never reach the DOM — an unresolved key always falls back to en. The SdkMessages type is re-exported from @seatbuilder/sdk if you want to author a complete standalone catalog.

A note on holdDurationSeconds and the hold TTL

holdDurationSeconds is the single client-side control over the browse-hold lifetime. When set, it is sent as ttlSeconds on the initial POST /hold. When you omit it, the field is absent from the request body and the server default of 900 seconds applies. There is no separate silent client default, and 300 (seen in some examples) is only an illustrative shorter value, not a built-in default.

Callbacks

All callbacks are optional and passed alongside the config fields above (SdkConfig extends SdkCallbacks).

Chart instance (ChartInstance)

SeatBuilder.render() returns a ChartInstance for imperative control:

The holdToken is the link between the browser session and your server: pass it to the backend extend / book / release endpoints to confirm or free the buyer's seats.

Worked example

Render a chart with the public key and read back the session hold token:

import SeatBuilder from '@seatbuilder/sdk';

const chart = SeatBuilder.render({
  publicKey: 'pk_live_xxx',
  eventKey: 'evt_summer_gala',
  container: '#seatmap',
  apiUrl: 'https://seatbuilder.org',
  onObjectSelected: ({ objectLabel, categoryKey }) => {
    console.log(`selected ${objectLabel} (${categoryKey})`);
  },
});

// Hand this token to your backend to book or release the held seats.
async function checkout() {
  await fetch('/api/checkout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ holdToken: chart.holdToken }),
  });
}

A minimal render with a selection cap and shorter browse hold:

import SeatBuilder from '@seatbuilder/sdk';

const chart = SeatBuilder.render({
  publicKey: 'pk_live_xxx',
  eventKey: 'evt_summer_gala',
  container: '#seatmap',
  apiUrl: 'https://seatbuilder.org',
  maxSelectedObjects: { total: 6, perCategory: { vip: 2 } },
  holdDurationSeconds: 300,
});

Full generated reference

Every exported symbol is also documented in the auto-generated TypeDoc tree:

• All modules — the generated entry page.
• sdk/src — the main SDK module (SdkConfig, ChartInstance, event payloads).
• sdk/src/types — flattened type aliases.
• shared/src/chart-schema — the ChartData family consumed by SeatBuilder.render.