Skip to main content

Contracts Package Types

The @ever-works/contracts package defines the shared TypeScript types, interfaces, and enums used across the entire Ever Works platform. It serves as the single source of truth for data shapes that cross package boundaries -- from the API layer to the frontend, from plugins to the generation pipeline. Every package that needs to exchange structured data depends on these contracts.

Package Overview​

PropertyValue
Package name@ever-works/contracts
Locationplatform/packages/contracts/
FormatESM (TypeScript declarations)
DependentsAPI, frontend, plugins, CLI, generation pipeline

Module Exports​

// Core domain types
export * from './item/item.types.js';
export * from './domain/domain.types.js';
export * from './form/form-field.types.js';

// API contracts
export * from './api/index.js';

Item Types​

The item/item.types.ts module defines the core data structures for work items -- the primary content entities in the platform.

Category​

interface Category {
	name: string;
	slug: string;
	description?: string;
	icon?: string;
	parentSlug?: string;
	itemCount?: number;
}

Tag​

interface Tag {
	name: string;
	slug: string;
	description?: string;
	itemCount?: number;
}

Collection​

interface Collection {
	name: string;
	slug: string;
	description?: string;
	items?: string[]; // Item IDs
}

Brand​

interface Brand {
	name: string;
	slug: string;
	description?: string;
	logo?: string;
	website?: string;
}

Badge and ItemBadges​

Badges are visual indicators attached to items for quick recognition.

interface Badge {
	label: string;
	color?: string;
	icon?: string;
	tooltip?: string;
}

interface ItemBadges {
	primary?: Badge;
	secondary?: Badge[];
}

ItemData​

The central item type used across the platform. Contains all displayable and searchable fields.

interface ItemData {
	name: string;
	slug: string;
	description: string;
	url?: string;
	imageUrl?: string;
	categories: Category[];
	tags: Tag[];
	badges?: ItemBadges;
	brand?: Brand;
	metadata?: Record<string, unknown>;
	features?: string[];
	pros?: string[];
	cons?: string[];
	rating?: number;
	reviewCount?: number;
	pricing?: string;
	lastUpdated?: string;
	source?: string;
	sourceUrl?: string;
}

MutableItemData​

A subset of ItemData fields that can be modified after creation.

interface MutableItemData {
	name?: string;
	description?: string;
	url?: string;
	imageUrl?: string;
	categories?: Category[];
	tags?: Tag[];
	badges?: ItemBadges;
	metadata?: Record<string, unknown>;
	features?: string[];
	pros?: string[];
	cons?: string[];
	pricing?: string;
}

Comparison Types​

Used for side-by-side item comparisons in the frontend.

interface ComparisonDimension {
	name: string;
	key: string;
	type: 'text' | 'number' | 'boolean' | 'rating';
	description?: string;
}

interface ComparisonData {
	dimensions: ComparisonDimension[];
	items: Record<string, Record<string, unknown>>;
}

Domain Types​

The domain/domain.types.ts module defines types related to domain detection and classification during content generation.

DomainType​

enum DomainType {
	SOFTWARE = 'software',
	ECOMMERCE = 'ecommerce',
	SERVICES = 'services',
	GENERAL = 'general'
}

The domain type influences how items are structured, what fields are emphasized, and which generation strategies are applied.

DomainAnalysis​

interface DomainAnalysis {
	domain: DomainType;
	confidence: number; // 0-1 confidence score
	reasoning: string; // Why this domain was detected
	suggestedFields?: string[];
}

WebPageData​

Represents fetched web page content used during content extraction.

interface WebPageData {
	url: string;
	title?: string;
	content: string;
	description?: string;
	statusCode?: number;
	contentType?: string;
}

RelevanceAssessment​

Scores how relevant a piece of web content is to the user's work topic.

interface RelevanceAssessment {
	relevant: boolean;
	score: number; // 0-1 relevance score
	reasoning: string;
	extractableItems?: number;
}

Form Field Types​

The form/form-field.types.ts module defines the form schema system used for dynamic form rendering in the frontend. This powers plugin settings UIs, work configuration forms, and item editing interfaces.

FormFieldType​

An extensive enumeration of all supported form field types.

enum FormFieldType {
	TEXT = 'text',
	TEXTAREA = 'textarea',
	NUMBER = 'number',
	EMAIL = 'email',
	URL = 'url',
	TEL = 'tel',
	PASSWORD = 'password',
	SELECT = 'select',
	MULTI_SELECT = 'multi-select',
	CHECKBOX = 'checkbox',
	RADIO = 'radio',
	TOGGLE = 'toggle',
	DATE = 'date',
	DATETIME = 'datetime',
	TIME = 'time',
	COLOR = 'color',
	FILE = 'file',
	IMAGE = 'image',
	RICH_TEXT = 'rich-text',
	MARKDOWN = 'markdown',
	CODE = 'code',
	JSON = 'json',
	SLIDER = 'slider',
	RATING = 'rating',
	TAGS = 'tags',
	HIDDEN = 'hidden'
}

FormFieldOption​

Options for select, multi-select, radio, and checkbox group fields.

interface FormFieldOption {
	label: string;
	value: string | number | boolean;
	description?: string;
	disabled?: boolean;
	icon?: string;
}

FormFieldValidation​

Validation rules applied to individual form fields.

interface FormFieldValidation {
	required?: boolean;
	minLength?: number;
	maxLength?: number;
	min?: number;
	max?: number;
	pattern?: string;
	patternMessage?: string;
	custom?: (value: unknown) => string | undefined;
}

FormFieldCondition​

Conditional visibility logic for form fields.

interface FormFieldCondition {
	field: string; // Field key to watch
	operator: 'eq' | 'neq' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains';
	value: unknown;
}

FormFieldDefinition​

The complete definition for a single form field.

interface FormFieldDefinition {
	key: string;
	type: FormFieldType;
	label: string;
	description?: string;
	placeholder?: string;
	defaultValue?: unknown;
	validation?: FormFieldValidation;
	options?: FormFieldOption[];
	condition?: FormFieldCondition;
	group?: string;
	order?: number;
	disabled?: boolean;
	readOnly?: boolean;
	metadata?: Record<string, unknown>;
}

FormFieldGroup and FormSchema​

Groups organize related fields visually, and the schema ties everything together.

interface FormFieldGroup {
	key: string;
	label: string;
	description?: string;
	collapsible?: boolean;
	defaultCollapsed?: boolean;
	order?: number;
}

interface FormSchema {
	fields: FormFieldDefinition[];
	groups?: FormFieldGroup[];
	metadata?: Record<string, unknown>;
}

API Contract Types​

The api/ subwork contains types shared between the API and its consumers (frontend, CLI).

GenerateStatusType​

Tracks the state of a work generation process.

enum GenerateStatusType {
	IDLE = 'idle',
	PENDING = 'pending',
	RUNNING = 'running',
	COMPLETED = 'completed',
	FAILED = 'failed',
	CANCELLED = 'cancelled'
}

GenerationMethod​

How items are generated for a work.

enum GenerationMethod {
	AI_GENERATED = 'ai-generated',
	MANUAL = 'manual',
	IMPORTED = 'imported',
	HYBRID = 'hybrid'
}

enum WebsiteRepositoryCreationMethod {
	TEMPLATE = 'template',
	EXISTING = 'existing',
	BLANK = 'blank'
}

Generator DTO Types​

Data transfer objects for the generation API.

interface CreateItemsGeneratorDto {
	workId: string;
	prompt: string;
	method: GenerationMethod;
	options?: Record<string, unknown>;
}

interface UpdateItemsGeneratorDto {
	prompt?: string;
	options?: Record<string, unknown>;
}

Work Schedule Types​

Types for managing automated work update schedules.

interface WorkScheduleDto {
	cadence: WorkScheduleAllowedCadence;
	enabled: boolean;
	nextRunAt?: string;
	lastRunAt?: string;
}

interface UpdateWorkSchedulePayload {
	cadence?: WorkScheduleAllowedCadence;
	enabled?: boolean;
}

type WorkScheduleAllowedCadence = 'daily' | 'weekly' | 'biweekly' | 'monthly';

Cross-Package Usage​

The contracts package is the foundation that enables type-safe communication across the platform:

ConsumerTypes Used
APIAll types for request/response validation
FrontendItemData, FormSchema, Category, Tag for rendering
PluginsDomainType, ItemData, WebPageData for generation
CLIGenerationMethod, WorkScheduleDto for commands
Generation pipelineDomainAnalysis, RelevanceAssessment, ComparisonData

File Structure​

contracts/src/
  index.ts                                    # Root exports
  item/
    item.types.ts                             # Item, Category, Tag, Badge, Comparison types
  domain/
    domain.types.ts                           # DomainType, DomainAnalysis, WebPageData
  form/
    form-field.types.ts                       # FormFieldType, FormSchema, validation types
  api/
    index.ts                                  # API sub-module exports
    generator/
      generation-method.enum.ts              # GenerationMethod, WebsiteRepositoryCreationMethod
      create-items-generator.dto.ts          # Generator DTOs
    work/
      generate-status.enum.ts               # GenerateStatusType
      work-schedule.dto.ts             # Schedule types