@riverbankcms/sdk 0.136.0 → 0.138.0

package/dist/_dts/core/src/whole-series-run-schedule.d.ts

@@ -0,0 +1,92 @@
+/**
+ * When a run is open to join, and where it sits in its own life.
+ *
+ * One authority for both, shared by the public read projection, the write-side
+ * run-facts loader and the page surfaces, so a run cannot report itself open on
+ * the storefront and closed at the point of booking.
+ *
+ * Every derivation here goes through `orderedLiveRunSessions`. That is the one
+ * ordered-schedule boundary: callers hand over whatever order their storage
+ * gave them, cancelled sessions are dropped, and the rest is read in schedule
+ * order. Cancelled sessions are excluded because a run whose opening week is
+ * cancelled has not started, and a run whose only remaining sessions are
+ * cancelled has not silently finished. The sessions themselves still travel
+ * with their `status` so a surface can show the cancellation.
+ *
+ * Booking needs a session to sell. A run with no schedule, or one whose every
+ * session has been cancelled, is closed — but it is closed for want of dates,
+ * not because it is under way, and the booking phase says which.
+ *
+ * Every function takes an explicit clock. Nothing here reads `Date.now()`.
+ */
+export type WholeSeriesScheduleSession = Readonly<{
+    startsAt: string;
+    endsAt: string;
+    status: string;
+}>;
+export type WholeSeriesRunLifecycle = 'upcoming' | 'in_progress' | 'completed' | 'cancelled';
+/**
+ * Whether a run still takes bookings, and if not, why.
+ *
+ * A page is often rendered from a projection that was prepared a little
+ * earlier, so the first session start is re-checked against the render clock
+ * rather than trusted from `enrollmentOpen` alone. The registration endpoint
+ * remains the authority that actually refuses a late booking; this only decides
+ * whether to invite one.
+ */
+export type WholeSeriesBookingPhase = Readonly<{
+    kind: 'open';
+}> | Readonly<{
+    kind: 'closed';
+    reason: 'cancelled' | 'in-progress' | 'completed' | 'enrolment-closed' | 'no-sessions';
+}>;
+/**
+ * A session that is not happening.
+ *
+ * Exported because every surface that renders a run's schedule has to mark the
+ * same weeks, and a second copy of the string is a second chance to disagree.
+ */
+export declare const CANCELLED_SESSION_STATUS = "cancelled";
+/**
+ * The run's sessions that still count, in schedule order.
+ *
+ * Sessions whose start cannot be read are dropped rather than sorted to an
+ * arbitrary end: an unparseable date is not a date a visitor can attend.
+ */
+export declare function orderedLiveRunSessions<TSession extends WholeSeriesScheduleSession>(sessions: readonly TSession[]): readonly TSession[];
+/** When the first session a visitor could attend begins. */
+export declare function firstLiveRunSessionStartMs(sessions: readonly WholeSeriesScheduleSession[]): number | null;
+/**
+ * Booking stays open until the run's first surviving session has started.
+ *
+ * There has to be something left to sell: a run with no schedule at all, or one
+ * whose every session has been cancelled, is closed rather than open. Adding a
+ * future session opens it again, subject to the usual status, visibility and
+ * admission rules.
+ */
+export declare function isWholeSeriesRegistrationOpen(sessions: readonly WholeSeriesScheduleSession[], now: Date): boolean;
+/**
+ * Where the run sits in its own life, independent of any one session.
+ *
+ * A cancelled or completed series status says so whatever the dates read.
+ * Otherwise the surviving schedule decides: before the first session it is
+ * upcoming, after the last session ends it is complete, and in between it is
+ * under way. A run with nothing left to attend is `upcoming` and never
+ * `in_progress` — an empty schedule has not started.
+ */
+export declare function resolveWholeSeriesRunLifecycle(input: Readonly<{
+    seriesStatus: string;
+    sessions: readonly WholeSeriesScheduleSession[];
+}>, now: Date): WholeSeriesRunLifecycle;
+/**
+ * Whether a prepared run is still inviting bookings at render time.
+ *
+ * `lifecycle` and `enrollmentOpen` come from the projection; the first session
+ * start is the one fact re-read against `now`, because that is the boundary a
+ * cached page can cross while it sits in front of a visitor.
+ */
+export declare function resolveWholeSeriesBookingPhase(run: Readonly<{
+    lifecycle: WholeSeriesRunLifecycle;
+    enrollmentOpen: boolean;
+    sessions: readonly WholeSeriesScheduleSession[];
+}>, now: Date): WholeSeriesBookingPhase;