Luma API Event Calendar Webhooks

A TypeScript client for the Luma public API with first-class support for events, calendars, memberships, images, entities, and webhooks. Responses are validated with Zod, and webhook payloads can be parsed and narrowed safely with discriminated unions.

Features

• Typed Luma API client with resource-based methods
• Zod-validated responses and exportable schemas
• Webhook configuration + payload parsing for incoming events
• Built-in error classes with rate limit handling
• Debug hook for request/response logging
• ESM + CJS builds with TypeScript types

Requirements

• Luma Plus subscription (required by Luma API)
• A Luma API key from your Luma dashboard
• Node.js >= 22
• zod installed in your project (peer dependency)

See Luma docs: https://docs.luma.com/reference/getting-started-with-your-api

Install

pnpm add luma-api-event-calendar-webhooks zod

npm install luma-api-event-calendar-webhooks zod

yarn add luma-api-event-calendar-webhooks zod

Quick Start

import { LumaClient } from 'luma-api-event-calendar-webhooks'

const apiKey = process.env.LUMA_API_KEY
if (!apiKey) {
  throw new Error('LUMA_API_KEY environment variable is required')
}

const client = new LumaClient({ apiKey })

const me = await client.user.getSelf()
const event = await client.event.get({ event_api_id: 'evt_123' })

console.log(me.user.email)
console.log(event.event.name)

Configuration

import { LumaClient, BASE_URL } from 'luma-api-event-calendar-webhooks'

const apiKey = process.env.LUMA_API_KEY
if (!apiKey) {
  throw new Error('LUMA_API_KEY environment variable is required')
}

const client = new LumaClient({
  apiKey,
  baseUrl: BASE_URL, // default: https://public-api.luma.com
  timeout: 30_000, // default: 30000 ms
})

Authentication uses the x-luma-api-key header. Luma docs include a simple curl example: https://docs.luma.com/reference/getting-started-with-your-api

Debug Hook

Add a debug callback to log all requests and responses for debugging:

import { LumaClient, type DebugContext } from 'luma-api-event-calendar-webhooks'

const client = new LumaClient({
  apiKey: process.env.LUMA_API_KEY!,
  debug: (ctx: DebugContext) => {
    console.log(`${ctx.request.method} ${ctx.request.url} [${ctx.durationMs}ms]`)

    if (ctx.outcome.type === 'success') {
      console.log(`Status: ${ctx.outcome.response.status}`)
    } else {
      console.log(`Error: ${ctx.outcome.error.message}`)
    }
  },
})

The debug hook is called after each request completes with:

• request: Method, URL, headers, and body (for POST/PUT/PATCH)
• outcome: Either { type: 'success', response } with status/headers/body, or { type: 'error', error } for network failures
• durationMs: Request duration in milliseconds

Resources

All methods are thin wrappers around the Luma REST endpoints. Request/response types are exported and validated.

• client.user
  • getSelf()
• client.event
  • get, create, update
  • getGuest, getGuests, updateGuestStatus
  • sendInvites, addGuests, addHost
  • getCoupons, createCoupon, updateCoupon
  • listTicketTypes, getTicketType, createTicketType, updateTicketType, deleteTicketType
• client.calendar
  • listEvents, lookupEvent, listPeople, listPersonTags
  • listCoupons, createCoupon, updateCoupon
  • importPeople, createPersonTag, updatePersonTag, deletePersonTag
  • addEvent, applyPersonTag, removePersonTag
• client.membership
  • listTiers, addMemberToTier, updateMemberStatus
• client.webhook
  • list, get, create, update, delete
• client.entity
  • lookup
• client.images
  • createUploadUrl

For full request/response shapes, use the exported schemas and types.

Using Types and Schemas

Types are exported via resource namespaces for clean imports:

import { Event, Calendar, Webhook } from 'luma-api-event-calendar-webhooks'

// Use types from namespaces
type MyEvent = Event.Event
type MyGuest = Event.Guest
type CalendarEntry = Calendar.CalendarEventEntry

// Webhook namespace includes the parseWebhookPayload utility
const payload = Webhook.parseWebhookPayload(requestBody)

For Zod schemas, use the Schemas namespace:

import { Schemas } from 'luma-api-event-calendar-webhooks'

const parsed = Schemas.GetEventResponseSchema.parse(apiResponse)

Webhook Payload Parsing

Incoming webhook payloads can be validated and narrowed by type.

import { Webhook } from 'luma-api-event-calendar-webhooks'

const payload = Webhook.parseWebhookPayload(requestBody)

switch (payload.type) {
  case 'event.created':
    console.log(payload.data.event.api_id)
    break
  case 'guest.registered':
    console.log(payload.data.guest.email)
    break
  default:
    // Exhaustive check is enforced by TypeScript
    break
}

Supported webhook types include:

• event.created
• event.updated
• guest.registered
• guest.updated
• ticket.registered
• calendar.event.added
• calendar.person.subscribed

Pagination

List endpoints accept cursor and limit. The client automatically maps them to Luma's pagination_cursor and pagination_limit query params.

const page = await client.calendar.listEvents({
  limit: 50,
  cursor: 'next-page-token',
})

if (page.has_more) {
  console.log(page.next_cursor)
}

Error Handling

Requests throw typed errors that you can handle in a single place.

import {
  LumaClient,
  LumaRateLimitError,
  LumaAuthenticationError,
  LumaValidationError,
} from 'luma-api-event-calendar-webhooks'

const client = new LumaClient({ apiKey: '...' })

try {
  await client.user.getSelf()
} catch (error) {
  if (error instanceof LumaRateLimitError) {
    console.error('Rate limited, retry after:', error.retryAfter)
  } else if (error instanceof LumaAuthenticationError) {
    console.error('Invalid API key')
  } else if (error instanceof LumaValidationError) {
    console.error('Response schema mismatch:', error.issues)
  } else {
    throw error
  }
}

The LumaRateLimitError uses the response Retry-After header (seconds or HTTP-date). You can also use parseRetryAfter directly if needed.

Rate Limits

Per Luma docs:

• GET endpoints: 500 requests per 5 minutes per calendar
• POST endpoints: 100 requests per 5 minutes per calendar (separate from GET limit)
• Block duration: 1 minute when the limit is exceeded (HTTP 429)

See: https://docs.luma.com/reference/rate-limits

Development

pnpm install
pnpm format
pnpm build
pnpm test
npx publint --pack npm

License

MIT