SDK
@whocoming/sdk, a small typed client for the API, and @whocoming/react, the widget as a React component.
@whocoming/sdk
npm install @whocoming/sdkA thin TypeScript client for the REST API. No runtime dependencies, built on fetch, so it runs on Node 20 and later, Bun, Deno and edge runtimes. Fields are camelCase in your code and snake_case on the wire; the SDK converts both ways.
import { WhoComing } from "@whocoming/sdk";
const wc = new WhoComing(process.env.WHOCOMING_API_KEY);
const event = await wc.events.create({
title: "Friday Night Magic",
startsAt: "2027-01-08T18:30:00",
timezone: "America/Detroit",
capacity: 32,
});
const rsvp = await wc.rsvps.create(
event.id,
{ name: "Ada Lovelace", email: "ada@example.com", guests: 1 },
{ idempotencyKey: crypto.randomUUID() },
);
console.log(rsvp.status); // "going", or "waitlisted" when fullWith no argument, new WhoComing() reads WHOCOMING_API_KEY from the environment. The client refuses to start in a browser, because a secret key must stay on your server.
Resources
| Property | Methods |
|---|---|
wc.events | list, create, get, update, delete |
wc.series | list, create, get, update, end |
wc.rsvps | list(eventId), create(eventId, ...), get, update, delete, checkIn |
wc.webhookEndpoints | list, create, get, update, delete |
wc.webhookDeliveries | list, retry |
wc.guests | erase, export |
wc.usage | get |
wc.webhooks | verify |
wc.public | The no-key client, sharing this client's options |
Each maps to one endpoint in the API reference. A few names differ from the HTTP verb: series.end(id) is DELETE /v1/series/{id} (no more dates are made, future dates with no RSVPs are removed, and dates with RSVPs stay), and webhookEndpoints.get(id) never returns the signing secret, which create shows once.
Lists
Every list method can be awaited for one page, or iterated for every item across pages:
const { data, nextCursor } = await wc.events.list({ limit: 20 });
for await (const r of wc.rsvps.list("evt_demo0000000000000001", { status: "going" })) {
console.log(r.name, r.guests);
}
const everyone = await wc.rsvps.list("evt_demo0000000000000001").toArray();Awaiting gives { data, nextCursor }; pass nextCursor back as cursor for the next page, or let for await follow the cursors for you. .pages() iterates page by page. Nothing is requested until you await or iterate.
Retries and idempotency
The client retries 429, 5xx and network errors with backoff, twice by default, and honors Retry-After. Creating calls are only retried with an idempotency key; when you do not pass idempotencyKey, the SDK makes one per call so its own retries can never create a duplicate. Pass your own when you retry across process restarts.
const wc = new WhoComing(process.env.WHOCOMING_API_KEY, {
maxRetries: 3,
timeoutMs: 10_000,
});Errors
Failures throw WhoComingError, with the API's stable code, the HTTP status, the requestId and any field errors:
import { WhoComingError } from "@whocoming/sdk";
try {
await wc.rsvps.create(eventId, { name: "Ada Lovelace", email: "ada@example.com" });
} catch (error) {
if (error instanceof WhoComingError && error.code === "already_registered") {
// Already on the list.
} else {
throw error;
}
}The error classes, all exported from the package:
| Class | When | code |
|---|---|---|
WhoComingError | The API answered with an error | The API's code, such as capacity_reached |
WhoComingConnectionError | The request never got an answer | connection_error |
WhoComingTimeoutError | No answer within timeoutMs | timeout |
WebhookVerificationError | webhooks.verify cannot trust a request | none; see reason |
The first three are all WhoComingErrors, so one instanceof check catches them. code is typed as the known codes plus string, because the API may add codes: keep a default branch.
Verifying webhooks
const payload = await wc.webhooks.verify(rawBody, request.headers, process.env.WHOCOMING_WEBHOOK_SECRET);verify is async (it uses Web Crypto), so remember the await. It checks the signature and the timestamp (5 minutes either way by default; set toleranceSeconds), then returns the parsed, typed event. When the request cannot be trusted it rejects with WebhookVerificationError, whose reason says why; answer such a request with 400. Pass the raw body, not parsed JSON. The same check is exported as verifyWebhook(rawBody, headers, secret) for code that has no client. See webhooks.
Without a key
WhoComingPublic calls the public surface and is safe in the browser:
import { WhoComingPublic } from "@whocoming/sdk";
const pub = new WhoComingPublic();
const event = await pub.events.get("evt_demo0000000000000001");
console.log(event.counts.spotsLeft);
const sandbox = await pub.sandbox.create(); // a 24-hour test org, key and event| Property | Methods |
|---|---|
pub.events | get(id), calendar(id) (the .ics file as text) |
pub.rsvps | create(eventId, ...) (needs a Turnstile token when the event has one), get(manageToken), update(manageToken, ...) |
pub.orgs | listEvents(slug), paginated like the lists above |
pub.sandbox | create() |
pub.rsvps.create accepts idempotencyKey and is only retried when you pass one.
@whocoming/react
npm install @whocoming/reactThe widget as a React component, with typed props and callbacks:
"use client";
import { WhoComingRsvp } from "@whocoming/react";
export function Rsvp() {
return (
<WhoComingRsvp
event="evt_demo0000000000000001"
theme="auto"
accent="#3451f5"
onReady={(detail) => console.log("ready", detail.state)}
onRsvp={(detail) => console.log("RSVP", detail.rsvpId, detail.status)}
onError={(detail) => console.log("error", detail.code)}
/>
);
}Props mirror the element's attributes in camelCase (hideCount, apiBase, source, noJsonld), and the callbacks receive the detail of its DOM events, also in camelCase (rsvpId, eventId). Style it with the same CSS variables and parts.
Two props are for special cases:
source: where the RSVP is recorded as coming from, shown as the RSVP'ssource. Leave it out on your own site (embed); WhoComing's hosted pages set"page".noJsonld: the page already has Event structured data for this event, so the widget should not add its own. Search engines then see one Event, not two.
<WhoComingRsvp event="evt_demo0000000000000001" noJsonld />We do not ship SDKs per framework. Vue, Svelte, Angular and the rest use the element directly; see other frameworks.