Unofficial Luma SDK

Under construction — not ready for production use.

A TypeScript client for the Luma public API. Not affiliated with or maintained by Luma.

Note: You need a Luma Plus organization to use the API. See the Getting Started guide for setup and authentication.

Documentation: alhwyn.mintlify.site — install, authentication, API guides, webhooks, and CLI.

Install

bun add @alhwyn/luma

If npm returns a 404, install from GitHub instead (no token required):

bun add github:Alhwyn/luma

Both install as @alhwyn/luma in node_modules.

CLI (optional)

bun add @alhwyn/luma-cli

Setup

Get an API key from Luma API keys (Luma Plus required).

# add LUMA_API_KEY=your-key-here

Usage

import { Luma } from "@alhwyn/luma";

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

await luma.events.guests.add("evt-abc123", {
  guests: [
    { email: "[email protected]", name: "Jane Doe" },
  ],
});

Webhooks

Add to .env (see .env.example):

LUMA_WEBHOOK_SECRET=whsec_...
LUMA_WEBHOOK_EVENT_TYPES=guest.updated,guest.registered

Register an endpoint

import { Luma } from "@alhwyn/luma";

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

const endpoint = await luma.webhooks.create({
  url: "https://myapp.com/api/luma-webhook",
  event_types: ["guest.updated", "guest.registered"],
});

// Save endpoint.secret as LUMA_WEBHOOK_SECRET

event_types also reads from LUMA_WEBHOOK_EVENT_TYPES via webhookEventTypesFromEnv().

Verify incoming events

import { Luma } from "@alhwyn/luma";

const webhook = new Luma(process.env.LUMA_API_KEY!).webhooks.client({
  secret: process.env.LUMA_WEBHOOK_SECRET!,
});

// In your HTTP handler — pass the raw body, not re-serialized JSON
const event = webhook.verify({
  body: await req.text(),
  headers: req.headers,
});

Inbound-only handlers do not need an API key:

import { WebhookInboundClient } from "@alhwyn/luma";

const webhook = new WebhookInboundClient({
  secret: process.env.LUMA_WEBHOOK_SECRET!,
});

Handle an event

if (event.type === "guest.updated") {
  const checkedIn = event.data.event_tickets.some((t) => t.checked_in_at !== null);
  if (checkedIn) {
    // e.g. send welcome email to event.data.user_email
  }
}

Luma has no dedicated check-in webhook — check-in arrives as guest.updated with event_tickets[].checked_in_at set. See the Guest Updated docs.

CLI

After installing @alhwyn/luma-cli:

luma users get
luma events list
luma --help