@theatrical/sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,2243 @@
+import { z } from 'zod';
+
+/**
+ * Vista platform environments
+ */
+type TheatricalEnvironment = 'sandbox' | 'staging' | 'production';
+/**
+ * Configuration for the TheatricalClient
+ */
+interface TheatricalConfig {
+    /** Vista API key — obtain from your Vista representative */
+    apiKey: string;
+    /** Target environment. Defaults to 'sandbox' */
+    environment?: TheatricalEnvironment;
+    /** Override the base URL. Normally derived from environment */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to 30000 */
+    timeout?: number;
+    /** Maximum retry attempts for failed requests. Defaults to 3 */
+    maxRetries?: number;
+    /** Enable debug logging. Defaults to false */
+    debug?: boolean;
+}
+
+/**
+ * Client for Vista's Global Authentication Service (GAS)
+ * Handles JWT token acquisition from auth.moviexchange.com
+ */
+interface GASConfig {
+    apiKey: string;
+    authUrl: string;
+}
+interface GASToken {
+    accessToken: string;
+    tokenType: string;
+    expiresIn: number;
+    issuedAt: number;
+}
+declare class GASClient {
+    private readonly config;
+    constructor(config: GASConfig);
+    /**
+     * Request a new JWT token from the Global Authentication Service
+     */
+    requestToken(): Promise<GASToken>;
+}
+
+/**
+ * Manages JWT token lifecycle — caching, refresh, and expiry detection.
+ * Ensures API requests always have a valid token without redundant auth calls.
+ */
+declare class TokenManager {
+    private readonly gasClient;
+    private currentToken;
+    private refreshPromise;
+    /** Buffer before expiry to trigger refresh (5 minutes) */
+    private readonly expiryBuffer;
+    constructor(gasClient: GASClient);
+    /**
+     * Get a valid access token, refreshing if necessary.
+     * Deduplicates concurrent refresh requests.
+     */
+    getToken(): Promise<string>;
+    /**
+     * Force a token refresh regardless of current token state
+     */
+    refresh(): Promise<GASToken>;
+    /**
+     * Check if a token is expired or within the expiry buffer
+     */
+    private isExpired;
+    /**
+     * Clear the current token (e.g., on 401 response)
+     */
+    invalidate(): void;
+}
+
+/**
+ * Retry utilities for the Theatrical HTTP client.
+ * Provides configurable exponential backoff with optional jitter,
+ * designed for resilient communication with Vista's OCAPI platform.
+ *
+ * @module http/retry
+ */
+/** Configuration for automatic request retry behaviour. */
+interface RetryConfig {
+    /**
+     * Maximum number of retry attempts. The initial request is not counted.
+     * A value of 3 means up to 4 total attempts (initial + 3 retries).
+     * @default 3
+     */
+    maxRetries: number;
+    /**
+     * Base delay in milliseconds for the first retry.
+     * Subsequent retries use exponential backoff: `baseDelay * 2^(attempt - 1)`.
+     * @default 1000
+     */
+    baseDelay: number;
+    /**
+     * Maximum delay cap in milliseconds.
+     * Prevents backoff from growing unbounded on high retry counts.
+     * @default 30_000
+     */
+    maxDelay: number;
+    /**
+     * When true, adds randomised full jitter to each delay.
+     * Spreads retry storms across the Vista API cluster.
+     * @default true
+     */
+    jitter: boolean;
+    /**
+     * Optional predicate — when provided, retries only if this function returns
+     * true for the thrown error. Use to avoid retrying non-recoverable errors
+     * such as 400 Bad Request or 401 Unauthorised.
+     */
+    shouldRetry?: (error: unknown) => boolean;
+}
+
+/**
+ * Sliding-window rate limiter for the Theatrical HTTP client.
+ * Prevents the SDK from exceeding Vista's OCAPI rate limits by queuing
+ * requests proactively rather than recovering from 429 responses after the fact.
+ *
+ * @module http/rate-limiter
+ */
+/** Configuration for the sliding-window rate limiter. */
+interface RateLimiterConfig {
+    /**
+     * Maximum number of requests allowed within the rolling window.
+     * Matches Vista's OCAPI per-key limit for the configured window.
+     */
+    maxRequests: number;
+    /**
+     * Duration of the sliding window in milliseconds.
+     * Timestamps older than `now - windowMs` are evicted and no longer count.
+     * @default 60_000
+     */
+    windowMs: number;
+}
+/**
+ * Sliding-window rate limiter using a timestamp queue.
+ *
+ * Tracks the wall-clock time of each accepted request. When the in-window
+ * request count reaches `maxRequests`, `waitForSlot()` blocks until the oldest
+ * recorded timestamp exits the window, then records the new request and resolves.
+ *
+ * @example
+ * const limiter = new RateLimiter({ maxRequests: 100, windowMs: 60_000 });
+ *
+ * // In the HTTP client, before each fetch:
+ * await limiter.waitForSlot();
+ * const response = await fetch(url, options);
+ */
+declare class RateLimiter {
+    private readonly config;
+    private readonly timestamps;
+    /**
+     * Creates a new RateLimiter.
+     * @param config - Limits and window size. Defaults to {@link DEFAULT_RATE_LIMITER_CONFIG}.
+     */
+    constructor(config?: RateLimiterConfig);
+    /**
+     * Waits until a request slot is available within the current window,
+     * records the request timestamp, and resolves.
+     *
+     * Callers `await` this before making an HTTP request. If the limit has been
+     * reached, the call suspends until the oldest in-window request expires.
+     *
+     * @returns Promise that resolves when it is safe to proceed with a request
+     */
+    waitForSlot(): Promise<void>;
+    /**
+     * Returns the number of requests recorded within the current rolling window.
+     * Useful for diagnostics and integration tests.
+     */
+    get activeCount(): number;
+    /**
+     * Clears all recorded timestamps, resetting the limiter to a clean state.
+     * Primarily intended for use in tests.
+     */
+    reset(): void;
+}
+
+/**
+ * Request/response interceptor types and chain runner for the Theatrical HTTP client.
+ * Interceptors allow consumers to inspect or mutate requests before they are sent
+ * and responses before they are returned — useful for logging, auth header injection,
+ * response normalisation, and telemetry.
+ *
+ * @module http/interceptors
+ */
+/**
+ * A function that receives a {@link RequestConfig} before a request is sent
+ * and returns a (possibly mutated) config to use instead.
+ *
+ * Return the same object to pass through unchanged, or return a new object to
+ * override headers, the URL, the body, etc.
+ *
+ * Async interceptors are fully supported — return a `Promise<RequestConfig>` to
+ * perform async work (e.g. look up a secondary token, log to an external service).
+ *
+ * @example
+ * const addCorrelationId: RequestInterceptor = (config) => ({
+ *   ...config,
+ *   headers: { ...config.headers, 'X-Correlation-ID': uuid() },
+ * });
+ */
+type RequestInterceptor = (config: RequestConfig) => RequestConfig | Promise<RequestConfig>;
+/**
+ * A function that receives a `Response` after a successful HTTP call and returns
+ * a (possibly mutated) `Response` to pass upstream.
+ *
+ * Note: interceptors run only on responses that pass the `response.ok` check.
+ * Error responses are handled by the client's error-mapping logic before
+ * interceptors are invoked.
+ *
+ * @example
+ * const logLatency: ResponseInterceptor = (response) => {
+ *   console.log(`[theatrical] ${response.url} — ${response.status}`);
+ *   return response;
+ * };
+ */
+type ResponseInterceptor = (response: Response) => Response | Promise<Response>;
+/**
+ * A plain-object snapshot of the mutable parts of a fetch request.
+ * Passed through the {@link RequestInterceptor} chain before each call.
+ */
+interface RequestConfig {
+    /** Fully-qualified URL for the request (base URL + path + query string). */
+    url: string;
+    /** HTTP method. */
+    method: string;
+    /** Request headers (merged with auth and content-type defaults). */
+    headers: Record<string, string>;
+    /** Serialised request body, or undefined for GET/DELETE. */
+    body?: string;
+}
+
+interface HTTPClientConfig {
+    baseUrl: string;
+    timeout: number;
+    maxRetries: number;
+    tokenManager: TokenManager;
+    debug: boolean;
+    /** Optional retry configuration. Defaults to {@link DEFAULT_RETRY_CONFIG}. */
+    retry?: RetryConfig;
+    /**
+     * Optional rate limiter instance for proactive request throttling.
+     *
+     * When provided, `waitForSlot()` is called before each outgoing request to
+     * ensure the SDK never exceeds Vista's OCAPI rate limits. If not provided,
+     * no proactive limiting is applied — the client falls back to reactive
+     * handling of 429 responses.
+     *
+     * Inject a shared `RateLimiter` when multiple SDK instances target the same
+     * Vista operator key, so all instances contribute to the same window count.
+     *
+     * @example
+     * ```typescript
+     * import { RateLimiter } from '@theatrical/sdk';
+     *
+     * const limiter = new RateLimiter({ maxRequests: 60, windowMs: 60_000 });
+     * const client = new TheatricalHTTPClient({ ..., rateLimiter: limiter });
+     * ```
+     */
+    rateLimiter?: RateLimiter;
+    /**
+     * Ordered list of request interceptors.
+     * Each interceptor receives the {@link RequestConfig} built for the outgoing
+     * request and may return a mutated copy. Interceptors run in array order
+     * before the `fetch` call is made.
+     */
+    onRequest?: RequestInterceptor[];
+    /**
+     * Ordered list of response interceptors.
+     * Each interceptor receives the raw `Response` object after a successful
+     * (`response.ok`) fetch and may return a mutated copy. Interceptors run in
+     * array order before the response body is decoded.
+     */
+    onResponse?: ResponseInterceptor[];
+}
+interface RequestOptions {
+    method?: string;
+    params?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/**
+ * Core HTTP client for all Vista API communication.
+ * Handles authentication, retries, rate limiting, and error transformation.
+ */
+declare class TheatricalHTTPClient {
+    private readonly config;
+    constructor(config: HTTPClientConfig);
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, options?: RequestOptions): Promise<T>;
+    put<T>(path: string, options?: RequestOptions): Promise<T>;
+    delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    private request;
+    private buildUrl;
+    private generateRequestId;
+    private delay;
+}
+
+/**
+ * Zod schema for presentation format — validates format strings from the API.
+ */
+declare const sessionFormatSchema: z.ZodEnum<["2D", "3D", "IMAX", "IMAX3D", "4DX", "DOLBY_CINEMA", "SCREENX", "STANDARD"]>;
+/**
+ * Zod schema for seat status — validates seat availability state from the API.
+ */
+declare const seatStatusSchema: z.ZodEnum<["available", "taken", "reserved", "wheelchair", "companion", "blocked"]>;
+/**
+ * A cinema session (showtime) — a specific screening of a film
+ * at a specific site, screen, date, and time.
+ */
+interface Session {
+    /** Unique session identifier */
+    id: string;
+    /** Film being screened */
+    filmId: string;
+    /** Film title */
+    filmTitle: string;
+    /** Cinema site ID */
+    siteId: string;
+    /** Screen/auditorium identifier */
+    screenId: string;
+    /** Screen name (e.g., "Screen 3", "IMAX") */
+    screenName: string;
+    /** Session start time (ISO 8601) */
+    startTime: string;
+    /** Session end time (ISO 8601) */
+    endTime: string;
+    /** Presentation format */
+    format: SessionFormat;
+    /** Whether the session is bookable */
+    isBookable: boolean;
+    /** Whether the session is sold out */
+    isSoldOut: boolean;
+    /** Available seat count */
+    seatsAvailable: number;
+    /** Total seat capacity */
+    seatsTotal: number;
+    /** Minimum ticket price in local currency */
+    priceFrom?: number;
+    /** Currency code (ISO 4217) */
+    currency?: string;
+    /** Additional attributes */
+    attributes: Record<string, string>;
+}
+/** Presentation format for a cinema session */
+type SessionFormat = z.infer<typeof sessionFormatSchema>;
+interface SessionFilter {
+    /** Filter by cinema site */
+    siteId?: string;
+    /** Filter by film */
+    filmId?: string;
+    /** Filter by date (YYYY-MM-DD) */
+    date?: string;
+    /** Filter by date range start */
+    dateFrom?: string;
+    /** Filter by date range end */
+    dateTo?: string;
+    /** Filter by format */
+    format?: SessionFormat;
+    /** Only bookable sessions */
+    bookableOnly?: boolean;
+    /** Maximum results to return */
+    limit?: number;
+    /** Numeric page offset — mutually exclusive with `cursor` */
+    offset?: number;
+    /**
+     * Opaque cursor string from a previous response's `nextCursor` field.
+     * Preferred over `offset` for real-time session data — cursors are stable
+     * when new sessions are added between pages.
+     * Mutually exclusive with `offset`.
+     */
+    cursor?: string;
+}
+interface SessionListResponse {
+    /** List of sessions matching the filter */
+    sessions: Session[];
+    /** Total count of matching sessions */
+    total: number;
+    /** Whether more results are available */
+    hasMore: boolean;
+    /** Numeric offset for the next page (offset-based pagination) */
+    nextOffset?: number;
+    /** Opaque cursor for the next page (cursor-based pagination) */
+    nextCursor?: string;
+}
+/** Seat status in an availability map */
+type SeatStatus = z.infer<typeof seatStatusSchema>;
+/** Individual seat in the auditorium */
+interface Seat {
+    /** Seat identifier */
+    id: string;
+    /** Row label (e.g., "H") */
+    row: string;
+    /** Seat number within the row */
+    number: number;
+    /** Current availability status */
+    status: SeatStatus;
+    /** X position for rendering */
+    x: number;
+    /** Y position for rendering */
+    y: number;
+    /** Seat type/category */
+    type?: string;
+    /** Whether this is an accessible seat */
+    isAccessible: boolean;
+}
+/** Seat availability response for a session */
+interface SeatAvailability {
+    /** Session ID */
+    sessionId: string;
+    /** Screen name */
+    screenName: string;
+    /** All seats in the auditorium */
+    seats: Seat[];
+    /** Number of rows */
+    rowCount: number;
+    /** Screen orientation hint for rendering */
+    screenPosition: 'top' | 'bottom';
+    /** Available seat count */
+    availableCount: number;
+    /** Total seat count */
+    totalCount: number;
+}
+
+/**
+ * Pagination strategy supported by Vista's OCAPI endpoints.
+ *
+ * - `'cursor'` — opaque cursor string returned with each page; preferred for
+ *   real-time data (sessions, orders) where rows may shift between requests.
+ * - `'offset'` — numeric offset/limit; suitable for stable result sets
+ *   (films, sites) where insertion order rarely changes mid-request.
+ */
+type PaginationStrategy = 'cursor' | 'offset';
+/**
+ * Generic paginated response envelope.
+ *
+ * All list endpoints return data wrapped in this shape once pagination
+ * is normalised. The `data` array contains the current page of results;
+ * `hasMore` indicates whether additional pages exist.
+ *
+ * @typeParam T - The resource type contained in each page
+ *
+ * @example
+ * ```typescript
+ * const page: PaginatedResponse<Session> = await client.sessions.list({
+ *   siteId: 'roxy-wellington',
+ *   limit: 25,
+ * });
+ *
+ * console.log(page.data.length);  // up to 25
+ * console.log(page.hasMore);      // true if more pages exist
+ * ```
+ */
+interface PaginatedResponse<T> {
+    /** The current page of results */
+    data: T[];
+    /** Total number of matching results across all pages */
+    total: number;
+    /** Whether additional pages are available */
+    hasMore: boolean;
+    /** Opaque cursor for the next page (cursor-based pagination) */
+    nextCursor?: string;
+    /** Numeric offset for the next page (offset-based pagination) */
+    nextOffset?: number;
+    /** The pagination strategy used for this response */
+    strategy: PaginationStrategy;
+}
+/**
+ * Options for controlling pagination behaviour on list endpoints.
+ */
+interface PaginationParams {
+    /** Maximum number of results per page (default: 50, max: 500) */
+    limit?: number;
+    /** Opaque cursor from a previous response — mutually exclusive with `offset` */
+    cursor?: string;
+    /** Numeric offset — mutually exclusive with `cursor` */
+    offset?: number;
+}
+
+/**
+ * Sessions resource — showtimes, availability, and seat maps.
+ *
+ * @example
+ * ```typescript
+ * const sessions = await client.sessions.list({
+ *   siteId: 'roxy-wellington',
+ *   date: '2026-04-08',
+ * });
+ *
+ * const seats = await client.sessions.availability(sessions[0].id);
+ * ```
+ *
+ * @example Auto-paginate all sessions
+ * ```typescript
+ * for await (const session of client.sessions.listAll({ siteId: 'roxy-wellington' })) {
+ *   console.log(session.filmTitle, session.startTime);
+ * }
+ * ```
+ */
+declare class SessionsResource {
+    private readonly http;
+    constructor(http: TheatricalHTTPClient);
+    /**
+     * List sessions (showtimes) with optional filters.
+     * Response is validated at runtime using Zod — malformed API responses throw a parse error.
+     * @throws {TheatricalError} When the API returns an error response
+     * @throws {z.ZodError} When the response fails schema validation
+     * @see https://developer.vista.co/digital-platform/sessions/
+     */
+    list(filters?: SessionFilter): Promise<SessionListResponse>;
+    /**
+     * List sessions with explicit pagination control.
+     *
+     * Returns a normalised `PaginatedResponse<Session>` envelope that includes
+     * the pagination strategy and cursor/offset for the next page.
+     *
+     * @param filters - Session filters (site, film, date range, etc.)
+     * @param pagination - Page size and cursor/offset position
+     * @returns A single page of sessions with pagination metadata
+     *
+     * @example
+     * ```typescript
+     * const page = await client.sessions.listPaginated(
+     *   { siteId: 'roxy-wellington' },
+     *   { limit: 25 },
+     * );
+     * console.log(page.data.length, page.hasMore);
+     * ```
+     */
+    listPaginated(filters?: SessionFilter, pagination?: PaginationParams): Promise<PaginatedResponse<Session>>;
+    /**
+     * Async generator that automatically paginates through all matching sessions.
+     *
+     * Yields individual `Session` objects, fetching the next page transparently
+     * when the current page is exhausted. Uses offset-based pagination internally
+     * since Vista's session endpoints support numeric offsets.
+     *
+     * @param filters - Session filters (site, film, date range, etc.)
+     * @param pageSize - Number of sessions to fetch per page (default: 50, max: 500)
+     *
+     * @example
+     * ```typescript
+     * const allSessions: Session[] = [];
+     * for await (const session of client.sessions.listAll({ siteId: 'roxy-wellington' })) {
+     *   allSessions.push(session);
+     * }
+     * ```
+     *
+     * @example Collect with early termination
+     * ```typescript
+     * for await (const session of client.sessions.listAll({ date: '2026-04-10' })) {
+     *   if (session.isSoldOut) continue;
+     *   console.log(`${session.filmTitle} — ${session.screenName} @ ${session.startTime}`);
+     *   if (!session.isBookable) break; // stop on first unbookable
+     * }
+     * ```
+     */
+    listAll(filters?: SessionFilter, pageSize?: number): AsyncGenerator<Session, void, undefined>;
+    /**
+     * Get a single session by ID.
+     * Response is validated at runtime using Zod.
+     */
+    get(sessionId: string): Promise<Session>;
+    /**
+     * Get seat availability for a session.
+     * Returns the complete auditorium seat map with status for each seat.
+     * Response is validated at runtime using Zod.
+     */
+    availability(sessionId: string): Promise<SeatAvailability>;
+}
+
+/**
+ * Zod schema for a cinema screen/auditorium.
+ * `formats` is a list of presentation formats (e.g. '2D', 'IMAX', 'DOLBY_ATMOS').
+ */
+declare const screenSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    seatCount: z.ZodNumber;
+    formats: z.ZodArray<z.ZodString, "many">;
+    isAccessible: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    isAccessible: boolean;
+    name: string;
+    seatCount: number;
+    formats: string[];
+}, {
+    id: string;
+    isAccessible: boolean;
+    name: string;
+    seatCount: number;
+    formats: string[];
+}>;
+/**
+ * Zod schema for site booking and operational configuration.
+ */
+declare const siteConfigSchema: z.ZodObject<{
+    bookingLeadTime: z.ZodNumber;
+    maxTicketsPerOrder: z.ZodNumber;
+    loyaltyEnabled: z.ZodBoolean;
+    fnbEnabled: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    bookingLeadTime: number;
+    maxTicketsPerOrder: number;
+    loyaltyEnabled: boolean;
+    fnbEnabled: boolean;
+}, {
+    bookingLeadTime: number;
+    maxTicketsPerOrder: number;
+    loyaltyEnabled: boolean;
+    fnbEnabled: boolean;
+}>;
+/**
+ * Zod schema for a cinema site (location).
+ * Validates the full shape of a site returned from Vista's OCAPI.
+ */
+declare const siteSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    address: z.ZodObject<{
+        line1: z.ZodString;
+        line2: z.ZodOptional<z.ZodString>;
+        city: z.ZodString;
+        state: z.ZodOptional<z.ZodString>;
+        postalCode: z.ZodString;
+        country: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        line1: string;
+        city: string;
+        postalCode: string;
+        country: string;
+        line2?: string | undefined;
+        state?: string | undefined;
+    }, {
+        line1: string;
+        city: string;
+        postalCode: string;
+        country: string;
+        line2?: string | undefined;
+        state?: string | undefined;
+    }>;
+    location: z.ZodObject<{
+        latitude: z.ZodNumber;
+        longitude: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        latitude: number;
+        longitude: number;
+    }, {
+        latitude: number;
+        longitude: number;
+    }>;
+    screens: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        seatCount: z.ZodNumber;
+        formats: z.ZodArray<z.ZodString, "many">;
+        isAccessible: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        isAccessible: boolean;
+        name: string;
+        seatCount: number;
+        formats: string[];
+    }, {
+        id: string;
+        isAccessible: boolean;
+        name: string;
+        seatCount: number;
+        formats: string[];
+    }>, "many">;
+    config: z.ZodObject<{
+        bookingLeadTime: z.ZodNumber;
+        maxTicketsPerOrder: z.ZodNumber;
+        loyaltyEnabled: z.ZodBoolean;
+        fnbEnabled: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        bookingLeadTime: number;
+        maxTicketsPerOrder: number;
+        loyaltyEnabled: boolean;
+        fnbEnabled: boolean;
+    }, {
+        bookingLeadTime: number;
+        maxTicketsPerOrder: number;
+        loyaltyEnabled: boolean;
+        fnbEnabled: boolean;
+    }>;
+    timezone: z.ZodString;
+    currency: z.ZodString;
+    isActive: z.ZodBoolean;
+    amenities: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /** Amenity identifier (e.g. 'parking', 'bar', 'vip_lounge', 'imax') */
+        id: z.ZodString;
+        /** Human-readable label */
+        label: z.ZodString;
+        /** Optional icon key for rendering */
+        icon: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        label: string;
+        icon?: string | undefined;
+    }, {
+        id: string;
+        label: string;
+        icon?: string | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    config: {
+        bookingLeadTime: number;
+        maxTicketsPerOrder: number;
+        loyaltyEnabled: boolean;
+        fnbEnabled: boolean;
+    };
+    id: string;
+    currency: string;
+    name: string;
+    address: {
+        line1: string;
+        city: string;
+        postalCode: string;
+        country: string;
+        line2?: string | undefined;
+        state?: string | undefined;
+    };
+    location: {
+        latitude: number;
+        longitude: number;
+    };
+    screens: {
+        id: string;
+        isAccessible: boolean;
+        name: string;
+        seatCount: number;
+        formats: string[];
+    }[];
+    timezone: string;
+    isActive: boolean;
+    amenities?: {
+        id: string;
+        label: string;
+        icon?: string | undefined;
+    }[] | undefined;
+}, {
+    config: {
+        bookingLeadTime: number;
+        maxTicketsPerOrder: number;
+        loyaltyEnabled: boolean;
+        fnbEnabled: boolean;
+    };
+    id: string;
+    currency: string;
+    name: string;
+    address: {
+        line1: string;
+        city: string;
+        postalCode: string;
+        country: string;
+        line2?: string | undefined;
+        state?: string | undefined;
+    };
+    location: {
+        latitude: number;
+        longitude: number;
+    };
+    screens: {
+        id: string;
+        isAccessible: boolean;
+        name: string;
+        seatCount: number;
+        formats: string[];
+    }[];
+    timezone: string;
+    isActive: boolean;
+    amenities?: {
+        id: string;
+        label: string;
+        icon?: string | undefined;
+    }[] | undefined;
+}>;
+/** Cinema screen/auditorium configuration */
+type Screen = z.infer<typeof screenSchema>;
+/** Site booking and operational configuration */
+type SiteConfig = z.infer<typeof siteConfigSchema>;
+/**
+ * A cinema site (location) — the physical venue with screens, address, and config.
+ *
+ * @example
+ * ```typescript
+ * const sites = await client.sites.list();
+ * const active = sites.filter(s => s.isActive);
+ * ```
+ */
+type Site = z.infer<typeof siteSchema>;
+
+/**
+ * Sites resource — cinema locations, screens, and geographic discovery.
+ *
+ * @example
+ * ```typescript
+ * const sites = await client.sites.list();
+ * const active = sites.filter(s => s.isActive);
+ * ```
+ *
+ * @example Geographic discovery
+ * ```typescript
+ * // Find cinemas within 10 km of central Wellington
+ * const nearby = await client.sites.nearby(-41.2865, 174.7762, 10);
+ * ```
+ */
+declare class SitesResource {
+    private readonly http;
+    constructor(http: TheatricalHTTPClient);
+    /**
+     * List all cinema sites, with optional search query or geographic filter.
+     * Response is validated at runtime using Zod.
+     *
+     * @param filters - Optional filters: `query` (text search), `latitude`/`longitude`/`radius`
+     * @returns Array of cinema sites
+     * @throws {TheatricalError} When the API returns an error response
+     * @throws {z.ZodError} When the response fails schema validation
+     *
+     * @example
+     * ```typescript
+     * const sites = await client.sites.list({ query: 'Embassy' });
+     * ```
+     */
+    list(filters?: {
+        query?: string;
+        latitude?: number;
+        longitude?: number;
+        radius?: number;
+    }): Promise<Site[]>;
+    /**
+     * Get a single cinema site by ID.
+     * Response is validated at runtime using Zod.
+     *
+     * @param siteId - Vista site identifier
+     * @returns The site record
+     *
+     * @example
+     * ```typescript
+     * const roxy = await client.sites.get('site_roxy_wellington');
+     * console.log(roxy.screens.length); // number of auditoriums
+     * ```
+     */
+    get(siteId: string): Promise<Site>;
+    /**
+     * Get the screen (auditorium) configurations for a site.
+     * Returns each screen's capacity, supported formats, and accessibility status.
+     * Response is validated at runtime using Zod.
+     *
+     * @param siteId - Vista site identifier
+     * @returns Array of screen configurations
+     *
+     * @example
+     * ```typescript
+     * const screens = await client.sites.screens('site_embassy_wellington');
+     * const imax = screens.find(s => s.formats.includes('IMAX'));
+     * ```
+     */
+    screens(siteId: string): Promise<Screen[]>;
+    /**
+     * Find cinema sites within a geographic radius.
+     *
+     * Returns sites sorted by distance from the given coordinates.
+     * Uses Vista's OCAPI geographic search which accepts decimal lat/lng
+     * and a radius in kilometres.
+     *
+     * @param latitude - Decimal latitude of the search centre (−90 to 90)
+     * @param longitude - Decimal longitude of the search centre (−180 to 180)
+     * @param radiusKm - Search radius in kilometres
+     * @returns Sites within the radius, sorted nearest-first
+     *
+     * @example
+     * ```typescript
+     * // Find cinemas within 5 km of Roxy Cinema Wellington
+     * const nearby = await client.sites.nearby(-41.3007, 174.7766, 5);
+     * console.log(nearby.map(s => s.name));
+     * ```
+     *
+     * @example Discover cinemas near central Auckland
+     * ```typescript
+     * const auckland = await client.sites.nearby(-36.8509, 174.7645, 10);
+     * ```
+     */
+    nearby(latitude: number, longitude: number, radiusKm: number): Promise<Site[]>;
+}
+
+/** Bounded genre enum. Unknown values from Vista's API indicate the schema needs updating. */
+declare const GENRES: readonly ["action", "adventure", "animation", "comedy", "crime", "documentary", "drama", "family", "fantasy", "horror", "musical", "mystery", "romance", "sci-fi", "thriller", "war", "western"];
+type Genre = typeof GENRES[number];
+/** Bounded screening format enum. */
+declare const FILM_FORMATS: readonly ["2D", "3D", "IMAX", "IMAX 3D", "4DX", "Dolby Atmos", "ScreenX"];
+type FilmFormat = typeof FILM_FORMATS[number];
+/** Bounded language code enum (BCP-47 subset for NZ market). */
+declare const FILM_LANGUAGES: readonly ["en", "es", "fr", "de", "ja", "ko", "zh", "hi", "te", "mi"];
+type FilmLanguage = typeof FILM_LANGUAGES[number];
+/**
+ * Age classification rating (e.g., NZ: G, PG, M, R13, R16, R18;
+ * US: G, PG, PG-13, R, NC-17).
+ */
+interface Rating {
+    /** Rating classification code (e.g., 'M', 'PG-13', 'R16') */
+    classification: string;
+    /** Human-readable content advisory (e.g., 'Violence, offensive language') */
+    description?: string;
+}
+/** An actor appearing in the film */
+interface CastMember {
+    /** Full name of the actor */
+    name: string;
+    /** Character name or role description */
+    role?: string;
+}
+/** A crew member (director, writer, cinematographer, etc.) */
+interface CrewMember {
+    name: string;
+    department: string;
+    job: string;
+}
+/** A rating from a specific source (IMDB, Rotten Tomatoes, Metacritic, etc.) */
+interface FilmRating {
+    source: string;
+    score: string;
+    outOf?: string;
+}
+/**
+ * A film available for screening — core list representation.
+ *
+ * This is the shape returned by list endpoints (`nowShowing`, `comingSoon`, `search`).
+ * For full detail including crew, ratings, and formats, use `FilmDetail` via `getDetail()`.
+ */
+interface Film {
+    /** Unique film identifier (UUID) */
+    id: string;
+    /** Display title in the local market */
+    title: string;
+    /** Marketing synopsis / plot summary */
+    synopsis: string;
+    /** Genre classifications */
+    genres: Genre[];
+    /** Runtime in minutes */
+    runtime: number;
+    /** Age classification rating */
+    rating: Rating;
+    /** Theatrical release date (ISO 8601 date string) */
+    releaseDate: string;
+    /** URL to the film's poster image */
+    posterUrl?: string;
+    /** URL to the official trailer */
+    trailerUrl?: string;
+    /** Principal cast members */
+    cast: CastMember[];
+    /** Primary director name */
+    director: string;
+    /** Distribution company */
+    distributor?: string;
+    /** Whether the film is currently screening */
+    isNowShowing: boolean;
+    /** Whether the film is announced but not yet released */
+    isComingSoon: boolean;
+}
+/**
+ * Full film detail — returned by `films.getDetail(id)`.
+ *
+ * Extends the base Film with crew, multiple rating sources,
+ * available formats, language options, and production metadata.
+ */
+interface FilmDetail extends Film {
+    crew: CrewMember[];
+    ratings: FilmRating[];
+    formats: FilmFormat[];
+    languages: FilmLanguage[];
+    originalTitle?: string;
+    productionCountries?: string[];
+    budget?: number;
+    boxOffice?: number;
+    website?: string;
+}
+/** Basic filter options for film list and search endpoints */
+interface FilmFilter {
+    /** Restrict results to a specific cinema site */
+    siteId?: string;
+    /** Filter by genre classification */
+    genre?: Genre;
+    /** Free-text search across title and synopsis */
+    query?: string;
+    /** Only return films currently screening */
+    nowShowing?: boolean;
+    /** Only return upcoming / announced films */
+    comingSoon?: boolean;
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+/**
+ * Extended search filters for `films.advancedSearch()`.
+ *
+ * Adds format, language, rating, runtime range, date range, and sorting
+ * on top of the base FilmFilter fields.
+ */
+interface FilmSearchFilter extends FilmFilter {
+    /** Filter by age rating classification (e.g., 'PG', 'M', 'R16') */
+    ratingClassification?: string;
+    /** Filter by screening format (e.g., 'IMAX', '3D', 'Dolby Atmos') */
+    format?: FilmFormat;
+    /** Filter by audio/subtitle language (ISO 639-1 code) */
+    language?: FilmLanguage;
+    /** Films released on or after this date (ISO 8601) */
+    releaseDateFrom?: string;
+    /** Films released on or before this date (ISO 8601) */
+    releaseDateTo?: string;
+    /** Minimum runtime in minutes */
+    minRuntime?: number;
+    /** Maximum runtime in minutes */
+    maxRuntime?: number;
+    /** Sort field */
+    sortBy?: 'title' | 'releaseDate' | 'runtime' | 'popularity';
+    /** Sort direction */
+    sortOrder?: 'asc' | 'desc';
+}
+
+/**
+ * Films resource — now showing, coming soon, search, and detailed film information.
+ *
+ * Provides access to the Vista OCAPI film catalogue. Supports browsing
+ * current and upcoming releases, searching with rich filters (genre, format,
+ * language, rating, runtime), and retrieving full film detail including
+ * cast, crew, and ratings from multiple sources.
+ */
+declare class FilmsResource {
+    private readonly http;
+    constructor(http: TheatricalHTTPClient);
+    /**
+     * Parse and validate a raw film response from the API.
+     * Throws a ZodError if the response doesn't match the expected shape.
+     */
+    private parseFilm;
+    /**
+     * Parse and validate an array of films from the API.
+     */
+    private parseFilms;
+    /**
+     * Parse and validate a full film detail response.
+     */
+    private parseFilmDetail;
+    /**
+     * List films currently showing at a given site (or across all sites).
+     *
+     * @param filters - Optional site filter
+     * @returns Array of films currently in cinemas
+     */
+    nowShowing(filters?: {
+        siteId?: string;
+    }): Promise<Film[]>;
+    /**
+     * List films coming soon — announced but not yet in cinemas.
+     *
+     * @param filters - Optional site filter
+     * @returns Array of upcoming films
+     */
+    comingSoon(filters?: {
+        siteId?: string;
+    }): Promise<Film[]>;
+    /**
+     * Retrieve a film by its unique identifier.
+     *
+     * @param filmId - The UUID of the film
+     * @returns The base film record
+     */
+    get(filmId: string): Promise<Film>;
+    /**
+     * Retrieve full film detail including cast, crew, ratings, formats, and languages.
+     *
+     * This returns the extended `FilmDetail` type with nested crew arrays,
+     * multiple rating sources (IMDB, Rotten Tomatoes, Metacritic), available
+     * screening formats, and language options.
+     *
+     * @param filmId - The UUID of the film
+     * @returns Full film detail with cast, crew, and ratings
+     */
+    getDetail(filmId: string): Promise<FilmDetail>;
+    /**
+     * Search films with basic filters.
+     *
+     * @throws {TheatricalError} When the API returns an error response
+     * @throws {z.ZodError} When the response fails schema validation
+     * @param filters - Genre, query string, site, and showing status filters
+     * @returns Array of matching films
+     */
+    search(filters: FilmFilter): Promise<Film[]>;
+    /**
+     * Advanced film search with extended filters.
+     *
+     * Supports filtering by format (IMAX, 3D, Dolby Atmos), language,
+     * rating classification, runtime range, release date range, and sorting.
+     *
+     * @param filters - Extended search filters including format, language, runtime range, sorting
+     * @returns Array of matching films
+     */
+    advancedSearch(filters: FilmSearchFilter): Promise<Film[]>;
+}
+
+/**
+ * Represents the lifecycle state of a cinema booking order.
+ *
+ * State transitions follow a strict flow:
+ * ```
+ * draft → pending → confirmed → completed
+ *       ↗ held ↗    ↘ cancelled
+ *        confirmed → refunded
+ * ```
+ *
+ * The `held` state is a Vista-specific pause: seats are reserved but payment not yet initiated.
+ * A held order transitions to `pending` when the hold window elapses or the caller invokes release.
+ */
+type OrderStatus = 'draft' | 'pending' | 'held' | 'confirmed' | 'completed' | 'cancelled' | 'refunded';
+/** A single ticket within a booking order */
+interface Ticket {
+    id: string;
+    type: string;
+    seatId: string;
+    seatLabel: string;
+    price: number;
+    discount?: number;
+}
+/** A concession or merchandise item added to an order */
+interface OrderItem {
+    id: string;
+    name: string;
+    category: string;
+    quantity: number;
+    unitPrice: number;
+    totalPrice: number;
+}
+/** A booking order — the transactional core of the cinema experience */
+interface Order {
+    id: string;
+    sessionId: string;
+    status: OrderStatus;
+    tickets: Ticket[];
+    items: OrderItem[];
+    subtotal: number;
+    tax: number;
+    discount: number;
+    total: number;
+    currency: string;
+    loyaltyMemberId?: string;
+    loyaltyPointsEarned?: number;
+    loyaltyPointsRedeemed?: number;
+    createdAt: string;
+    updatedAt?: string;
+    /** ISO timestamp when the order entered the `held` state */
+    heldAt?: string;
+    /** ISO timestamp when the hold expires — after this the order auto-transitions to `pending` */
+    heldUntil?: string;
+    confirmedAt?: string;
+    completedAt?: string;
+    cancelledAt?: string;
+    refundedAt?: string;
+}
+/**
+ * Input for replacing tickets on a draft order.
+ *
+ * Call `orders.addTickets()` after creating a draft order to assign specific seats.
+ * The Vista OCAPI replaces all existing tickets on the order — include every desired
+ * ticket in a single call to avoid partial state.
+ */
+interface AddTicketsInput {
+    tickets: Array<{
+        /** Ticket category — e.g. `'adult'`, `'child'`, `'senior'` */
+        type: string;
+        /** Seat ID from the session availability response */
+        seatId: string;
+    }>;
+}
+/**
+ * Input for adding concession or merchandise items to an order.
+ *
+ * Items can be added at any point before the order is confirmed.
+ * Duplicate `menuItemId` entries are merged — quantities accumulate.
+ */
+interface AddItemsInput {
+    items: Array<{
+        /** Menu item ID from the F&B menu response */
+        menuItemId: string;
+        /** Number of units to add (must be ≥ 1) */
+        quantity: number;
+    }>;
+}
+/**
+ * Input for applying a loyalty account to an order.
+ *
+ * Attaches a loyalty member to earn points on the purchase. Optionally redeems
+ * accumulated points to reduce the order total — Vista enforces per-transaction
+ * redemption limits based on the member's tier.
+ */
+interface ApplyLoyaltyInput {
+    /** Loyalty member ID to attach to this order */
+    memberId: string;
+    /** Number of loyalty points to redeem — reduces order total at ~1pt = $0.01 NZD */
+    pointsToRedeem?: number;
+}
+/** Filter parameters for querying order history */
+interface OrderHistoryFilter {
+    /** Filter by order status */
+    status?: OrderStatus;
+    /** ISO date string — orders created after this date */
+    since?: string;
+    /** ISO date string — orders created before this date */
+    until?: string;
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Pagination cursor from a previous response */
+    cursor?: string;
+}
+
+/**
+ * Input for creating a new draft order.
+ *
+ * A draft order locks the requested seats for a short window (typically 10 minutes)
+ * while the customer completes checkout. If the order is not confirmed within that
+ * window, Vista automatically cancels it and releases the seats.
+ *
+ * @example
+ * ```typescript
+ * const order = await client.orders.create({
+ *   sessionId: 'sess_abc123',
+ *   tickets: [
+ *     { type: 'adult', seatId: 'seat_d5' },
+ *     { type: 'child', seatId: 'seat_d6' },
+ *   ],
+ *   loyaltyMemberId: 'mem_xyz',
+ * });
+ * ```
+ */
+interface CreateOrderInput {
+    /** ID of the session (showtime) to book */
+    sessionId: string;
+    /** Tickets to reserve — each entry specifies a ticket type and the seat to assign */
+    tickets: Array<{
+        /** Ticket category — e.g. `'adult'`, `'child'`, `'senior'`, `'concession'` */
+        type: string;
+        /** Seat ID from the availability response (e.g. `'seat_d5'`) */
+        seatId: string;
+    }>;
+    /** Optional concession or merchandise items to include at order creation time */
+    items?: Array<{
+        menuItemId: string;
+        quantity: number;
+    }>;
+    /** Loyalty member ID — attach to earn points on this booking */
+    loyaltyMemberId?: string;
+}
+/**
+ * Orders resource — the full booking lifecycle.
+ *
+ * Covers the entire booking flow for Vista OCAPI:
+ * create → add tickets → optionally add F&B → apply loyalty → confirm → complete.
+ * Orders can also be cancelled or refunded depending on their current state.
+ *
+ * All responses are validated at runtime using Zod schemas to ensure
+ * the API response matches the expected shape before reaching application code.
+ */
+declare class OrdersResource {
+    private readonly http;
+    constructor(http: TheatricalHTTPClient);
+    /**
+     * Parse and validate a raw order response from the API.
+     * Throws a ZodError if the response doesn't match the expected shape.
+     */
+    private parseOrder;
+    /**
+     * Parse and validate a paginated order response from the API.
+     */
+    private parsePaginatedOrders;
+    /**
+     * Create a new draft order for a session.
+     *
+     * @throws {TheatricalError} When the API returns an error response
+     * @throws {z.ZodError} When the response fails schema validation
+     * @param input - Session ID, initial tickets, optional F   * @param input - Session ID, initial tickets, optional F&B items, optional loyalty memberB items, optional loyalty member
+     * @returns The newly created order in 'draft' status
+     */
+    create(input: CreateOrderInput): Promise<Order>;
+    /**
+     * Retrieve an order by its unique identifier.
+     *
+     * @param orderId - The UUID of the order to retrieve
+     */
+    get(orderId: string): Promise<Order>;
+    /**
+     * Set tickets on a draft order. Each ticket specifies a seat and ticket type.
+     * The Vista OCAPI replaces all existing tickets — pass the full desired set in one call.
+     *
+     * @param orderId - The UUID of the draft order
+     * @param input - Tickets to set (replaces any previously assigned tickets)
+     * @returns The updated order with the new ticket set
+     */
+    addTickets(orderId: string, input: AddTicketsInput): Promise<Order>;
+    /**
+     * Add concession or merchandise items to an order.
+     * F&B items can be added to orders in 'draft' or 'pending' status.
+     *
+     * @param orderId - The UUID of the order
+     * @param input - Items to add (menuItemId + quantity pairs)
+     * @returns The updated order with new items included
+     */
+    addItems(orderId: string, input: AddItemsInput): Promise<Order>;
+    /**
+     * Confirm an order, transitioning it from 'pending' to 'confirmed'.
+     * This locks in the seat selection and pricing.
+     *
+     * @param orderId - The UUID of the order to confirm
+     */
+    confirm(orderId: string): Promise<Order>;
+    /**
+     * Cancel an order. Can be applied to 'pending' or 'confirmed' orders.
+     * Releases any held seats back to the pool.
+     *
+     * @param orderId - The UUID of the order to cancel
+     */
+    cancel(orderId: string): Promise<Order>;
+    /**
+     * Apply a loyalty membership discount to an order.
+     * Links the member to the order and optionally redeems loyalty points
+     * for a discount on the total.
+     *
+     * @param orderId - The UUID of the order
+     * @param input - Loyalty member ID and optional points to redeem
+     * @returns The updated order with loyalty discount applied
+     */
+    applyLoyalty(orderId: string, input: ApplyLoyaltyInput): Promise<Order>;
+    /**
+     * Request a refund for a confirmed or completed order.
+     * Triggers the refund workflow in Vista's payment system.
+     *
+     * @param orderId - The UUID of the order to refund
+     */
+    refund(orderId: string): Promise<Order>;
+    /**
+     * Mark a confirmed order as completed (e.g., after the screening).
+     *
+     * @param orderId - The UUID of the confirmed order
+     */
+    complete(orderId: string): Promise<Order>;
+    /**
+     * Retrieve order history for a loyalty member.
+     * Returns a paginated list of orders, newest first.
+     *
+     * @param memberId - The loyalty member's unique identifier
+     * @param filter - Optional filters for status, date range, and pagination
+     */
+    history(memberId: string, filter?: OrderHistoryFilter): Promise<PaginatedResponse<Order>>;
+}
+
+/** Loyalty tier levels available in Vista cinema programs. */
+type LoyaltyTierName = 'Bronze' | 'Silver' | 'Gold' | 'Platinum';
+/** A loyalty program tier with benefits and point thresholds. */
+interface LoyaltyTier {
+    id: string;
+    name: LoyaltyTierName;
+    /** Numeric rank: 1 = Bronze … 4 = Platinum */
+    level: number;
+    benefits: string[];
+    /** Lifetime points required to reach this tier. */
+    pointsThreshold: number;
+}
+/** A loyalty program member. */
+interface LoyaltyMember {
+    id: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+    tier: LoyaltyTier;
+    /** Current redeemable points balance. */
+    points: number;
+    /** All-time accumulated points (never decremented). */
+    lifetimePoints: number;
+    memberSince: string;
+    /** Linked subscription plan ID, if any. */
+    subscriptionId?: string;
+    /** ISO-8601 date of most recent transaction. */
+    lastActivityDate?: string;
+    /** Whether the member account is currently active. */
+    active: boolean;
+}
+/** A single points earn or redeem transaction. */
+interface PointsTransaction {
+    id: string;
+    memberId: string;
+    type: 'earn' | 'redeem' | 'adjust' | 'expire';
+    points: number;
+    /** Signed net change — negative for redemptions and expirations. */
+    balanceAfter: number;
+    description: string;
+    /** ISO-8601 datetime */
+    createdAt: string;
+    /** Order reference for earn/redeem transactions, if applicable. */
+    orderId?: string;
+    /** Cinema site reference, if applicable. */
+    siteId?: string;
+}
+/** An option that members can redeem points for. */
+interface RedemptionOption {
+    id: string;
+    name: string;
+    description: string;
+    /** Points cost to redeem. */
+    pointsCost: number;
+    category: 'ticket' | 'concession' | 'upgrade' | 'merchandise';
+    /** Whether the option is currently available. */
+    available: boolean;
+    /** ISO-8601 expiry date of the offer, if limited. */
+    expiresAt?: string;
+}
+/** Input payload for redeeming points against an option. */
+interface RedeemPointsInput {
+    optionId: string;
+    /** Order to apply the redemption to, if applicable. */
+    orderId?: string;
+    /** Quantity of the option to redeem (default 1). */
+    quantity?: number;
+}
+/** Filters for querying a member's transaction history. */
+interface PointsHistoryFilter {
+    type?: PointsTransaction['type'];
+    /** ISO-8601 start date (inclusive) */
+    from?: string;
+    /** ISO-8601 end date (inclusive) */
+    to?: string;
+    limit?: number;
+    offset?: number;
+}
+
+/**
+ * Loyalty resource — member management, points, tiers.
+ *
+ * Wraps the Vista OCAPI loyalty endpoints for full member lifecycle management:
+ * authentication, balance queries, transaction history, and points redemption.
+ */
+declare class LoyaltyResource {
+    private readonly http;
+    constructor(http: TheatricalHTTPClient);
+    /**
+     * Fetch a loyalty member by their unique ID.
+     *
+     * @param memberId - Vista loyalty member identifier
+     * @throws {TheatricalError} When the API returns an error response
+     */
+    getMember(memberId: string): Promise<LoyaltyMember>;
+    /**
+     * Authenticate a member using their email address and password (cookie-based
+     * session). Returns the authenticated member record on success.
+     *
+     * @param email    - Member's registered email
+     * @param password - Account password (transmitted over TLS)
+     */
+    authenticate(email: string, password: string): Promise<LoyaltyMember>;
+    /**
+     * Return the current redeemable points balance for a member.
+     *
+     * @param memberId - Vista loyalty member identifier
+     */
+    getPointsBalance(memberId: string): Promise<{
+        points: number;
+        lifetimePoints: number;
+    }>;
+    /**
+     * Retrieve a paginated transaction history for a member.
+     *
+     * @param memberId - Vista loyalty member identifier
+     * @param filter   - Optional date range, type, and pagination filters
+     */
+    getHistory(memberId: string, filter?: PointsHistoryFilter): Promise<PaginatedResponse<PointsTransaction>>;
+    /**
+     * List available redemption options for the loyalty program.
+     * Options are filtered to those the member is eligible for based on their
+     * tier and current points balance.
+     *
+     * @param memberId - Vista loyalty member identifier
+     */
+    listRedemptionOptions(memberId: string): Promise<RedemptionOption[]>;
+    /**
+     * Redeem points against a catalog option for a member.
+     * Deducts points from the member's balance and applies the benefit.
+     *
+     * @param memberId - Vista loyalty member identifier
+     * @param input    - Redemption option, optional order linkage, and quantity
+     */
+    redeemPoints(memberId: string, input: RedeemPointsInput): Promise<PointsTransaction>;
+}
+
+/** Billing interval for a subscription plan. */
+type SubscriptionInterval = 'monthly' | 'annual';
+/** Current lifecycle state of a member's subscription. */
+type SubscriptionStatus = 'active' | 'paused' | 'cancelled' | 'expired' | 'pending';
+/** Category of a subscription benefit. */
+type BenefitCategory = 'booking' | 'concession' | 'companion' | 'priority' | 'exclusive';
+/**
+ * A specific benefit included with a subscription plan.
+ *
+ * Benefits define the concrete perks of a plan beyond the base booking
+ * allowance — e.g., companion passes, F&B discounts, priority booking windows.
+ */
+interface SubscriptionBenefit {
+    id: string;
+    category: BenefitCategory;
+    name: string;
+    description: string;
+    /** Maximum number of times this benefit may be used per billing period. */
+    usesPerPeriod?: number;
+    /** Whether this benefit is currently active on the plan. */
+    active: boolean;
+}
+/**
+ * A subscribable cinema pass plan (e.g. Hoyts LoyaltyCinema Pass, Event Select).
+ *
+ * Plans define pricing, booking allowances, and the list of benefits included
+ * for subscribers. Equivalent to AMC A-List or Cineworld Unlimited in structure.
+ */
+interface SubscriptionPlan {
+    id: string;
+    name: string;
+    description: string;
+    price: number;
+    currency: string;
+    interval: SubscriptionInterval;
+    /** Number of bookings included per billing period. Undefined = unlimited. */
+    bookingsIncluded?: number;
+    benefits: SubscriptionBenefit[];
+    /** Whether new subscriptions can currently be purchased. */
+    available: boolean;
+    /** Minimum commitment period in months (e.g. 3 for lock-in plans). */
+    minimumTermMonths?: number;
+}
+/**
+ * Usage statistics for a member's active subscription in the current period.
+ */
+interface SubscriptionUsage {
+    subscriptionId: string;
+    memberId: string;
+    /** ISO-8601 start of the current billing period. */
+    periodStart: string;
+    /** ISO-8601 end of the current billing period. */
+    periodEnd: string;
+    bookingsUsed: number;
+    /** Null when the plan has unlimited bookings. */
+    bookingsIncluded: number | null;
+    /** Derived: bookingsIncluded - bookingsUsed. Null for unlimited plans. */
+    bookingsRemaining: number | null;
+    /** Per-benefit usage counts keyed by benefit ID. */
+    benefitUsage: Record<string, number>;
+}
+/**
+ * A member's active or historical subscription record.
+ */
+interface MemberSubscription {
+    id: string;
+    planId: string;
+    plan?: SubscriptionPlan;
+    memberId: string;
+    status: SubscriptionStatus;
+    /** ISO-8601 date the subscription started. */
+    startDate: string;
+    /** ISO-8601 date of the next renewal. Null if cancelled or expired. */
+    renewalDate: string | null;
+    /** ISO-8601 date the subscription was cancelled, if applicable. */
+    cancelledAt?: string;
+    /** ISO-8601 date the subscription expires, if applicable. */
+    expiresAt?: string;
+    /** Whether auto-renewal is enabled. */
+    autoRenew: boolean;
+    /** Shorthand usage for current period (populated on detail views). */
+    usage?: SubscriptionUsage;
+}
+/**
+ * Input for suspending a member's subscription temporarily.
+ */
+interface SuspendSubscriptionInput {
+    /** ISO-8601 date to resume the subscription. Required for timed suspension. */
+    resumeDate?: string;
+    reason?: string;
+}
+/**
+ * Input for cancelling a member's subscription.
+ */
+interface CancelSubscriptionInput {
+    /** When true, cancel immediately. When false, cancel at end of period. */
+    immediate?: boolean;
+    reason?: string;
+}
+
+/**
+ * Subscriptions resource — cinema pass plans and member subscription lifecycle.
+ *
+ * Wraps the Vista OCAPI subscription endpoints, covering plan discovery,
+ * member subscription state, usage tracking, benefit eligibility checks,
+ * and administrative actions (suspend, cancel).
+ */
+declare class SubscriptionsResource {
+    private readonly http;
+    constructor(http: TheatricalHTTPClient);
+    /**
+     * List all available subscription plans for a Vista site.
+     *
+     * Returns only plans that are available for new subscriptions unless
+     * {@link includeUnavailable} is set to true (useful for admin UIs).
+     *
+     * @param siteId            - Vista site identifier to scope plans to
+     * @param includeUnavailable - When true, include discontinued plans
+     */
+    listPlans(siteId?: string, includeUnavailable?: boolean): Promise<SubscriptionPlan[]>;
+    /**
+     * Retrieve the active (or most recent) subscription for a member.
+     *
+     * @param memberId - Vista loyalty member identifier
+     */
+    getMemberSubscription(memberId: string): Promise<MemberSubscription>;
+    /**
+     * Get usage statistics for a member's subscription in the current billing period.
+     *
+     * Returns booking counts, remaining allowance, and per-benefit usage.
+     * Use this before allowing a booking to check whether the member has
+     * bookings remaining under their plan.
+     *
+     * @param memberId - Vista loyalty member identifier
+     */
+    getUsage(memberId: string): Promise<SubscriptionUsage>;
+    /**
+     * Check whether a member is eligible to use a specific benefit.
+     *
+     * Returns true if the benefit is included in their plan, is currently active,
+     * and the member has remaining uses for the current period.
+     *
+     * @param memberId  - Vista loyalty member identifier
+     * @param benefitId - Benefit ID from the plan's benefits array
+     */
+    checkBenefitEligibility(memberId: string, benefitId: string): Promise<{
+        eligible: boolean;
+        usesRemaining: number | null;
+        reason?: string;
+    }>;
+    /**
+     * Suspend a member's subscription temporarily.
+     *
+     * The subscription status transitions to `paused`. Billing is paused for the
+     * suspension period. If {@link SuspendSubscriptionInput.resumeDate} is
+     * provided, the subscription will auto-resume on that date; otherwise it must
+     * be manually resumed.
+     *
+     * @param memberId - Vista loyalty member identifier
+     * @param input    - Optional resume date and reason
+     */
+    suspend(memberId: string, input?: SuspendSubscriptionInput): Promise<MemberSubscription>;
+    /**
+     * Cancel a member's subscription.
+     *
+     * By default cancels at the end of the current billing period. Set
+     * {@link CancelSubscriptionInput.immediate} to `true` for an immediate
+     * cancellation with no refund.
+     *
+     * @param memberId - Vista loyalty member identifier
+     * @param input    - Whether to cancel immediately and optional reason
+     */
+    cancel(memberId: string, input?: CancelSubscriptionInput): Promise<MemberSubscription>;
+}
+
+/** Ticket type grouping — matches Vista OCAPI ticket type categories. */
+type TicketCategory = 'adult' | 'child' | 'senior' | 'student' | 'family' | 'concession' | 'loyalty-member';
+interface TicketType {
+    id: string;
+    name: string;
+    description?: string;
+    /** Base price in minor currency units (e.g., cents). */
+    price: number;
+    currency: string;
+    category: TicketCategory;
+    isDefault: boolean;
+    requiresLoyalty: boolean;
+    /** Minimum age for this ticket type (e.g. senior >= 65). */
+    minimumAge?: number;
+    /** Maximum age (e.g. child <= 14). */
+    maximumAge?: number;
+    /** Whether this ticket type is currently purchasable. */
+    isAvailable: boolean;
+}
+interface TicketTypeFilter {
+    sessionId: string;
+    /** Filter by category (e.g., only loyalty-eligible types). */
+    category?: TicketCategory;
+    /** Exclude unavailable ticket types. Defaults to true. */
+    availableOnly?: boolean;
+}
+/**
+ * Regional tax configuration for price display.
+ *
+ * NZ cinema operators present tax-inclusive prices; Australian operators
+ * sometimes break GST out separately in B2B contexts.
+ */
+interface TaxConfig {
+    /** ISO 4217 currency code. */
+    currency: string;
+    /** Tax rate as a decimal fraction (e.g. 0.15 for 15% NZ GST). */
+    rate: number;
+    /** Label shown on receipts (e.g. "GST", "VAT"). */
+    label: string;
+    /**
+     * When true, all prices are tax-inclusive (consumer-facing display).
+     * When false, tax is added on top (B2B / booking-system context).
+     */
+    inclusive: boolean;
+}
+type DiscountSource = 'loyalty-tier' | 'coupon' | 'promo' | 'member' | 'employee' | 'group';
+interface Discount {
+    id: string;
+    source: DiscountSource;
+    /** Human-readable label (e.g. "Gold Member Discount"). */
+    label: string;
+    /** Discount amount in minor units. */
+    amount: number;
+    /** Percentage discount, 0–100. Informational only when `amount` is authoritative. */
+    percentage?: number;
+    /** Coupon code that triggered this discount, if applicable. */
+    couponCode?: string;
+}
+type SurchargeReason = 'format' | 'seat-type' | 'booking-fee' | 'service-fee' | 'peak-surcharge';
+interface Surcharge {
+    id: string;
+    reason: SurchargeReason;
+    /** Human-readable label (e.g. "IMAX Surcharge"). */
+    label: string;
+    /** Surcharge amount in minor units. */
+    amount: number;
+}
+/**
+ * Itemised price breakdown for a single ticket or a quantity of tickets.
+ *
+ * All amounts are in minor units of `currency` (e.g. cents for NZD).
+ */
+interface PriceBreakdown {
+    /** Base price per ticket before adjustments. */
+    basePrice: number;
+    /** Ordered list of discounts applied. */
+    discounts: Discount[];
+    /** Ordered list of surcharges applied. */
+    surcharges: Surcharge[];
+    /** Tax amount. Zero when `taxConfig.inclusive` is true. */
+    taxAmount: number;
+    /** Sum of all discounts. */
+    totalDiscount: number;
+    /** Sum of all surcharges. */
+    totalSurcharge: number;
+    /** Per-ticket price after all adjustments. */
+    pricePerTicket: number;
+    /** `pricePerTicket * quantity`. */
+    totalPrice: number;
+    quantity: number;
+    currency: string;
+    taxConfig: TaxConfig;
+}
+/**
+ * Full price calculation response from the Vista pricing engine.
+ *
+ * Returned by `PricingResource.calculate()`. The `breakdown` field gives
+ * full itemisation; legacy integrations can use the flat fields.
+ */
+interface PriceCalculation {
+    sessionId: string;
+    ticketTypeId: string;
+    /** Total price, minor units. */
+    totalPrice: number;
+    currency: string;
+    /** Whether returned price includes tax. */
+    taxInclusive: boolean;
+    /** Detailed, itemised breakdown. */
+    breakdown: PriceBreakdown;
+    /** ISO 8601 timestamp — price is valid until this time. */
+    validUntil: string;
+}
+interface ApplyCouponsInput {
+    sessionId: string;
+    ticketTypeId: string;
+    quantity: number;
+    couponCodes: string[];
+    /** Loyalty member ID for tier-based discount resolution. */
+    membershipId?: string;
+}
+interface CouponApplicationResult {
+    applied: Discount[];
+    rejected: Array<{
+        code: string;
+        reason: string;
+    }>;
+    updatedBreakdown: PriceBreakdown;
+}
+
+/**
+ * Pricing resource — ticket types, price calculations, tax handling, and coupon application.
+ *
+ * Handles the complexity of Vista's pricing model: matinee vs peak pricing,
+ * format surcharges (IMAX, 4DX), loyalty tier discounts, and coupon stacking.
+ */
+declare class PricingResource {
+    private readonly http;
+    constructor(http: TheatricalHTTPClient);
+    /**
+     * List available ticket types for a session.
+     *
+     * @param sessionId - The Vista session ID.
+     * @param filter - Optional filter params (category, availableOnly).
+     */
+    ticketTypes(sessionId: string, filter?: Omit<TicketTypeFilter, 'sessionId'>): Promise<TicketType[]>;
+    /**
+     * Calculate the price for a ticket type and quantity.
+     *
+     * Returns an itemised {@link PriceBreakdown} including base price, discounts,
+     * surcharges, and tax. The breakdown reflects the caller's Vista site tax
+     * configuration (inclusive vs exclusive).
+     *
+     * @param sessionId - The Vista session ID.
+     * @param ticketTypeId - Ticket type to price.
+     * @param quantity - Number of tickets (default 1).
+     */
+    calculate(sessionId: string, ticketTypeId: string, quantity?: number): Promise<PriceCalculation>;
+    /**
+     * Apply coupon codes and resolve loyalty-tier discounts.
+     *
+     * Validates each coupon code, stacks applicable discounts, and returns
+     * an updated {@link PriceBreakdown}. Invalid or expired codes are listed
+     * in the `rejected` array rather than throwing.
+     *
+     * @param input - Session, ticket type, quantity, coupon codes, and optional member ID.
+     */
+    applyCoupons(input: ApplyCouponsInput): Promise<CouponApplicationResult>;
+}
+
+/**
+ * Dietary classification flags.
+ *
+ * Multiple flags can apply simultaneously (e.g. vegan items are also vegetarian).
+ */
+type DietaryFlag = 'vegetarian' | 'vegan' | 'gluten-free' | 'dairy-free' | 'nut-free' | 'halal' | 'kosher';
+/** Broad menu section groupings used for candy-bar display ordering. */
+type MenuSectionType = 'hot-food' | 'cold-food' | 'drinks' | 'combos' | 'snacks' | 'ice-cream' | 'alcohol';
+interface MenuCategory {
+    id: string;
+    name: string;
+    sectionType: MenuSectionType;
+    /** Display rank — lower numbers appear first in UI. */
+    displayOrder: number;
+    /** Whether this category is currently visible on the menu. */
+    isActive: boolean;
+}
+interface MenuItem {
+    id: string;
+    name: string;
+    description?: string;
+    /** Price in minor currency units (e.g. cents). */
+    price: number;
+    currency: string;
+    /** Parent category. */
+    categoryId: string;
+    /** Human-readable category name for convenience. */
+    categoryName?: string;
+    imageUrl?: string;
+    /** Dietary classifications. Empty array means no special designation. */
+    dietary: DietaryFlag[];
+    isAvailable: boolean;
+    /** When true, item can be added to an active pre-order. */
+    isPreOrderEligible: boolean;
+    /** ID of a combo offer this item belongs to, if any. */
+    comboDealId?: string;
+    /** Calories as listed on menu (optional — site-dependent). */
+    calories?: number;
+    /** Customisation options (e.g. "Size", "Flavour"). */
+    customisations?: ItemCustomisation[];
+}
+interface ItemCustomisation {
+    id: string;
+    name: string;
+    required: boolean;
+    options: Array<{
+        id: string;
+        name: string;
+        /** Price delta in minor units — positive means extra charge, negative means discount. */
+        priceDelta: number;
+    }>;
+}
+/**
+ * A bundled combo deal — e.g. "Large Popcorn + Large Drink = $18.50"
+ *
+ * Combos are priced as a unit; the `savings` field shows value vs buying
+ * items individually, suitable for upsell copy.
+ */
+interface ComboOffer {
+    id: string;
+    name: string;
+    description?: string;
+    /** Total combo price in minor units. */
+    price: number;
+    currency: string;
+    /** IDs of MenuItem that make up this combo. */
+    itemIds: string[];
+    /** Saving in minor units vs buying all items individually at full price. */
+    savings: number;
+    isAvailable: boolean;
+    /** Whether this combo can be added via pre-order. */
+    isPreOrderEligible: boolean;
+    imageUrl?: string;
+}
+interface FnbOrderLineItem {
+    itemId: string;
+    quantity: number;
+    /** Selected customisation option IDs, keyed by customisation ID. */
+    customisations?: Record<string, string>;
+    /** Unit price at time of ordering (minor units). */
+    unitPrice: number;
+}
+interface AddToOrderInput {
+    /** Vista order ID to attach F&B items to. */
+    orderId: string;
+    items: FnbOrderLineItem[];
+    /** Pre-order session ID — required when `isPreOrderEligible` items are included. */
+    sessionId?: string;
+}
+interface FnbOrderConfirmation {
+    orderId: string;
+    addedItems: FnbOrderLineItem[];
+    /** Updated F&B subtotal in minor units. */
+    fnbSubtotal: number;
+    currency: string;
+}
+interface MenuFilter {
+    siteId: string;
+    categoryId?: string;
+    dietary?: DietaryFlag[];
+    /** Return only items with isAvailable = true. Defaults to true. */
+    availableOnly?: boolean;
+    /** Filter for pre-order-eligible items only. */
+    preOrderOnly?: boolean;
+}
+
+/**
+ * Food & Beverage resource — menus, ordering, combo deals, and dietary filtering.
+ *
+ * Covers the Vista OCAPI candy-bar endpoints used to surface F&B options
+ * on digital kiosks, mobile apps, and web booking flows.
+ */
+declare class FoodAndBeverageResource {
+    private readonly http;
+    constructor(http: TheatricalHTTPClient);
+    /**
+     * List menu items for a site, with optional filtering.
+     *
+     * Results include dietary tags and customisation options. Use `filter.dietary`
+     * to surface only vegan / gluten-free items. Use `filter.preOrderOnly` when
+     * building a pre-order flow tied to a session.
+     *
+     * @param siteId - The Vista site ID.
+     * @param filter - Optional filter (dietary, category, availability).
+     */
+    menu(siteId: string, filter?: Omit<MenuFilter, 'siteId'>): Promise<MenuItem[]>;
+    /**
+     * List available menu categories for a site.
+     *
+     * Categories define the candy-bar section groupings (popcorn, drinks,
+     * combos, snacks). Ordered by `displayOrder` ascending.
+     *
+     * @param siteId - The Vista site ID.
+     */
+    categories(siteId: string): Promise<MenuCategory[]>;
+    /**
+     * Fetch full detail for a single menu item.
+     *
+     * Includes customisation options (size, flavour) not always returned in
+     * the full menu list. Use this before presenting an add-to-order form.
+     *
+     * @param siteId - The Vista site ID.
+     * @param itemId - The menu item ID.
+     */
+    itemDetail(siteId: string, itemId: string): Promise<MenuItem>;
+    /**
+     * List combo deals available at a site.
+     *
+     * Combos are pre-configured bundles (e.g. "Large Popcorn + Large Drink").
+     * The `savings` field on each {@link ComboOffer} indicates the discount
+     * vs buying items individually — useful for upsell copy.
+     *
+     * @param siteId - The Vista site ID.
+     */
+    combos(siteId: string): Promise<ComboOffer[]>;
+    /**
+     * Add F&B items to an existing Vista order.
+     *
+     * Attaches concession items to a booking in progress. When adding
+     * pre-order items tied to a specific session, pass `input.sessionId`
+     * to enable collection-slot logic on the Vista side.
+     *
+     * Returns a confirmation with updated F&B subtotal for display.
+     *
+     * @param input - Order ID, items to add, optional session ID.
+     */
+    addToOrder(input: AddToOrderInput): Promise<FnbOrderConfirmation>;
+}
+
+/**
+ * TheatricalClient — the primary entry point for the Theatrical SDK.
+ *
+ * Provides type-safe access to cinema platform API resources through
+ * lazily-initialised resource modules.
+ *
+ * Configuration is validated at construction time using Zod schemas.
+ * Invalid configs throw a `ValidationError` immediately so misconfigurations
+ * surface at startup rather than at runtime.
+ *
+ * @example
+ * ```typescript
+ * const client = new TheatricalClient({
+ *   apiKey: 'your-api-key',
+ *   environment: 'sandbox',
+ * });
+ *
+ * const sessions = await client.sessions.list({
+ *   siteId: 'roxy-wellington',
+ *   date: '2026-04-09',
+ * });
+ * ```
+ *
+ * @example Static factory
+ * ```typescript
+ * const client = TheatricalClient.create({
+ *   apiKey: process.env.THEATRICAL_API_KEY!,
+ *   environment: 'production',
+ * });
+ * ```
+ *
+ * @example Singleton
+ * ```typescript
+ * TheatricalClient.setGlobal({ apiKey: 'key', environment: 'sandbox' });
+ * const client = TheatricalClient.global();
+ * ```
+ */
+declare class TheatricalClient {
+    private readonly config;
+    private readonly httpClient;
+    private readonly tokenManager;
+    private _sessions?;
+    private _sites?;
+    private _films?;
+    private _orders?;
+    private _loyalty?;
+    private _subscriptions?;
+    private _pricing?;
+    private _fnb?;
+    /**
+     * Constructs a TheatricalClient with validated configuration.
+     *
+     * Throws `ValidationError` immediately if config is invalid.
+     *
+     * @param config - SDK configuration
+     * @throws {ValidationError} if config fails schema validation
+     */
+    constructor(config: TheatricalConfig);
+    /**
+     * Creates a new TheatricalClient instance.
+     *
+     * Equivalent to `new TheatricalClient(config)` but provided as a static
+     * factory for clarity in configuration-heavy setups.
+     *
+     * @param config - SDK configuration
+     * @returns New TheatricalClient instance
+     * @throws {ValidationError} if config fails schema validation
+     *
+     * @example
+     * ```typescript
+     * const client = TheatricalClient.create({
+     *   apiKey: process.env.THEATRICAL_API_KEY!,
+     *   environment: 'production',
+     *   timeout: 15_000,
+     * });
+     * ```
+     */
+    static create(config: TheatricalConfig): TheatricalClient;
+    /**
+     * Returns the global singleton TheatricalClient instance.
+     *
+     * Throws if no global instance has been configured via `setGlobal()`.
+     * Useful for applications that initialise the client once at startup and
+     * access it throughout without passing the instance around.
+     *
+     * @returns The global TheatricalClient instance
+     * @throws {Error} if setGlobal() has not been called
+     *
+     * @example
+     * ```typescript
+     * // At startup:
+     * TheatricalClient.setGlobal({ apiKey: 'key', environment: 'production' });
+     *
+     * // Anywhere in your app:
+     * const client = TheatricalClient.global();
+     * const films = await client.films.nowShowing({ siteId: 'roxy-wellington' });
+     * ```
+     */
+    static global(): TheatricalClient;
+    /**
+     * Configures the global singleton TheatricalClient instance.
+     *
+     * Replaces any existing global instance. Subsequent calls to
+     * `TheatricalClient.global()` will return this instance.
+     *
+     * @param config - SDK configuration
+     * @throws {ValidationError} if config fails schema validation
+     *
+     * @example
+     * ```typescript
+     * TheatricalClient.setGlobal({
+     *   apiKey: process.env.THEATRICAL_API_KEY!,
+     *   environment: 'production',
+     * });
+     * ```
+     */
+    static setGlobal(config: TheatricalConfig): void;
+    /**
+     * Resets the global singleton instance.
+     *
+     * Primarily intended for testing — allows tests to start with a clean slate.
+     *
+     * @example
+     * ```typescript
+     * afterEach(() => {
+     *   TheatricalClient.resetGlobal();
+     * });
+     * ```
+     */
+    static resetGlobal(): void;
+    /**
+     * Creates an offline mock client that returns pre-defined NZ cinema fixture data.
+     *
+     * Ideal for demos, prototypes, and evaluators without a Vista API key.
+     * The mock covers films, sessions, sites, orders, and loyalty endpoints.
+     *
+     * @param fixtureOverrides - Optional URL-keyed fixture map to replace specific responses
+     *
+     * @example
+     * ```typescript
+     * const client = import.meta.env.VITE_THEATRICAL_MOCK
+     *   ? TheatricalClient.createMock()
+     *   : TheatricalClient.create({ apiKey: process.env.THEATRICAL_API_KEY! });
+     * ```
+     *
+     * @see https://developer.vista.co
+     */
+    static createMock(fixtureOverrides?: Record<string, unknown>): TheatricalClient;
+    /** Sessions — showtimes, availability, seat maps */
+    get sessions(): SessionsResource;
+    /** Sites — cinema locations, screens, configurations */
+    get sites(): SitesResource;
+    /** Films — now showing, coming soon, search */
+    get films(): FilmsResource;
+    /** Orders — booking lifecycle: create, confirm, cancel */
+    get orders(): OrdersResource;
+    /** Loyalty — member management, points, tiers */
+    get loyalty(): LoyaltyResource;
+    /** Subscriptions — plans, member subscriptions */
+    get subscriptions(): SubscriptionsResource;
+    /** Pricing — ticket types, price calculations, tax handling */
+    get pricing(): PricingResource;
+    /** Food & Beverage — menus, ordering, dietary information */
+    get fnb(): FoodAndBeverageResource;
+}
+
+/**
+ * Base error class for all Theatrical SDK errors
+ */
+declare class TheatricalError extends Error {
+    readonly statusCode: number;
+    readonly vistaErrorCode?: string;
+    readonly requestId?: string;
+    constructor(message: string, statusCode: number, vistaErrorCode?: string, requestId?: string);
+    toJSON(): {
+        name: string;
+        message: string;
+        statusCode: number;
+        vistaErrorCode: string | undefined;
+        requestId: string | undefined;
+    };
+}
+declare class AuthenticationError extends TheatricalError {
+    constructor(message?: string, vistaErrorCode?: string, requestId?: string);
+}
+declare class RateLimitError extends TheatricalError {
+    readonly retryAfter: number;
+    constructor(retryAfter: number, requestId?: string);
+}
+declare class ValidationError extends TheatricalError {
+    readonly fields: Record<string, string>;
+    constructor(message: string, fields?: Record<string, string>, requestId?: string);
+}
+declare class NotFoundError extends TheatricalError {
+    readonly resource: string;
+    readonly resourceId: string;
+    constructor(resource: string, resourceId: string, requestId?: string);
+}
+declare class ServerError extends TheatricalError {
+    constructor(message?: string, requestId?: string);
+}
+
+/**
+ * A lightweight mock HTTP adapter for offline development and testing.
+ *
+ * Replaces `TheatricalHTTPClient` inside a mock `TheatricalClient`.
+ * Matches URL paths against a fixture map and returns pre-defined responses.
+ *
+ * @see TheatricalClient.createMock()
+ */
+declare class MockHTTPAdapter {
+    private readonly responses;
+    constructor(overrides?: Record<string, unknown>);
+    /** Normalise a concrete path to a pattern key by replacing segments that look like IDs. */
+    private matchPattern;
+    private lookup;
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, options?: {
+        body?: unknown;
+    }): Promise<T>;
+    put<T>(path: string, options?: {
+        body?: unknown;
+    }): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+}
+
+declare const SDK_VERSION = "0.1.0";
+declare const SDK_USER_AGENT = "theatrical-sdk/0.1.0 (Node.js)";
+
+export { AuthenticationError, type Film, type FilmFilter, type LoyaltyMember, type LoyaltyTier, type MemberSubscription, type MenuCategory, type MenuItem, MockHTTPAdapter, NotFoundError, type Order, type OrderItem, type OrderStatus, type PriceCalculation, RateLimitError, SDK_USER_AGENT, SDK_VERSION, type Screen, type Seat, type SeatAvailability, type SeatStatus, ServerError, type Session, type SessionFilter, type SessionListResponse, type Site, type SiteConfig, type SubscriptionBenefit, type SubscriptionPlan, type SubscriptionUsage, TheatricalClient, type TheatricalConfig, type TheatricalEnvironment, TheatricalError, type Ticket, type TicketType, ValidationError };