Polyglot SDKs, CLI tools, UI components, real-time events, and analytics
for cinema platform APIs — in TypeScript, C#, and Python.
Quick Start · Docs · Live Demo · Architecture · Research · Website
Cinema platforms process billions in annual transaction value. The APIs are production-grade. The developer ecosystem around them is not. No typed clients. No component libraries. No event systems. Every integrator starts from scratch.
Theatrical is the missing developer experience layer.
Independent project. Theatrical is not affiliated with or endorsed by any cinema platform vendor. See VISION.md for full context.
Start building in 30 seconds — no API credentials required:
| TypeScript | C# | Python |
|---|---|---|
import { TheatricalClient } from '@theatrical/sdk';
const client = TheatricalClient.createMock();
const films = await client.films.nowShowing();
const { sessions } = await client.sessions.list({
siteId: 'site_embassy_wellington',
});
const order = await client.orders.create({
sessionId: sessions[0].id,
tickets: [{ type: 'adult', seatId: 'H7' }],
}); |
using Theatrical.Sdk;
using Theatrical.Sdk.Types;
var client = TheatricalClient.CreateMock();
var films = await client.Films.NowShowingAsync();
var sessions = await client.Sessions.ListAsync(
new SessionFilter
{
SiteId = "site_embassy_wellington"
}); |
from theatrical import TheatricalClient
from theatrical.types import SessionFilter
client = TheatricalClient.create_mock()
films = await client.films.now_showing()
result = await client.sessions.list(
SessionFilter(site_id="site_embassy_wellington")
) |
npm install @theatrical/sdk |
dotnet add package Theatrical.Sdk |
pip install theatrical |
Mock mode returns real NZ cinema fixture data — Embassy Theatre Wellington, Roxy Cinema, Rialto Auckland — so you can build and test complete flows without API access.
┌─────────────────────────────────────────────────────────────────────────┐
│ Your Application │
├──────────────┬───────────────┬───────────────┬──────────────────────────┤
│ @theatrical │ templates │ @theatrical │ @theatrical │
│ /react │ (CLI init) │ /analytics │ /events │
│ Components │ Starters │ Horizon │ Real-time Bridge │
├──────────────┴───────┬───────┴───────────────┴──────────────────────────┤
│ │ @theatrical/cli │
│ │ init · codegen · inspect │
├──────────────────────┴──────────────────────────────────────────────────┤
│ @theatrical/sdk (TS) │ Theatrical.Sdk (C#) │ theatrical (Python) │
│ Auth · HTTP · Retry · Rate Limiting · 8 Resources │
├─────────────────────────────────────────────────────────────────────────┤
│ Cinema Platform API Layer │
└─────────────────────────────────────────────────────────────────────────┘
Six packages. Three languages. One API surface. See ARCHITECTURE.md for the full design.
Every SDK provides the same capabilities: GAS authentication with token refresh, HTTP retry with exponential backoff, token-bucket rate limiting, typed error hierarchy, and mock mode for zero-credential development.
| Package | Language | Tests | Install |
|---|---|---|---|
@theatrical/sdk |
TypeScript 5.9 | 274 | npm install @theatrical/sdk |
Theatrical.Sdk |
C# / .NET 8 | 276 | dotnet add package Theatrical.Sdk |
theatrical |
Python 3.10+ | 339 | pip install theatrical |
8 resource modules per SDK: Sessions, Sites, Films, Orders, Loyalty, Subscriptions, Pricing, F&B.
| Package | Description | Tests | License |
|---|---|---|---|
@theatrical/cli |
Scaffold projects, generate types from OpenAPI, explore APIs interactively | 171 | MIT |
@theatrical/react |
SeatMap, SessionPicker, OrderSummary, PaymentForm, Loyalty — ARIA accessible, dark-mode-first | 62 | BSL 1.1 |
@theatrical/events |
Real-time event bridge: poll → diff → emit → webhook (HMAC-SHA256 signed) | 71 | BSL 1.1 |
@theatrical/analytics |
Horizon client, fluent query builder, export to CSV/JSON/DataFrame/Chart.js | 72 | BSL 1.1 |
| Starter templates | React ticketing starter — living booking demo on the event bridge, scaffolded via npx @theatrical/cli init |
— | BSL 1.1 |
Cinema platforms don't have webhooks. Theatrical builds them:
import { BookingWatcher } from '@theatrical/events';
const watcher = new BookingWatcher({
fetch: (signal) => client.orders.list({}, signal),
});
watcher.on('booking.confirmed', async ({ order }) => {
// Triggered when order state changes to 'confirmed'
await notifyStaff(order);
await updateDashboard(order);
});
watcher.start();The event bridge polls, diffs state changes, and delivers typed webhooks with HMAC-SHA256 signatures. One failing endpoint doesn't block the others (Promise.allSettled isolation).
# Scaffold a new project with everything wired up
npx @theatrical/cli init my-cinema-app --template react-ticketing
# Explore any API endpoint interactively
npx @theatrical/cli inspect sessions list --site roxy-wellington
# Generate types from an OpenAPI spec
npx @theatrical/cli codegen openapi.yaml --output src/typesPre-built React components for the patterns every cinema app needs:
- SeatMap — interactive seat grid with ARIA keyboard navigation, wheelchair and companion markers
- SessionPicker — date-grouped showtime browser
- OrderSummary — line items, price breakdowns, loyalty points
- PaymentForm — provider-agnostic shell with render slots
- Loyalty — MemberCard, TierIndicator, PointsDisplay with animations
Dark-mode-first. Fully themeable via design tokens.
1,265 tests across three languages:
TypeScript 650 tests SDK 274 · CLI 171 · Events 71 · React 62 · Analytics 72
C# / .NET 276 tests xUnit
Python 339 tests pytest · mypy-strict · ruff
All mock data uses real NZ cinema context — Embassy Theatre Wellington, Roxy Cinema Wellington, Rialto Auckland. NZD currency, en-NZ locale. The fixture data tells a story, not test-1 and site-abc.
Five essays on the architecture and economics of cinema platform technology:
| Essay | Question |
|---|---|
| The Cinema Platform Thesis | Why does cinema need a developer ecosystem? |
| What Stripe Did for Payments | What can cinema learn from the Stripe playbook? |
| Cinema as Protocol | What happens when we treat cinema-going as infrastructure? |
| The 3.3 Billion Dollar API | What's the developer opportunity in cinema's transaction volume? |
| Event-Driven Cinema | How do you build real-time on top of request-response? |
Available as web pages at theatrical.dev/essays with RSS.
git clone https://github.com/brunohart/theatrical.git
cd theatrical
# TypeScript — SDK + CLI
cd packages/sdk && npm install && npx vitest run
cd ../cli && npm install && npx vitest run
# C# — requires .NET 8 SDK
cd packages/sdk-csharp && dotnet test
# Python — requires 3.10+
cd packages/sdk-py && pip install -e ".[dev]" && pytest tests/ -qTheatrical is not affiliated with, endorsed by, or officially connected to Vista Group International Limited or any of its subsidiaries. All trademarks are the property of their respective owners. See VISION.md for full context.
| Packages | License | Why |
|---|---|---|
@theatrical/sdk, @theatrical/cli, Theatrical.Sdk, theatrical (Python) |
MIT | Maximum adoption |
@theatrical/events, @theatrical/analytics, @theatrical/react, starter templates |
BSL 1.1 | Commercial protection, converts to MIT after 3 years |
© 2026 Bruno Hart