Typed events

Validate custom events with Valibot or Zod and attach a schema version.

Validate with Valibot

pnpm add @hyperreal/landscape-core @hyperreal/landscape-schema @hyperreal/landscape-plugins-manual-tracking

import { init } from "@hyperreal/landscape-core";
import { defineEvents, generateContract, v } from "@hyperreal/landscape-schema";
import { createTypedTrack } from "@hyperreal/landscape-plugins-manual-tracking/typed";

const events = defineEvents({
  signed_up: v.object({ plan: v.string() }),
});

const client = init({
  endpoint: "/api/events",
  validator: events.validator,
});

const track = createTypedTrack(client, events);
track("signed_up", { plan: "pro" });

const contract = generateContract(events);

defineEvents lives in packages/schema/src/index.ts. schemaVersion defaults to "1". Validated events include that version on the payload.

createTypedTrack types track() against the registry. Untyped track() from core is also valid.

Validate with Zod

import { defineEventsZod, generateContractZod, z } from "@hyperreal/landscape-schema/zod";

const events = defineEventsZod({
  signed_up: z.object({ plan: z.string() }),
});

Pass events.validator to init. Use generateContractZod for the JSON Schema contract. createTypedTrack accepts either registry.

Defaults

Generate a contract

generateContract / generateContractZod return { schemaVersion, events } JSON Schema. Use it in ingest docs or OpenAPI components.schemas.