@getmicdrop/venue-calendar 4.3.37 → 4.3.39

package/dist/api/recommendations.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Cross-event recommendations — the buyer's read.
+ *
+ * The rail on an event page and the block on the checkout-success page both
+ * come from here. The answer is already materialized and cached server-side, so
+ * this is one indexed read; nothing on a buyer's path ever waits on a model.
+ *
+ * EVERY failure returns an empty list. A cross-sell rail is decoration on
+ * somebody's event page — if it cannot load, the page renders without it and
+ * nobody sees an error.
+ */
+/** Why a show is being recommended. Rendered to the buyer as the badge. */
+export type RecommendationRule = 'performer' | 'genre' | 'weekday' | 'similar' | 'pin';
+/** The surfaces a buyer can see. `email` is rendered server-side at send time. */
+export type RecommendationSurface = 'event_page' | 'success';
+export interface RecommendationCard {
+    eventId: number;
+    slot: number;
+    rule: RecommendationRule;
+    title: string;
+    startsAt: string | null;
+    timeZone: string;
+    venueName: string;
+    image?: string;
+    url?: string;
+    minPrice?: number;
+}
+/**
+ * Fetches the recommendations for one event and surface.
+ *
+ * @param eventId - the event being viewed or bought
+ * @param surface - which placement is asking
+ * @param widgetKey - the embed key, when this render is inside a widget
+ */
+export declare function getRecommendations(eventId: number, surface?: RecommendationSurface, widgetKey?: string): Promise<RecommendationCard[]>;

package/dist/api/surge-queue.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Surge queue — the virtual waiting room's half of the wire.
+ *
+ * On a viral on-sale every buyer races for the same inventory decrement on
+ * `POST /orders/create`. The backend puts a line in front of that door: a
+ * bounded number of buyers hold a checkout pass at any moment and everyone else
+ * waits with a position and an estimate. These four calls are how the widget
+ * asks about the line, takes a place in it, watches it move, and gives the place
+ * back.
+ *
+ * FAIL OPEN, EVERY TIME. The queue is a protection mechanism, not a money
+ * control — the backend itself reports `armed:false` when it cannot reach Redis,
+ * because refusing every sale on the platform is a worse outcome than a surge.
+ * So every function here degrades to "there is no line": a read that fails must
+ * never leave an overlay across a checkout that would have worked. The only
+ * thing that actually gates a purchase is the server's `QUEUE_REQUIRED` refusal
+ * on `/orders/create`, which `initiateOrder` in src/lib/utils/orderApi.ts
+ * surfaces as its own error type — that refusal cannot be lost by a client-side
+ * failure, which is what makes failing open here safe.
+ *
+ * @auth-token-url-escape: the status poll carries its token in the query string
+ * because that is the only shape the endpoint answers —
+ * `GET /events/:id/queue/status?token=…`. A request header would move it out of
+ * nginx logs and browser history, and would also add a CORS preflight to every
+ * poll of a line that can be tens of thousands deep, on the one endpoint whose
+ * whole purpose is to survive that load. What the token actually grants is one
+ * place in one line: it expires with the pass, `leaveQueue` revokes it, and it
+ * authorises no order, no payment and no session. The marker is FILE-LEVEL —
+ * the only scope the rule offers — so it covers anything added here later.
+ */
+/**
+ * The refusal code the gate answers on `POST /orders/create` (HTTP 429) when
+ * the event is armed and the caller holds no admitted token.
+ *
+ * Exported so the one consumer that has to recognise it — `initiateOrder` —
+ * matches the backend's spelling rather than carrying a second copy of the
+ * string. A drifted spelling would classify a queue refusal as a server fault
+ * and the buyer would be told the sale failed.
+ */
+export declare const QUEUE_REQUIRED = "QUEUE_REQUIRED";
+/**
+ * This module's own code for "the queue could not be asked" — a transport
+ * failure, not a verdict. Distinct from anything the backend sends so a caller
+ * can tell a refusal apart from an unanswered question, and fail open on both.
+ */
+export declare const QUEUE_UNAVAILABLE = "queue_unavailable";
+/** The event's own setting: `off` never queues, `on` always does, `auto` arms
+ *  itself while demand holds and dissolves on its own afterwards. */
+export type QueueMode = 'off' | 'auto' | 'on';
+/**
+ * Where one buyer stands.
+ *
+ * `open` is the answer when the event has no line at all — there is nothing to
+ * wait for and no token to carry. `expired` means the line entry or the checkout
+ * pass timed out and the client must re-join.
+ */
+export type QueueState = 'open' | 'waiting' | 'admitted' | 'expired';
+/** The tokenless "is there a line?" answer — cheap enough for every page load. */
+export interface QueueSnapshot {
+    /** The only field the widget branches on: false renders nothing at all. */
+    armed: boolean;
+    mode: QueueMode;
+    /** How many people are in line right now. */
+    waiting: number;
+    /** The server's estimate for somebody joining now. */
+    etaSeconds: number;
+}
+/**
+ * A place in line, or a checkout pass — join and status answer the same shape,
+ * so a poll is read exactly like the join that started it.
+ */
+export interface QueueEntry {
+    token: string;
+    state: QueueState;
+    /** 1-based place in line. */
+    position: number;
+    /** How many people are in front of this buyer. */
+    ahead: number;
+    etaSeconds: number;
+    /** How long to wait before polling again. The server widens it as the line
+     *  grows, so a 50k-deep queue does not become its own DDoS — honour it. */
+    pollAfterMs: number;
+    /** ISO instant the line entry or the checkout pass dies. */
+    expiresAt: string;
+}
+export interface QueueEntryResult {
+    success: boolean;
+    entry?: QueueEntry;
+    /** The backend's failure code, or this module's `queue_unavailable`. */
+    errorCode?: string;
+    /** The HTTP status, so a caller can back off on a 429 from the join or status
+     *  rate limiter without reading a sentence written for a human. */
+    statusCode?: number;
+}
+export interface LeaveQueueResult {
+    /** False for an unknown token, which the server answers 200 — leave is a
+     *  beacon, not a transaction, so "nothing to release" is not a failure. */
+    released: boolean;
+}
+/**
+ * Is there a line on this event? Tokenless and cheap, for page load.
+ *
+ * Answers `armed:false` for every failure, so a blip on this call is exactly
+ * today's behaviour: the buyer goes straight at the buy button, and the gate
+ * decides.
+ */
+export declare function getQueueState(eventId: string | number): Promise<QueueSnapshot>;
+/**
+ * Take a place in line, or a checkout pass when there is spare capacity.
+ *
+ * Safe to call again on a reload: the server hands a caller that already holds a
+ * live token for this event its existing entry back, so a refresh does not cost
+ * the buyer their spot. It does NOT need to be called before every purchase —
+ * the reactive entry into the line is the gate's `QUEUE_REQUIRED` refusal.
+ */
+export declare function joinQueue(eventId: string | number): Promise<QueueEntryResult>;
+/**
+ * The poll. Answers the same shape as the join that started it, and draining the
+ * line is its server-side side effect — so stopping the poll stops the line
+ * moving for everybody, and polling faster than `pollAfterMs` is what the server
+ * widens that number to prevent.
+ */
+export declare function getQueueStatus(eventId: string | number, token: string): Promise<QueueEntryResult>;
+/**
+ * Give the place in line, or the checkout pass, back.
+ *
+ * Sent on `pagehide`, which is the whole reason for the two request options:
+ * without `keepalive` the browser cancels an in-flight request as the document
+ * goes away and the slot is held until the pass expires — the next buyer waits
+ * fifteen minutes for a tab that closed. And a beacon fired at unload has nobody
+ * left to tell, so its failure is not routed to the global error handler.
+ */
+export declare function leaveQueue(eventId: string | number, token: string): Promise<LeaveQueueResult>;