tickethead-sdk/README.md

SDK for the Tickethead API

# Tickethead SDK

SDK library for the **[Tickethead API](https://readthedocs.tickethead.io/)**.

## Installation

`npm i tickethead-sdk`

## Usage

### Create the main service object:

```ts
import { SDK } from  'tickethead-sdk';

// Production API by default

// For development, use new SDK('https://api.staging.tickethead.io');
const sdk = new SDK();

// Set the appropriate organizer name
// NOTE: This is not needed for `sdk.account` and `sdk.auth` calls
await sdk.useOrganizer('tickethead');

// List all events with ticket configurations and occurrences
const events =  await sdk.event
.listEvents({
	with: {
		ticket_config:  true,
		occurrence:  true
	}
});

// Get single event with all details (occurrences, timeslot, ticket configurations, discounts, ...)
const singleEvent =  await sdk.event.getEvent({ id:  1234 })

// Create an order with 3 tickets
await sdk.order.createOrder({
	format:  'PDF',
	orderItem: [{
		quantity:  3,
		ticketConfigId:  12345
	}]
});

```

### Caching

Caching options can be provided when initializing the SDK. The full list of options is available at https://axios-cache-interceptor.js.org/config
Below is a simple example of how to enable caching for the SDK with the time to live of 5 minutes. By default there is no caching.

```ts
import { SDK, BaseUrl } from  'tickethead-sdk';

const sdk = await SDK.build({
	baseUrl: BaseUrl.ThStaging,
	cache:{
		ttl: 5 * 60 * 1000, // 5 minutes caching time
	}
})
```

### Retries

Requests are retried 3 times by default. You can change the number of retries and the time to wait between retries by providing the `retry` option.
The full list of options is available at https://www.npmjs.com/package/axios-retry

```ts
import { SDK, BaseUrl } from  'tickethead-sdk';

const sdk = await SDK.build({
	baseUrl: BaseUrl.ThStaging,
	retry: {
		retries: 5,
	}
})
```

### Saving and loading the state

It is possible to save the state of the SDK and load it later.
For example, when using the SDK in the browser, you could put the serialized state in the local storage and load it when the page is reloaded.

```ts
import { SDK, BaseUrl } from  'tickethead-sdk';

const sdk = await SDK.build({
	baseUrl: BaseUrl.ThStaging,
})
// Do some operations with the SDK, set the authorization etc.

// Save the state
const state = sdk.serialize()

// Load the state
const sdk2 = await SDK.build(state)
```

### Validators/Check-in application

How to initialize the SDK for a validator application:
First, if you have the payload from the QR code, you can extract the required data from it.

```ts
import { extractAccessDataFromValidatorQrCode } from  'tickethead-sdk';

const qrCodeContent =
	'{"url":"https://api.staging.tickethead.io/account/v1/organizer/validator/c0ffeef2-b836-4a0f-9555-eeb99c9c99fd","organizer":"dnd"}'
const data = extractAccessDataFromValidatorQrCode(qrCodeContent)
```

```ts
import { SDK, WalletCredentials } from  'tickethead-sdk';

// This is a part of the validator data you get in the QR code when you go to the Dashboard/Assign validator on an event
// Or you can extract it from the QR code content, as shown above
const accessToken = 'c0ffeef2-b836-4a0f-9555-eeb99c9c99fd'
const baseUrl = 'https://api.staging.tickethead.io' // Or simply BaseUrl.EnvironmentName, ie. BaseUrl.ThStaging

// Initialize the SDK
const sdk = await SDK.build({
	baseUrl,
})

const validator = await sdk.validator.getValidatorByToken({
	token: accessToken,
})
const credentials = new WalletCredentials(validator.wallet)

// After this, the SDK is ready to be used for privileged calls
await sdk.authorize(credentials, validator.organizer)
```

After you fetch the credentials and initialize the SDK, you can fetch the QR codes for the tickets:
```ts
// initialize the SDK before this
const ticketList = await sdk.event.getQrCodes({
	organizer_id: validator.organizer,
	id: validator.eventId,
})

// Tickets are grouped by categories and have a sub-object with their QR code content
const ticketQrCodes = ticketList
	.flatMap((ticketCategory) => ticketCategory.ticket)
	.map((ticket) => ticket.ticketQrCode.content)
```

## Authentication

Tickethead API uses JWT based authentication and authorization. The `account/v1/auth/login` is used for users (or services) with credentials, i.e. username and password. 

Tickethead SDK uses a global method for any type of authentication with `authorize`. After calling this method, the internal HTTP client updates the authorization headers and successive calls will use the resolved JWT from SDK's API.

```ts
import { SDK } from  'tickethead-sdk';
const sdk = new SDK();

// Authorize with username and password
// Permissions are based on the account and are loaded into the instance
await sdk.authorize({ username: 'admin', password: 'S3cr3t123' });

// Log in as guest user with a short-living guest JWT
await sdk.authorize();
```

## Reference

The SDK instance contains all properties and methods for authorization, users, events, orders and tickets.

### Constructor

Create a new SDK instance.

```ts
new SDK(url: 'http://api.tickethead.io', version: 'v1')
```
or
```ts
await SDK.build({baseUrl: 'http://api.tickethead.io', version: 'v1' }) // Other options are available
```

### Properties

| Property       | Description                                |
| -------------- | ------------------------------------------ |
| **account**    | User, organizer and account management     |
| **auth**       | Authorization endpoints                    |
| **blockchain** | Wallet signing operations                  |
| **event**      | Event management                           |
| **order**      | Order, order contact and ticket management |
| **payment**    | Payment providers operations               |
| **venue**      | Venue information and search               |

## License

ISC