data-studio-shared

A shared TypeScript package providing common types, services, and schemas for the Data Studio ecosystem. This package serves as the foundation for data ingestion, event tracking, and analytics across Data Studio services.

Overview

data-studio-shared provides:

• Type Definitions: Common TypeScript interfaces and types for clients, sessions, events, alerts, and notifications
• ClickHouse Integration: Base service class and schema definitions for ClickHouse database operations
• Event Mapping: Standard event processing and mapping utilities
• Schema Definitions: Shared ClickHouse table schemas for consistency across services

Installation

npm install data-studio-shared
# or
yarn add data-studio-shared

Requirements

• Node.js >= 22.0.0
• TypeScript >= 5.6.0

Main Exports

Types

Common Types

• SDKBaseEntity, SDKBaseEntityWithUser, SDKBaseEntityWithContext
• SDKBaseEvent
• MessageTypeEnum
• EventMessagePayload, ClientMessagePayload, SessionMessagePayload, QueueMessagePayload
• SDKEventsQuotaResponse

Entity Types

• Clients: ClientInput, Client, ShortenedClient
• Sessions: SessionInput, Session, ShortenedSession
• Events: EventContext, Event, ShortenedProperties, ShortenedEvent

Standard Event Types

• AllowedEventTypesEnum
• RatingEvent, FeedbackEvent, BugReportEvent, SurveyEvent, ComplaintEvent
• WorkflowStartedEvent, WorkflowStepCompletedEvent, WorkflowErrorEvent, WorkflowAbortedEvent
• DocumentCreatedEvent, DocumentApprovedEvent, DocumentRejectedEvent
• TaskAssignedEvent, TaskCompletedEvent

Alert Types

• SeverityEnum, EventPropertyEnum, OperatorEnum
• State, Condition, AlertGroupResponse, AlertGroupCreate, AlertGroupUpdate

Notification Types

• NotificationGroupResponse, NotificationGroupCreate, NotificationGroupUpdate

Services

BaseClickHouseService

Abstract base class for ClickHouse database operations. Extend this class to create service-specific implementations.

Features:

• Automatic database and table initialization
• Connection management with lazy initialization
• Batch insert support
• Query execution with typed results
• Timestamp formatting utilities

Example Usage:

import {
  BaseClickHouseService,
  type ClickHouseConfig,
} from 'data-studio-shared';

class MyClickHouseService extends BaseClickHouseService {
  protected async initializeTables(): Promise<void> {
    // Implement table creation logic
    await this.executeQuery(`
      CREATE TABLE IF NOT EXISTS ${this.databaseName}.my_table (
        id String,
        data String
      ) ENGINE = MergeTree() ORDER BY id
    `);
  }

  async insertMyData(data: { id: string; data: string }): Promise<void> {
    await this.insert('my_table', data);
  }
}

const config: ClickHouseConfig = {
  clickhouseUrl: 'http://localhost:8123',
  clickhouseUsername: 'default',
  clickhousePassword: 'password',
};

const service = new MyClickHouseService(config);
await service.insertMyData({ id: '1', data: 'example' });
await service.close();

EventsMapper

Service for mapping standard events to the internal event format. Provides methods for processing feedback, quality, workflow, and business process events. Also includes event category functionality for organizing and retrieving events by category.

Features:

• Map standard events to internal format
• Get category for any event type
• Retrieve all events in a specific category
• Validate event types
• List all available categories and event types

Event Categories:

• Feedback and Quality: rating, feedback_submitted, bug_reported, survey, complaint_received
• Workflow and Business Process: workflow_started, workflow_step_completed, workflow_error, workflow_aborted, document_created, document_approved, document_rejected, task_assigned, task_completed
• Custom: custom

Example Usage:

import { EventsMapper, EventCategoryEnum, AllowedEventTypesEnum } from 'data-studio-shared';
import type { RatingEvent, EventContext } from 'data-studio-shared';

const mapper = new EventsMapper();

// Event mapping example
const ratingEvent: RatingEvent = {
  rating: 5,
  max: 5,
  source: 'web',
  raterId: 'user123',
};

const context: EventContext = {
  id: 'event-1',
  tenantId: 'tenant-1',
  sessionId: 'session-1',
  timestamp: Date.now(),
};

const mappedEvent = mapper.processRatingEvent(ratingEvent, context);

// Event category examples
// Get category info for 'rating' event
const ratingInfo = mapper.getEventCategoryInfo(AllowedEventTypesEnum.RATING);
console.log(ratingInfo.eventType); // 'rating'
console.log(ratingInfo.category); // 'Feedback and Quality'
console.log(ratingInfo.eventsInCategory);
// ['rating', 'feedback_submitted', 'bug_reported', 'survey', 'complaint_received']

// Get just the category
const category = mapper.getCategory('rating');
// Returns: EventCategoryEnum.FEEDBACK_AND_QUALITY

// Get all events in a category
const feedbackEvents = mapper.getEventsByCategory(
  EventCategoryEnum.FEEDBACK_AND_QUALITY
);
// Returns: ['rating', 'feedback_submitted', 'bug_reported', 'survey', 'complaint_received']

// Validate event type
const isValid = mapper.isValidEventType('rating'); // true

Schemas

ClickHouse table schema definitions for consistent database structure across services.

Exports:

• CLICKHOUSE_DATABASE_NAME - Database name constant ("data_studio")
• getClientsTableSchema(databaseName) - Clients table schema
• getSessionsTableSchema(databaseName) - Sessions table schema
• getEventsTableSchema(databaseName) - Events table schema
• getAlertsTableSchema(databaseName) - Alerts table schema

Example Usage:

import {
  CLICKHOUSE_DATABASE_NAME,
  getEventsTableSchema,
} from 'data-studio-shared';

const schema = getEventsTableSchema(CLICKHOUSE_DATABASE_NAME);
await clickhouseClient.exec({ query: schema });

Development

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Watch mode for development
• npm run clean - Remove dist directory
• npm run lint - Run ESLint
• npm run lint:fix - Fix ESLint errors
• npm run format - Format code with Prettier
• npm run format:check - Check code formatting

Project Structure

src/
├── index.ts                    # Main entry point with all exports
├── schemas/
│   └── clickhouse.schemas.ts   # ClickHouse table schema definitions
├── services/
│   ├── clickhouse-base.service.ts      # Base ClickHouse service class
│   ├── events-mapper.service.ts        # Event mapping service
│   └── standard-events/                # Standard event processors
│       ├── feedback-and-quality-events.service.ts
│       └── workflow-and-business-process-events.service.ts
└── types/                      # TypeScript type definitions
    ├── alerts.types.ts
    ├── client.types.ts
    ├── common.types.ts
    ├── events.types.ts
    ├── notifications.types.ts
    ├── session.types.ts
    └── standardEvents.types.ts

Dependencies

• @clickhouse/client - Official ClickHouse client for Node.js

License

ISC