> ## Documentation Index
> Fetch the complete documentation index at: https://alhwyn.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Client

> Initialize the Luma TypeScript SDK client with your API key and explore shared types, resource properties, and method conventions used across endpoints.

The `Luma` class is the entry point for the unofficial SDK. Pass your API key once, then call typed methods on resource properties.

## Quick start

```typescript theme={null}
import { Luma } from "@alhwyn/luma";

const luma = new Luma(process.env.LUMA_API_KEY!);

const user = await luma.users.get();
const { data: events } = await luma.events.list({ pagination_limit: 10 });
```

If you have not verified your API key yet, start with [Test your setup](/test-your-setup).

## Constructor

<Badge color="purple">SDK</Badge> `new Luma(apiKey, options?): Luma`

Creates a `Luma` client for calling the API.

<RequestExample>
  ```typescript Example theme={null}
  import { Luma } from "@alhwyn/luma";

  const luma = new Luma(process.env.LUMA_API_KEY!, {
    baseUrl: "https://public-api.luma.com",
    fetch: customFetch,
  });
  ```
</RequestExample>

<ResponseExample>
  ```typescript Response theme={null}
  // Returns a Luma client with luma.users, luma.calendar,
  // luma.events, and luma.webhooks resource properties.
  const luma: Luma;
  ```
</ResponseExample>

### Parameters

<ParamField path="apiKey" type="string" required>
  Your Luma API key. Sent as the `x-luma-api-key` header on every request.
</ParamField>

<ParamField path="options" type="ClientOptions">
  Optional client configuration.

  <Expandable title="ClientOptions properties">
    <ParamField path="baseUrl" type="string" default="https://public-api.luma.com">
      API base URL. Override for testing or proxies.
    </ParamField>

    <ParamField path="fetch" type="typeof fetch" default="global fetch">
      Custom fetch implementation. Useful for mocking in tests.
    </ParamField>
  </Expandable>
</ParamField>

## Resources

The client groups methods by resource:

| Property                  | Methods                                                           | Guide                               |
| ------------------------- | ----------------------------------------------------------------- | ----------------------------------- |
| `luma.users`              | `get()`                                                           | [Users](/users/get)                 |
| `luma.calendar`           | `get()`, `update()`                                               | [Calendar](/calendar/get)           |
| `luma.events`             | `get()`, `list()`, `create()`, `update()`                         | [Events](/events/list)              |
| `luma.events.guests`      | `list()`, `get()`, `add()`, `sendInvites()`, `updateStatus()`     | [Events](/events/guests/list)       |
| `luma.events.ticketTypes` | `list()`, `get()`, `create()`, `update()`, `delete()`             | [Events](/events/ticket-types/list) |
| `luma.webhooks`           | `create()`, `get()`, `list()`, `update()`, `delete()`, `client()` | [Webhooks](/webhooks/create)        |

## List responses

List methods return a normalized paginated shape:

```typescript theme={null}
interface ListResponse<T> {
  data: T[];
  hasMore: boolean;
  nextCursor: string | null;
}
```

```typescript theme={null}
const page = await luma.events.list({ pagination_limit: 20 });

page.data;        // items for this page
page.hasMore;     // more pages available?
page.nextCursor;  // pass as pagination_cursor for the next page
```

See [Events — pagination](/events/list#pagination) for fetching the next page.

## TypeScript types

Entity and param types are exported from the package:

```typescript theme={null}
import type {
  User,
  Calendar,
  Event,
  Guest,
  Webhook,
  WebhookEvent,
  ClientOptions,
  ListResponse,
} from "@alhwyn/luma";
```

For field-level details on request bodies, see the [official Luma API docs](https://docs.luma.com).