@autoscroll/types

Shared types, schemas, and contracts for the Autoscroll Recorder ecosystem.

This package provides:

• TypeScript types generated from JSON Schema (single source of truth)
• JSON Schema for configuration validation and form generation
• Event types for EventBridge/SQS integration
• AJV-based validation that automatically stays in sync with schema changes
• Compute configuration support for CPU and GPU encoding

Installation

npm install @autoscroll/types

Usage

Configuration Types and Schema

import { 
  RecordingOptions,
  RECORDING_SCHEMA,
  validateConfig,
  mergeWithDefaults,
  DEFAULT_RECORDING_OPTIONS
} from '@autoscroll/types/config';

// Create a recording configuration
const config: RecordingOptions = {
  url: 'https://example.com',
  compute: {
    type: 'cpu',
    preset: 'veryfast',
    crf: 23
  },
  scrollBehavior: 'human-like',
  deviceType: 'desktop-standard'
};

// Validate configuration (uses AJV internally)
const validation = validateConfig(config);
if (!validation.valid) {
  console.error('Invalid config:', validation.errors);
}

// Merge partial config with defaults
const fullConfig = mergeWithDefaults({
  url: 'https://example.com'
});

// Access the JSON Schema (e.g., for form generation)
import { getRecordingSchema } from '@autoscroll/types/config';
const schema = getRecordingSchema(); // RJSFSchema for @rjsf/core

Partial Configuration Updates

import { 
  updateConfig,
  validatePartialConfig,
  deepMergeConfig
} from '@autoscroll/types/config';

// Update existing config with partial changes
const existingConfig: RecordingOptions = loadFromDatabase();
const updates = {
  scrollSpeed: 1.5,
  compute: { preset: 'medium' }  // Merges with existing compute settings
};

const result = updateConfig(existingConfig, updates);
if (result.success) {
  console.log('Updated fields:', result.changes); // ['scrollSpeed', 'compute.preset']
  saveToDatabase(result.config);
} else {
  console.error('Invalid update:', result.errors);
}

// Validate partial config without merging
const partialValidation = validatePartialConfig({
  frameRate: 30,
  scrollSpeed: 1.25
});
console.log('Partial valid:', partialValidation.valid);

// Deep merge configs manually
const merged = deepMergeConfig(existingConfig, updates);

Event Types

import { 
  RecordingRequest,
  RecordingCompletedEvent,
  RecordingFailedEvent,
  Destinations,
  hasDestinations,
  isRecordingCompletedEvent
} from '@autoscroll/types/events';

// Example: Creating a recording request
const request: RecordingRequest = {
  url: 'https://example.com',
  compute: {
    type: 'gpu',
    preset: 'p4'
  },
  deviceType: 'desktop-standard',
  jobId: 'job-123',
  destinations: {
    extraS3: [{
      bucket: 'my-bucket',
      prefix: 'videos/',
      roleArn: 'arn:aws:iam::123456789012:role/MyRole',
      externalId: 'my-external-id'
    }]
  }
};

// Example: Handling EventBridge events
function handleEvent(event: BaseAutoscrollEvent) {
  if (isRecordingCompletedEvent(event)) {
    console.log('Recording completed:', event.detail.jobId);
    
    if (hasDestinations(event.detail.destinations)) {
      console.log('Has destinations to process');
    }
  }
}

Types Included

Configuration Types (@autoscroll/types/config)

• RecordingOptions - Complete recording configuration (generated from schema)
• DeviceType - Device viewport presets (desktop/mobile variants)
• ScrollBehavior - Scrolling behaviors (none, human-like, constant, momentum, wheel-simulation)
• VideoFormat - Output formats (mp4, webm)
• ComputeConfig - CPU or GPU encoding configuration
• CPUComputeConfig - CPU encoding with libx264 presets
• GPUComputeConfig - GPU encoding with NVENC presets
• Constants: DEFAULT_RECORDING_OPTIONS, DEFAULT_CPU_COMPUTE, DEFAULT_GPU_COMPUTE

Event Types (@autoscroll/types/events)

• RecordingRequest - SQS message format for recording jobs
• RecordingCompletedEvent - EventBridge event when recording succeeds
• RecordingFailedEvent - EventBridge event when recording fails
• BaseAutoscrollEvent - Base type for all events
• Destinations - Container for all destination types
• ExtraS3Destination - Cross-account S3 destination configuration
• GoogleDriveDestination - Google Drive destination configuration

Schema & Validation (@autoscroll/types/config)

• RECORDING_SCHEMA - JSON Schema (source of truth for types)
• validateConfig() - AJV-based validation with user-friendly errors
• mergeWithDefaults() - Merge partial config with defaults
• getConfigSchema() - Get the JSON schema with version
• getSchemaVersion() - Get current schema version
• getRecordingSchema() - Get RJSFSchema for form generation
• getRecordingUISchema() - Get UI customization schema

Partial Update Utilities (@autoscroll/types/config)

• updateConfig() - Update existing config with partial changes, validate, and track changes
• validatePartialConfig() - Validate only provided fields without requiring all fields
• deepMergeConfig() - Deep merge configs with smart handling of nested objects
• DeepPartial<T> - Type helper for partial updates
• ConfigUpdateResult - Result type with success, config, errors, and changes

Utility Functions

• isRecordingCompletedEvent() - Type guard for completed events
• isRecordingFailedEvent() - Type guard for failed events
• hasDestinations() - Check if destinations are configured
• getSchemaPropertyKeys() - Get all schema property names
• getVisibleFields() - Get fields visible in UI
• isHiddenField() - Check if field is hidden in UI

Architecture

Single Source of Truth

The package uses RECORDING_SCHEMA as the single source of truth:

1. JSON Schema defines the structure, validation rules, and defaults
2. TypeScript types are generated from the schema using json-schema-to-ts
3. Validation uses AJV compiled from the same schema
4. Forms are generated using the schema with @rjsf/core

This ensures everything stays in sync automatically when the schema changes.

Type Generation

// Types are generated from schema with proper optionality
export type RecordingOptions = FromSchema<
  typeof RECORDING_SCHEMA,
  { keepDefaultedPropertiesOptional: true }
>;

The keepDefaultedPropertiesOptional option ensures that fields with default values remain optional in the TypeScript type, following correct JSON Schema semantics.

Publishing Updates

When types change:

1. Update version in package.json
2. Build the package: npm run build
3. Run the publish script: ./publish.sh

The publish script handles:

• Building TypeScript files
• Generating the schema.json file
• Publishing to npm with public access

Integration Examples

In the Web App

import { RecordingRequest, Destinations } from '@autoscroll/types/events';
import { RecordingOptions, mergeWithDefaults } from '@autoscroll/types/config';

// Create recording options
const options: RecordingOptions = mergeWithDefaults({
  url: 'https://example.com',
  compute: { type: 'gpu', preset: 'p4' },
  scrollBehavior: 'wheel-simulation'
});

// Create destinations
const destinations: Destinations = {
  googleDrive: {
    connectionId: 'customer123',
    folderId: 'folder-id'
  }
};

// Create recording request
const request: RecordingRequest = {
  ...options,
  jobId: generateJobId(),
  destinations
};

// Send to SQS...

In Lambda Functions

import { RecordingCompletedEvent, isRecordingCompletedEvent } from '@autoscroll/types/events';

export const handler = async (event: unknown) => {
  if (!isRecordingCompletedEvent(event)) {
    throw new Error('Invalid event type');
  }
  
  const { jobId, destinations, videoUrl } = event.detail;
  
  // Process destinations...
  if (destinations?.googleDrive) {
    await uploadToGoogleDrive(videoUrl, destinations.googleDrive);
  }
};

In React Forms (with @rjsf/core)

import Form from '@rjsf/core';
import { getRecordingSchema, getRecordingUISchema } from '@autoscroll/types/config';
import { RecordingOptions, validateConfig } from '@autoscroll/types/config';

function RecordingForm() {
  const handleSubmit = (data: { formData: RecordingOptions }) => {
    const validation = validateConfig(data.formData);
    if (validation.valid) {
      // Submit the recording...
    }
  };

  return (
    <Form
      schema={getRecordingSchema()}
      uiSchema={getRecordingUISchema()}
      onSubmit={handleSubmit}
    />
  );
}

Version History

• 1.3.0 - Added partial validation utilities for config updates
• 1.2.0 - AJV validation and type generation from schema
• 1.1.0 - Added GPU compute configuration support
• 1.0.0 - Initial release with basic types