@encatch/schema

TypeScript schema definitions using Zod for validation and type inference for the Encatch feedback and form platform.

Overview

This package provides comprehensive Zod schemas and TypeScript types for the entire Encatch ecosystem, including:

• Form fields and questions (rating, multiple choice, NPS, etc.)
• Validation rules and visibility conditions
• Themes and appearance customization
• Translations and internationalization
• API request/response schemas
• Device and session information
• Auto-trigger and audience targeting

Installation

npm install @encatch/schema zod

pnpm add @encatch/schema zod

yarn add @encatch/schema zod

Note: Zod is a peer dependency and must be installed separately.

Features

• Type-Safe Schemas: Full TypeScript support with Zod-powered runtime validation
• Comprehensive Coverage: Schemas for all Encatch form and feedback components
• Tree-Shakeable: Import only what you need
• ESM/CJS Support: Works in both modern and legacy environments
• Case Conversion Utilities: Built-in helpers for camelCase, snake_case, and PascalCase
• Enum Constants: Strongly-typed constants for all enumerated values

Usage

Basic Schema Validation

import { questionSchema, QuestionTypes, type Question } from '@encatch/schema';

// Validate runtime data
const data = {
  id: '123',
  type: 'rating',
  label: 'How satisfied are you?',
  // ... other fields
};

const result = questionSchema.safeParse(data);
if (result.success) {
  const question: Question = result.data;
  console.log('Valid question:', question);
} else {
  console.error('Validation errors:', result.error);
}

Type Inference

import { type RatingQuestion, RatingDisplayStyles } from '@encatch/schema';

// Use inferred types directly
const ratingQuestion: RatingQuestion = {
  id: '123',
  type: 'rating',
  label: 'Rate our service',
  displayStyle: RatingDisplayStyles.STARS,
  max: 5,
  // TypeScript will enforce all required fields
};

Using Enum Constants

import {
  QuestionTypes,
  ValidationRuleTypes,
  PublicationStatuses
} from '@encatch/schema';

// Use strongly-typed constants instead of string literals
const questionType = QuestionTypes.RATING; // 'rating'
const validationType = ValidationRuleTypes.REQUIRED; // 'required'
const status = PublicationStatuses.PUBLISHED; // 'published'

Case Conversion

import { objectToCamel, objectToSnake } from '@encatch/schema';

const snakeCase = {
  user_name: 'John',
  user_age: 30,
  user_preferences: {
    theme_mode: 'dark'
  }
};

const camelCase = objectToCamel(snakeCase);
// { userName: 'John', userAge: 30, userPreferences: { themeMode: 'dark' } }

const backToSnake = objectToSnake(camelCase);
// { user_name: 'John', user_age: 30, user_preferences: { theme_mode: 'dark' } }

API Request Validation

import {
  submitFeedbackSchema,
  fetchFeedbackDetailsSchema,
  type SubmitFeedback
} from '@encatch/schema';

// Validate API requests
const feedbackData: SubmitFeedback = {
  // ... feedback data
};

const validated = submitFeedbackSchema.parse(feedbackData);
// Throws if validation fails

Available Schemas

Field Schemas

• Question types: questionSchema, ratingQuestionSchema, npsQuestionSchema, etc.
• Validation: validationRuleSchema, visibilityConditionSchema
• Sections: sectionSchema
• Answers: answerSchema, annotationSchema

Form Schemas

• Configuration: feedbackConfigurationSchema
• Properties: formPropertiesSchema, welcomeScreenPropertiesSchema, endScreenPropertiesSchema
• Publishing: externalPublishingPropertiesSchema, publicationStatusSchema

Theme Schemas

• Themes: themesSchema, themeConfigurationSchema
• Theme (per mode): themeColorsSchema (shadcn variables JSON)
• Features: featureSettingsSchema

Translation Schemas

• Questions: questionTranslationSchema, translationsSchema
• Screens: WelcomeFieldsTranslationSchema, EndFieldsTranslationSchema
• Provider: TranslationProvider, createTranslationProvider

API Schemas

• Submit: submitFeedbackSchema, viewFeedbackSchema
• Fetch: fetchFeedbackDetailsSchema, fetchConfigurationListSchema
• Device: deviceInfoSchema, sessionInfoSchema, userInfoSchema

Auto-Trigger Schemas

• Targeting: audienceTriggerPropertiesSchema, audienceSegmentSchema
• Conditions: conditionalIfSchema, filterConditionSchema
• Actions: triggerActionSchema

Development

Build

pnpm run build

Builds both TypeScript declarations and the bundled ESM output.

Watch Mode

pnpm run dev

Rebuilds on file changes.

Testing

pnpm run test        # Run tests in watch mode
pnpm run test:run    # Run tests once
pnpm run test:ui     # Open Vitest UI
pnpm run test:coverage  # Generate coverage report

Clean Build

pnpm run clean

Removes the dist directory.

Publishing

This package uses release-it for automated releases:

pnpm run release        # Auto-detect version bump
pnpm run release:patch  # Patch version (0.0.x)
pnpm run release:minor  # Minor version (0.x.0)
pnpm run release:major  # Major version (x.0.0)

Bundler Implementation

This package uses esbuild for bundling, providing:

• Better performance with single bundled files
• Automatic ESM/CJS compatibility
• Cleaner source code without manual .js extensions

Project Structure

src/
├── schemas/
│   ├── api/              # API request/response schemas
│   │   ├── fetch-feedback-schema.ts
│   │   ├── submit-feedback-schema.ts
│   │   ├── other-schema.ts
│   │   └── refine-text-schema.ts
│   └── fields/           # Form field and configuration schemas
│       ├── answer-schema.ts
│       ├── app-props-schema.ts
│       ├── auto-trigger-schema.ts
│       ├── field-schema.ts
│       ├── form-properties-schema.ts
│       ├── form-schema.ts
│       ├── other-properties-schema.ts
│       ├── other-screen-schema.ts
│       ├── theme-schema.ts
│       └── translations-schema.ts
├── helpers/
│   └── case-convert-helper.ts  # Case conversion utilities
└── index.ts                     # Main entry point

License

AGPL-3.0