@waldyn/immersiv-training-shared

Shared contract layer for the Waldyn / Teleperformance Immersiv AI Training platform. Consumed by authoring and trainee runtime apps that share the same Postgres-backed contract when they depend on this package from npm.

The package exports:

• Drizzle table + enum + relation definitions (db/schema, db/enums, db/relations).
• Zod validators for node configs, routing rules, training metadata, enrollment payloads, and the publish-time structural checklist (validators/*).
• TypeScript types derived from Drizzle and Zod, plus typed envelopes for the publish-training and duplicate-training Supabase Edge Functions (types, types/publish).
• Shared constants — node types, routing strategies, progress / training statuses, publish error codes, the canonical idempotency header name (constants, constants/publish).

Released versions of this package track the platform schema contract on npm; consuming apps pin a semver range and follow migration notes per release.

Install

pnpm add @waldyn/immersiv-training-shared
# peer deps used by some subpaths:
pnpm add drizzle-orm zod

0.11.0 adds waitConfigSchema, quiz time_limit_seconds, and node_progress.progress_metadata typing in Drizzle; 0.10.2 already documented videoConfigSchema.text_alternative as WYSIWYG HTML (TipTap, same family as reading rich text).

Common imports

// Top-level re-export (tree-shakeable): everything is available here.
import {
  // Zod validators
  trainingSchema,
  getConfigValidator,
  validateTrainingForPublish,
  // Constants
  NODE_TYPES,
  TRAINING_STATUSES,
  PUBLISH_ERROR_CODES,
  PUBLISH_IDEMPOTENCY_KEY_HEADER,
  // Types (erased at runtime)
  type PublishEdgeResponse,
  type PublishTrainingRpcArgs,
} from '@waldyn/immersiv-training-shared'

Subpath imports for callers that want narrower boundaries:

import { trainings, nodes } from '@waldyn/immersiv-training-shared/db/schema'
import { quizConfigSchema } from '@waldyn/immersiv-training-shared/validators/node-configs'
import { validateTrainingForPublish } from '@waldyn/immersiv-training-shared/validators/publish'
import { PUBLISH_ERROR_CODES } from '@waldyn/immersiv-training-shared/constants/publish'
import type { PublishEdgeResponse } from '@waldyn/immersiv-training-shared/types/publish'

Publish path

The publish path uses a Postgres RPC (publish_training_snapshot) reached through the publish-training Supabase Edge Function (Clerk-verified, service-role caller). See the back office docs/data-contract.md for full details. Consumers of this package should:

1. Call validateTrainingForPublish(...) in the editor / publish dialog to collect warnings-only structural feedback (data-contract §7). The RPC does not run these checks — they are product guidance surfaced to the author.
2. Send the publish request to the Edge Function, optionally with an x-idempotency-key UUID header (PUBLISH_IDEMPOTENCY_KEY_HEADER).
3. Parse the response against PublishEdgeResponse and switch on PUBLISH_ERROR_CODES instead of string-matching messages.

Server-only ledger

The publishIdempotencyKeys Drizzle table is exported for server-side TypeScript only (Edge Functions, admin scripts). RLS is enabled with no policies and no PostgREST grants — there is no path from the browser to this table. Do not import it in browser bundles; it exists so server code gets the same typing the rest of the schema enjoys.

Versioning

This package follows SemVer against the data contract it mirrors. Bumping a table column, enum value, or Zod shape is a breaking change for both consumer apps — coordinate the deploy with the matching Postgres migration in the back office repo.

See the repository CHANGELOG (or git log) for the full version history.