@game-infra/event-schemas

@game-infra/event-schemas

Narrative event-editor API contract: valibot schemas plus toad-contracts defineApiContract definitions for event definitions, the Miro-style event board (HTTP + live-collab WebSocket protocol), and the AI generation/review/polish/tier-review endpoints. This is the largest schema slice extracted from golem-forge; it builds on @game-infra/api-schemas-core (response wrappers, AI provider enum) and @game-infra/common-data-model (tier-review entity types).

Published to npm. Also consumable as sibling source (exports points at src/).

Install

// pnpm sibling checkout
"@game-infra/event-schemas": "link:../../game-infra/packages/schemas/event-schemas"
// or from npm
"@game-infra/event-schemas": "^0.1.0"

valibot is a peer dependency (^1.4.0); the consumer provides it.

Usage

Contracts carry method, path, params, and request/response schemas in one object. Build a URL with pathResolver, derive the route pattern with mapApiContractToPath:

import {
  eventDefinitionLoadContract,
  aiReviewEventContract,
  TierReviewRequestSchema,
} from "@game-infra/event-schemas";
import { mapApiContractToPath } from "@toad-contracts/valibot";

eventDefinitionLoadContract.pathResolver({ gameId: "g1", eventId: "e1" });
// '/games/g1/event-definitions/e1'
aiReviewEventContract.pathResolver(); // '/ai/review-event'
mapApiContractToPath(eventDefinitionLoadContract); // '/games/:gameId/event-definitions/:eventId'

Register on a Hono service with @toad-contracts/hono (buildHonoRoute) and call from a frontend with @toad-contracts/frontend-http-client (sendByApiContract) — both drive off the same contract objects. The event board's live traffic is not HTTP: eventBoardLayoutWsContract is only the upgrade endpoint, and the actual edits flow through the ClientCollabMessageSchema / ServerCollabMessageSchema op protocol validated on the WebSocket.

Extension points

• Tier-review entity vocabulary: TierReviewEntityTypeSchema is a plain string(). golem-forge hardcoded picklist(['persona','item','secret','spell','organization']); that vocabulary is game-specific, so games re-tighten it via the editor's tierReviewEntityTypes config. The entityType field in tierReviewAIOutputSchema likewise dropped its enum so each game defines its own types.
• AI provider: the provider field reuses AIProviderSchema from @game-infra/api-schemas-core.

Migrating from golem-forge

The old EventApiPaths constants and PathResolvers / resolve*Path helpers (including the internal-tools EventGenerationPathResolvers and NextScreenPathResolvers) are gone. Get a URL from the contract itself with contract.pathResolver(params) and the :param route pattern with mapApiContractToPath(contract). Prefer driving requests through @toad-contracts/frontend-http-client (sendByApiContract) and routes through @toad-contracts/hono (buildHonoRoute), which consume the contract directly so you never touch a raw path.

Dependencies

@game-infra/api-schemas-core (createSuccessResponseSchema, TimestampFieldsSchema, ApiResponseSchema, AIProviderSchema), @game-infra/common-data-model (re-exported EntityInfo / AvailableEntities types), @toad-contracts/core, @toad-contracts/valibot; peer valibot.

Consumers

event-editor (frontend), core-service (event-board Durable Object plus the event-definition, board-layout, and AI endpoints).