@vantageos/event-schemas

Versioned event schema registry for Vantage Immo feature MCPs.

What it is

A code-side schema registry. No Convex tables. No event bus. Provides typed validators, type-guards, and helpers so feature MCPs can publish validated events into the host app's intakeEvents table without re-implementing validation logic.

Schemas

| Schema ID | Convex Validator | Type-guard | Status | Variants | |---|---|---|---|---| | intake.event.v1 | IntakeEventV1Schema | isIntakeEventV1 | Production | mail, document, contract, candidature, external-event | | task.complete.v1 | TaskCompleteV1Schema | isTaskCompleteV1 | Placeholder (Sigma API 5 v2 roadmap) | normal, auto-resolved |

Usage

import {
  publishEvent,
  isIntakeEventV1,
  IntakeEventV1Schema,
} from "@vantageos/event-schemas";

// 1. Validate and get typed payload (runtime type-guard)
const result = publishEvent("intake.event.v1", isIntakeEventV1, rawPayload);
if (!result.ok) {
  throw new Error(`Event validation failed: ${result.error}`);
}

// 2. result.payload is typed as IntakeEventV1
// 3. Insert into host app's intakeEvents table (Component does NOT insert)
await ctx.db.insert("intakeEvents", {
  orgId: result.payload.orgId,
  // ...
});

// validatePayload directly
import { validatePayload, isIntakeEventMailV1 } from "@vantageos/event-schemas";
const check = validatePayload(isIntakeEventMailV1, unknownValue);
if (check.ok) {
  console.log(check.value.sujet); // typed as IntakeEventMailV1
}

Convex schema args

Use the exported Convex validators in function args:

import { v } from "convex/values";
import { IntakeEventV1Schema } from "@vantageos/event-schemas";

export const myMutation = mutation({
  args: { event: IntakeEventV1Schema },
  // ...
});

Rules

• No v.any() at any public boundary.
• All exported symbols carry a V1 version suffix.
• publishEvent validates but never inserts — the host app owns the table.
• registerSchema throws on duplicate IDs — one schema per version.

License

MIT