bam-ticketing-sdk/README.md

SDK for B.A.M Ticketing API

# BAM Ticketing SDK

SDK library for **[B.A.M Ticketing API](https://readthedocs.bam.fan/)**.

## Installation

`npm i bam-ticketing-sdk`

## Usage

### Create the main service object:

```ts
import { BAM } from  'bam-ticketing-sdk';

// Production API by default

// For development, use new BAM('https://develop.bam.fan');
const bam = new BAM();

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

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

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

// Create an order with 3 tickets
await bam.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 { BAM, BaseUrl } from  'bam-ticketing-sdk';

const sdk = await BAM.build({
	baseUrl: BaseUrl.Dev,
	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 { BAM, BaseUrl } from  'bam-ticketing-sdk';

const sdk = await BAM.build({
	baseUrl: BaseUrl.Dev,
	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 { BAM, BaseUrl } from  'bam-ticketing-sdk';

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

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

// Load the state
const sdk2 = await BAM.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  'bam-ticketing-sdk';

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

```ts
import { BAM, WalletCredentials } from  'bam-ticketing-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://develop.bam.fan' // Or simply BaseUrl.EnvironmentName, ie. BaseUrl.Dev

// Initialize the SDK
const sdk = await BAM.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

BAM Ticketing 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. 

BAM 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 BAM's API.

```ts
import { BAM } from  'bam-ticketing-sdk';
const bam = new BAM();

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

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

## Reference

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

### Constructor

Create a new BAM instance.

```ts
new BAM(url: 'http://api.bam.fan', version: 'v1')
```
or
```ts
await BAM.build({baseUrl: 'http://api.bam.fan', 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