@themoonlitcompany/mbevents 0.1.0

package/README.md

@@ -0,0 +1,94 @@
+# @themoonlitcompany/mbevents
+
+Client SDK for [Momentum Events](../application), a white-label RSVP engine. The
+backend workflow is prebuilt; this package gives your front end ready-made
+tools to talk to it. Zero dependencies, works in the browser and Node.
+
+## Install
+
+```sh
+npm install @themoonlitcompany/mbevents
+```
+
+## Quick start
+
+Every Momentum event has a slug and a public event key (find both on the
+event's API tab in the console). The key only grants reading the published
+event and submitting RSVPs, so it is safe in browser code.
+
+```ts
+import { createEventClient } from "@themoonlitcompany/mbevents";
+
+const client = createEventClient({
+  baseUrl: "https://your-momentum-deployment.com",
+  slug: "spring-launch-dinner",
+  eventKey: "me_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+});
+
+// 1. Read the event and its question definitions
+const event = await client.getEvent();
+
+// 2. Submit an RSVP (idempotency key is generated for you)
+const result = await client.accept({
+  email: "guest@example.com",
+  fullName: "Guest Name",
+  partySize: 2,
+  answers: { meal_preference: "Vegetarian" },
+});
+
+console.log(result); // { rsvpId: "...", status: "accepted", deduped: false }
+```
+
+## Tools included
+
+| Tool | What it does |
+| --- | --- |
+| `client.getEvent()` | Fetches the published event with questions |
+| `client.submitRsvp(input)` | Submits or updates an RSVP (any status) |
+| `client.accept(input)` / `client.decline(input)` | Status shorthands |
+| `toFormFields(event)` | Flattens built-in fields + questions into an ordered, renderable field list |
+| `validateAnswers(event, answers)` | Client-side validation mirroring the server, for instant feedback |
+| `isRsvpClosed(event)` | Whether the RSVP deadline has passed |
+| `MomentumError` | Thrown on API errors; carries `.status` and a human-readable message |
+
+## Rendering a form from the event definition
+
+```ts
+import { createEventClient, toFormFields, validateAnswers } from "@themoonlitcompany/mbevents";
+
+const client = createEventClient({ baseUrl, slug, eventKey });
+const event = await client.getEvent();
+
+// Drive your markup from the definition; it stays in sync with the console.
+for (const field of toFormFields(event)) {
+  renderInput(field); // your UI, your brand
+}
+
+// Validate before submitting
+const errors = validateAnswers(event, collectedAnswers);
+if (Object.keys(errors).length === 0) {
+  await client.accept({ email, fullName, answers: collectedAnswers });
+}
+```
+
+## Error handling
+
+```ts
+import { MomentumError } from "@themoonlitcompany/mbevents";
+
+try {
+  await client.accept({ email, fullName });
+} catch (error) {
+  if (error instanceof MomentumError) {
+    // Server messages are written to be shown to guests,
+    // e.g. "This event is at capacity." or "Meal preference is required."
+    showMessage(error.message);
+  }
+}
+```
+
+## What the engine enforces server-side
+
+Required questions, capacity, party-size limits, RSVP deadlines, one response
+per email (repeat submissions update the existing RSVP), and idempotent
+retries. Your front end never reimplements the workflow.

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Momentum Events client SDK.
+ *
+ * Wraps the two public endpoints every Momentum event exposes:
+ *
+ *   GET  {baseUrl}/api/public/events/{slug}        -> event details + questions
+ *   POST {baseUrl}/api/public/events/{slug}/rsvps  -> submit an RSVP
+ *
+ * The event key (`me_...`) only grants access to published event details and
+ * RSVP submission, so it is safe to use in browser code.
+ */
+export type QuestionType = "text" | "textarea" | "select" | "boolean";
+export type EventQuestion = {
+    key: string;
+    label: string;
+    type: QuestionType;
+    required: boolean;
+    options: string[];
+};
+export type MomentumEvent = {
+    title: string;
+    slug: string;
+    description: string | null;
+    location: string | null;
+    startsAt: string | null;
+    endsAt: string | null;
+    capacity: number | null;
+    rsvpDeadline: string | null;
+    allowPlusOnes: boolean;
+    maxPartySize: number;
+    confirmationEmailEnabled: boolean;
+    questions: EventQuestion[];
+};
+export type RsvpStatus = "accepted" | "declined" | "waitlisted";
+export type AnswerValue = string | number | boolean | null;
+export type RsvpInput = {
+    email: string;
+    fullName: string;
+    status?: RsvpStatus;
+    partySize?: number;
+    answers?: Record<string, AnswerValue>;
+    /** Provide your own to dedupe retries; one is generated when omitted. */
+    idempotencyKey?: string;
+};
+export type RsvpResult = {
+    rsvpId: string;
+    status: RsvpStatus;
+    /** True when the server matched a previous submission by idempotency key. */
+    deduped: boolean;
+};
+/** A renderable field description: the built-in fields plus custom questions. */
+export type FormField = {
+    key: string;
+    label: string;
+    kind: "builtin" | "question";
+    type: QuestionType | "email" | "number";
+    required: boolean;
+    options: string[];
+};
+export declare class MomentumError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export type ClientConfig = {
+    /** Origin of the Momentum deployment, e.g. "https://events.example.com". */
+    baseUrl: string;
+    /** The event's URL slug. */
+    slug: string;
+    /** The event's public key (starts with "me_"). */
+    eventKey: string;
+    /** Custom fetch implementation; defaults to globalThis.fetch. */
+    fetch?: typeof globalThis.fetch;
+};
+export type EventClient = {
+    /** Fetch the published event with its question definitions. */
+    getEvent: () => Promise<MomentumEvent>;
+    /** Submit or update an RSVP. Defaults to status "accepted", party of 1. */
+    submitRsvp: (input: RsvpInput) => Promise<RsvpResult>;
+    /** Shorthand for submitRsvp with status "accepted". */
+    accept: (input: Omit<RsvpInput, "status">) => Promise<RsvpResult>;
+    /** Shorthand for submitRsvp with status "declined". */
+    decline: (input: Omit<RsvpInput, "status">) => Promise<RsvpResult>;
+};
+export declare function createEventClient(config: ClientConfig): EventClient;
+/**
+ * Validate answers against the event's question definitions before
+ * submitting. Returns a map of question key to error message; empty when
+ * everything passes. Mirrors the server's validation so users get instant
+ * feedback instead of a round trip.
+ */
+export declare function validateAnswers(event: MomentumEvent, answers: Record<string, AnswerValue>): Record<string, string>;
+/**
+ * Flatten an event into an ordered list of renderable form fields: the
+ * built-in fields (name, email, party size when plus-ones are allowed)
+ * followed by the event's custom questions. Drive your form markup from this
+ * and it stays in sync with the console automatically.
+ */
+export declare function toFormFields(event: MomentumEvent): FormField[];
+/** True when the event's RSVP deadline has passed. */
+export declare function isRsvpClosed(event: MomentumEvent, now?: Date): boolean;

package/dist/index.js

@@ -0,0 +1,155 @@
+/**
+ * Momentum Events client SDK.
+ *
+ * Wraps the two public endpoints every Momentum event exposes:
+ *
+ *   GET  {baseUrl}/api/public/events/{slug}        -> event details + questions
+ *   POST {baseUrl}/api/public/events/{slug}/rsvps  -> submit an RSVP
+ *
+ * The event key (`me_...`) only grants access to published event details and
+ * RSVP submission, so it is safe to use in browser code.
+ */
+export class MomentumError extends Error {
+    constructor(message, status) {
+        super(message);
+        this.name = "MomentumError";
+        this.status = status;
+    }
+}
+export function createEventClient(config) {
+    const { slug, eventKey } = config;
+    const baseUrl = config.baseUrl.replace(/\/+$/, "");
+    const doFetch = config.fetch ?? globalThis.fetch.bind(globalThis);
+    const endpoint = `${baseUrl}/api/public/events/${encodeURIComponent(slug)}`;
+    async function parse(response, pick) {
+        const body = (await response.json().catch(() => null));
+        if (!response.ok) {
+            const message = body && typeof body.error === "string"
+                ? body.error
+                : `Request failed with status ${response.status}.`;
+            throw new MomentumError(message, response.status);
+        }
+        return (body?.[pick] ?? body);
+    }
+    const getEvent = async () => {
+        const response = await doFetch(endpoint, {
+            headers: { "x-momentum-public-key": eventKey },
+        });
+        return await parse(response, "event");
+    };
+    const submitRsvp = async (input) => {
+        const response = await doFetch(`${endpoint}/rsvps`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                publicKey: eventKey,
+                email: input.email,
+                fullName: input.fullName,
+                status: input.status ?? "accepted",
+                partySize: input.partySize ?? 1,
+                answers: input.answers ?? {},
+                idempotencyKey: input.idempotencyKey ?? generateIdempotencyKey(),
+            }),
+        });
+        return await parse(response, "rsvp");
+    };
+    return {
+        getEvent,
+        submitRsvp,
+        accept: (input) => submitRsvp({ ...input, status: "accepted" }),
+        decline: (input) => submitRsvp({ ...input, status: "declined" }),
+    };
+}
+function generateIdempotencyKey() {
+    const cryptoApi = globalThis.crypto;
+    if (cryptoApi && "randomUUID" in cryptoApi) {
+        return cryptoApi.randomUUID();
+    }
+    return `mk_${Date.now()}_${Math.random().toString(36).slice(2, 12)}`;
+}
+/**
+ * Validate answers against the event's question definitions before
+ * submitting. Returns a map of question key to error message; empty when
+ * everything passes. Mirrors the server's validation so users get instant
+ * feedback instead of a round trip.
+ */
+export function validateAnswers(event, answers) {
+    const errors = {};
+    for (const question of event.questions) {
+        const value = answers[question.key];
+        const empty = value === undefined || value === null || value === "";
+        if (question.required && empty) {
+            errors[question.key] = `${question.label} is required.`;
+            continue;
+        }
+        if (empty) {
+            continue;
+        }
+        if (question.type === "select" &&
+            typeof value === "string" &&
+            question.options.length > 0 &&
+            !question.options.includes(value)) {
+            errors[question.key] =
+                `${question.label} must be one of: ${question.options.join(", ")}.`;
+        }
+        if (question.type === "boolean" && typeof value !== "boolean") {
+            errors[question.key] = `${question.label} must be true or false.`;
+        }
+    }
+    return errors;
+}
+/**
+ * Flatten an event into an ordered list of renderable form fields: the
+ * built-in fields (name, email, party size when plus-ones are allowed)
+ * followed by the event's custom questions. Drive your form markup from this
+ * and it stays in sync with the console automatically.
+ */
+export function toFormFields(event) {
+    const fields = [
+        {
+            key: "fullName",
+            label: "Full name",
+            kind: "builtin",
+            type: "text",
+            required: true,
+            options: [],
+        },
+        {
+            key: "email",
+            label: "Email",
+            kind: "builtin",
+            type: "email",
+            required: true,
+            options: [],
+        },
+    ];
+    if (event.allowPlusOnes && event.maxPartySize > 1) {
+        fields.push({
+            key: "partySize",
+            label: `Party size (up to ${event.maxPartySize})`,
+            kind: "builtin",
+            type: "number",
+            required: true,
+            options: [],
+        });
+    }
+    for (const question of event.questions) {
+        fields.push({
+            key: question.key,
+            label: question.label,
+            kind: "question",
+            type: question.type,
+            required: question.required,
+            options: question.options,
+        });
+    }
+    return fields;
+}
+/** True when the event's RSVP deadline has passed. */
+export function isRsvpClosed(event, now = new Date()) {
+    if (!event.rsvpDeadline) {
+        return false;
+    }
+    const deadline = Date.parse(event.rsvpDeadline);
+    return !Number.isNaN(deadline) && now.getTime() > deadline;
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@themoonlitcompany/mbevents",
+  "version": "0.1.0",
+  "description": "Client SDK for Momentum Events: a white-label RSVP engine. Read events, render your own form, submit RSVPs.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "rsvp",
+    "events",
+    "momentum",
+    "white-label",
+    "backend-as-a-service"
+  ],
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  }
+}