@semics-tech/emdash-events-suite 0.0.0-bootstrap.0 → 1.0.0-rc.0

package/src/astro/lib/form.ts

@@ -0,0 +1,190 @@
+/**
+ * The booking form of `<BookingWithWaiver>` (SX-FR-02): the buyer, then one row per attendee
+ * (ticket type, name, optional email, "under 18"). Read and checked here before anything is
+ * reserved; the Events core stays the authority on every rule. Web APIs only (R35).
+ */
+
+/** The suite's page (injected by `suiteIntegration`): booking and inline signing. */
+export const WAIVER_PATH = "/_events/waiver";
+/** Attendee rows the widget offers (one booking holds at most this many seats). */
+export const MAX_SEATS = 10;
+export const DEFAULT_SEATS = 4;
+
+export type SeatPart = "ticketTypeId" | "name" | "email" | "minor";
+/** The form control (and field id) of one part of attendee row `row` (1-based). */
+export const seatField = (row: number, part: SeatPart) => `attendee.${row}.${part}`;
+
+/** Query parameters a refused booking returns to the widget with (codes and field names only). */
+export const WAIVER_PARAMS = { error: "waiver_error", fields: "waiver_fields", event: "waiver_event" } as const;
+
+/**
+ * A C0 control character (U+0000-U+001F) or DEL (U+007F): esign-intent/1 §5 refuses them in a
+ * `name`, so a name carrying one would only fail later, at e-sign, after the seats are held.
+ */
+export function hasControlCharacters(value: string): boolean {
+	for (let i = 0; i < value.length; i++) {
+		const unit = value.charCodeAt(i);
+		if (unit <= 0x1f || unit === 0x7f) return true;
+	}
+	return false;
+}
+
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+export interface WaiverAttendee {
+	ticketTypeId: string;
+	name: string;
+	email?: string;
+	minor?: true;
+}
+
+export interface WaiverOrder {
+	eventId: string;
+	occurrenceId?: string;
+	buyer: { name: string; email: string };
+	attendees: WaiverAttendee[];
+	/** Seats per ticket type, in the order the types first appear. */
+	lines: Array<{ ticketTypeId: string; qty: number }>;
+	/** The form row of each attendee, to point the core's issues back at the right row. */
+	rows: number[];
+	idempotencyKey: string;
+	turnstileToken?: string;
+}
+
+export type WaiverFormResult =
+	| { ok: true; order: WaiverOrder }
+	| { ok: false; code: "BAD_REQUEST" | "CONTROL_CHARACTERS"; fields: string[] };
+
+const text = (form: FormData, key: string) => {
+	const value = form.get(key);
+	return typeof value === "string" ? value.trim() : "";
+};
+
+/** Reads the widget's post; on a refusal, names the fields to fix (never their values). */
+export function readWaiverForm(form: FormData): WaiverFormResult {
+	const bad: string[] = [];
+	let control = false;
+	const check = (field: string, value: string, valid: boolean) => {
+		if (hasControlCharacters(value)) {
+			control = true;
+			bad.push(field);
+		} else if (!valid) bad.push(field);
+	};
+
+	const eventId = text(form, "eventId");
+	if (!eventId) bad.push("event");
+	const occurrenceId = text(form, "occurrenceId");
+	if (form.get("needsOccurrence") === "1" && !occurrenceId) bad.push("occurrence");
+	const buyer = { name: text(form, "name"), email: text(form, "email") };
+	check("name", buyer.name, buyer.name.length >= 1 && buyer.name.length <= 200);
+	check("email", buyer.email, buyer.email.length <= 254 && EMAIL.test(buyer.email));
+
+	const attendees: WaiverAttendee[] = [];
+	const rows: number[] = [];
+	// An event that needs no waiver (T066) is booked by ticket type and quantity: no attendee rows.
+	const plain = form.get("plain") === "1";
+	const plainType = text(form, "ticketTypeId");
+	const plainQty = Number(text(form, "qty"));
+	if (plain && !(plainType && Number.isInteger(plainQty) && plainQty >= 1 && plainQty <= MAX_SEATS))
+		bad.push("tickets");
+	for (let row = 1; row <= (plain ? 0 : MAX_SEATS); row++) {
+		const name = text(form, seatField(row, "name"));
+		const email = text(form, seatField(row, "email"));
+		const minor = form.get(seatField(row, "minor")) === "on";
+		if (!name && !email && !minor) continue;
+		const ticketTypeId = text(form, seatField(row, "ticketTypeId"));
+		if (!ticketTypeId) bad.push(seatField(row, "ticketTypeId"));
+		check(seatField(row, "name"), name, name.length >= 1 && name.length <= 200);
+		if (email) check(seatField(row, "email"), email, email.length <= 254 && EMAIL.test(email));
+		attendees.push({ ticketTypeId, name, ...(email ? { email } : {}), ...(minor ? { minor: true as const } : {}) });
+		rows.push(row);
+	}
+	if (!plain && attendees.length === 0) bad.push("attendees");
+	if (bad.length > 0) return { ok: false, code: control ? "CONTROL_CHARACTERS" : "BAD_REQUEST", fields: bad };
+
+	const counts = new Map<string, number>(plain ? [[plainType, plainQty]] : []);
+	for (const a of attendees) counts.set(a.ticketTypeId, (counts.get(a.ticketTypeId) ?? 0) + 1);
+	const turnstileToken = text(form, "cf-turnstile-response");
+	return {
+		ok: true,
+		order: {
+			eventId,
+			...(occurrenceId ? { occurrenceId } : {}),
+			buyer,
+			idempotencyKey: text(form, "idempotencyKey"),
+			...(turnstileToken ? { turnstileToken } : {}),
+			lines: [...counts].map(([ticketTypeId, qty]) => ({ ticketTypeId, qty })),
+			attendees,
+			rows,
+		},
+	};
+}
+
+/** Messages for the codes a refused booking comes back with. */
+export const WAIVER_MESSAGES: Record<string, string> = {
+	BAD_REQUEST: "Please check the highlighted details.",
+	CONTROL_CHARACTERS: "Names and emails cannot contain control characters (such as tabs or line breaks).",
+	WAIVER_EMAIL_REQUIRED:
+		"Every adult other than you needs their own email address, so they can sign their waiver themselves.",
+	WAIVER_TOO_MANY_EMAILS:
+		"One booking can invite at most 10 adults to sign by email. Please split the group into smaller bookings.",
+	SOLD_OUT: "Sorry, there are not enough tickets left for that order.",
+	SALES_CLOSED: "Ticket sales for this event are closed.",
+	RATE_LIMITED: "Too many bookings from this connection. Please wait a few minutes and try again.",
+	TURNSTILE_FAILED: "The security check did not pass. Please try again.",
+	HOLD_EXPIRED: "Your hold on these tickets expired. Please start again.",
+	NOT_FOUND: "This event is not taking bookings.",
+	SIGNING_UNAVAILABLE:
+		"The waiver could not be opened for signing just now. Your tickets are still held for a short time: try again, or contact the organiser.",
+	INTERNAL: "Something went wrong. Please try again.",
+};
+
+/** The anchor of a widget, so a refusal scrolls back to it. */
+export function waiverAnchor(eventId: string): string {
+	return `semics-waiver-${eventId.replace(/[^A-Za-z0-9_-]/g, "_")}`;
+}
+
+/** A same-site path to return to after a refusal; never another origin or one of the plugins' own routes. */
+export function safeReturnPath(raw: string, origin: string): string | undefined {
+	if (!raw.startsWith("/") || raw.startsWith("//") || raw.startsWith("/\\")) return undefined;
+	let url: URL;
+	try {
+		url = new URL(raw, origin);
+	} catch {
+		return undefined;
+	}
+	// `/.//x` and `/%2e//x` resolve to `//x`: as a Location that is another host (T119 F11).
+	const path = url.pathname;
+	if (url.origin !== origin || path.startsWith("//") || path.startsWith("/_events/") || path.startsWith("/_emdash/")) {
+		return undefined;
+	}
+	for (const name of Object.values(WAIVER_PARAMS)) url.searchParams.delete(name);
+	return `${url.pathname}${url.search}`;
+}
+
+/** Where a refused booking goes: back to the widget with a code and the fields to fix. No values. */
+export function waiverErrorLocation(
+	returnTo: string,
+	eventId: string,
+	code: string,
+	fields: readonly string[],
+): string {
+	const url = new URL(returnTo, "http://x");
+	url.searchParams.set(WAIVER_PARAMS.error, code);
+	if (fields.length > 0) url.searchParams.set(WAIVER_PARAMS.fields, fields.join(","));
+	url.searchParams.set(WAIVER_PARAMS.event, eventId);
+	return `${url.pathname}${url.search}#${waiverAnchor(eventId)}`;
+}
+
+const KNOWN_FIELD = new RegExp(
+	`^(event|occurrence|name|email|tickets|attendees|attendee\\.([1-9]|${MAX_SEATS})\\.(ticketTypeId|name|email))$`,
+);
+
+/** The refusal a widget shows after a round trip; only for the widget of `eventId`. */
+export function readWaiverState(url: URL, eventId: string): { code?: string; fields: string[] } {
+	const raw = url.searchParams.get(WAIVER_PARAMS.error);
+	if (!raw || url.searchParams.get(WAIVER_PARAMS.event) !== eventId) return { fields: [] };
+	const code = Object.hasOwn(WAIVER_MESSAGES, raw) ? raw : "INTERNAL";
+	const fields = (url.searchParams.get(WAIVER_PARAMS.fields) ?? "").split(",").filter((f) => KNOWN_FIELD.test(f));
+	return { code, fields };
+}

package/src/astro/lib/reconcile.ts

@@ -0,0 +1,66 @@
+/**
+ * Closed-tab reconciliation for a booking that waits for signatures (SX-FR-05; esign-intent/1 §8.3).
+ * A signer may have finished without Events hearing of it: they closed the tab before the receipt
+ * redirect, or they sign by email and never come back here. When the booking page loads, the Events
+ * core lists the refs still unsigned and (Pro) a signed lookup request for each, minted where the
+ * pairing secret lives. This asks e-sign's `public/receipts/lookup` for each request and forwards every
+ * terminal receipt to Events with Events' own `forwardReceipt`. Events stores a receipt once and never
+ * replaces a completed one, so forwarding the same receipt again changes nothing.
+ *
+ * Glue only: no storage, no tokens minted, no judgement about what a receipt means. The Free core
+ * lists no requests, so nothing happens there. Every failure is swallowed: the status page must render.
+ * Web APIs only, no `@semics-tech/shared` (R35).
+ */
+import { callPublicRoute, type PublicRouteContext } from "@semics-tech/emdash-events/astro/lib/call";
+import { forwardReceipt } from "@semics-tech/emdash-events/astro/lib/receipt";
+import type { BookingView } from "@semics-tech/emdash-events/astro/lib/widget";
+
+export interface ReconcileInput {
+	booking: Pick<BookingView, "bookingRef" | "waiver">;
+	/** The Events core's plugin id. */
+	pluginId: string;
+	/** The E-sign core's plugin id. */
+	esignPluginId: string;
+}
+
+/** A page load asks e-sign at most this many times (the core lists no more refs than this). */
+const MAX_LOOKUPS = 10;
+/** `payloadB64 "." signature` (§4). */
+const TOKEN = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{43}$/;
+const LOOKUP_MAX = 1024;
+const RECEIPT_MAX = 2048;
+
+const tokenOf = (value: unknown, max: number): string | null =>
+	typeof value === "string" && value.length <= max && TOKEN.test(value) ? value : null;
+
+/** Forwards the receipts e-sign already holds for the booking's unsigned refs; resolves with how many Events took. */
+export async function reconcileBooking(ctx: PublicRouteContext, input: ReconcileInput): Promise<{ forwarded: number }> {
+	const { refs = [], lookups = {} } = input.booking.waiver ?? {};
+	const requests = refs
+		.slice(0, MAX_LOOKUPS)
+		.map((ref) => tokenOf(lookups[ref], LOOKUP_MAX))
+		.filter((token): token is string => token !== null);
+	const answers = await Promise.all(
+		requests.map((request) =>
+			callPublicRoute<{ state?: unknown; receipt?: unknown }>(ctx, {
+				method: "POST",
+				path: "public/receipts/lookup",
+				pluginId: input.esignPluginId,
+				body: { request },
+			}).catch(() => null),
+		),
+	);
+	let forwarded = 0;
+	for (const answer of answers) {
+		if (!answer?.ok || answer.data.state !== "terminal") continue;
+		const receipt = tokenOf(answer.data.receipt, RECEIPT_MAX);
+		if (receipt === null) continue;
+		const done = await forwardReceipt(
+			ctx,
+			{ ref: input.booking.bookingRef, receipt },
+			{ pluginId: input.pluginId, esignPluginId: input.esignPluginId },
+		).catch(() => null);
+		if (done && !done.location.includes("waiver=failed")) forwarded += 1;
+	}
+	return { forwarded };
+}

package/src/astro/lib/templates.ts

@@ -0,0 +1,76 @@
+/**
+ * The catalogue refresh behind the Events panel's "Refresh templates" (SX-FR-07; esign-intent/1 §8.5).
+ * The Events core cannot reach E-sign, and only it holds the pairing secret, so the panel's button
+ * (Events Pro) mints a short-lived catalogue request and links to `/_events/templates#catalog=<request>`
+ * (a fragment: tokens never travel in URLs). The page posts the request here: E-sign's
+ * `public/templates/catalog` answers with the templates flagged "available to integrations", and
+ * Events `esign/catalog` caches them for the panel's template select. Events checks the request
+ * again (it must be one it minted, within five minutes), so a forged list cannot get in.
+ *
+ * Glue only. Web APIs only, no `@semics-tech/shared` (R35).
+ */
+import { callPublicRoute, type PublicRouteContext } from "@semics-tech/emdash-events/astro/lib/call";
+
+/** The page the panel links to (injected by `suiteIntegration`). */
+export const TEMPLATES_PATH = "/_events/templates";
+
+export interface CatalogueIds {
+	eventsPluginId: string;
+	esignPluginId: string;
+}
+
+export type CatalogueResult = { ok: true; count: number } | { ok: false; code: string };
+
+const REQUEST = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{43}$/;
+const REQUEST_MAX = 1024;
+const TEMPLATE_ID = /^[A-Za-z0-9_-]{1,64}$/;
+const MAX_TEMPLATES = 100;
+
+interface Template {
+	id: string;
+	name: string;
+	version: number;
+}
+
+/** The templates that fit the protocol's grammar; anything else e-sign sent is dropped. */
+function usable(raw: unknown): Template[] {
+	if (!Array.isArray(raw)) return [];
+	const out: Template[] = [];
+	for (const t of raw) {
+		const { id, name, version } = (t ?? {}) as Record<string, unknown>;
+		if (typeof id !== "string" || !TEMPLATE_ID.test(id)) continue;
+		if (typeof name !== "string" || name.length < 1 || name.length > 200) continue;
+		if (typeof version !== "number" || !Number.isInteger(version) || version < 1) continue;
+		out.push({ id, name, version });
+		if (out.length === MAX_TEMPLATES) break;
+	}
+	return out;
+}
+
+/** Fetches the catalogue with `request` and hands it to Events. Never throws. */
+export async function refreshCatalogue(
+	ctx: PublicRouteContext,
+	request: unknown,
+	ids: CatalogueIds,
+): Promise<CatalogueResult> {
+	if (typeof request !== "string" || request.length > REQUEST_MAX || !REQUEST.test(request)) {
+		return { ok: false, code: "REQUEST_INVALID" };
+	}
+	const fetched = await callPublicRoute<{ templates?: unknown }>(ctx, {
+		method: "POST",
+		path: "public/templates/catalog",
+		pluginId: ids.esignPluginId,
+		body: { request },
+	}).catch(() => null);
+	if (!fetched) return { ok: false, code: "INTERNAL" };
+	if (!fetched.ok) return { ok: false, code: fetched.error.code };
+	const templates = usable(fetched.data.templates);
+	const cached = await callPublicRoute(ctx, {
+		method: "POST",
+		path: "esign/catalog",
+		pluginId: ids.eventsPluginId,
+		body: { request, templates },
+	}).catch(() => null);
+	if (!cached) return { ok: false, code: "INTERNAL" };
+	return cached.ok ? { ok: true, count: templates.length } : { ok: false, code: cached.error.code };
+}

package/src/astro/virtual.d.ts

@@ -0,0 +1,7 @@
+// Provided by the suite integration's Vite plugin (`eventsSuite()` / `suiteIntegration(ids)`).
+declare module "virtual:semics-events-suite/config" {
+	/** The Events core's plugin id on this site (a slug for npm installs, `r_…` from the registry). */
+	export const eventsPluginId: string;
+	/** The E-sign core's plugin id on this site. */
+	export const esignPluginId: string;
+}