API Transformer Documentation

Project Overview

This service allows you to add your own integrations, resulting in a standardized output of event data.

This service uses NitroJS. Nitro.js is a framework-agnostic, TypeScript-based server-side rendering engine for NodeJs. Learn more at nitro JS.

Architectural Approach

1. Core API Endpoint

• Create a main API endpoint (e.g., /api/transform-events) that accepts incoming requests.
• This endpoint will determine which integration to use based on the request parameters.

2. Integration Registry

• Implement a registry system where different integrations can be registered and easily added.
• Each integration will have its own transformer function.

3. Transformer Functions

• Create individual transformer functions for each integration.
• These functions will take the raw API data and convert it to the WebEventItem format.

4. Configuration Management

• Implement a configuration system to manage API keys, endpoints, and other integration-specific settings.

5. Error Handling and Logging

• Implement robust error handling for API calls and data transformations.
• Set up logging for debugging and monitoring purposes.

Code Structure

src/
├── server/
│   ├── api/
│   │   └── transform-events.ts
│   ├── integrations/
│   │   ├── integration-registry.ts
│   │   ├── base-transformer.ts
│   │   └── [integration-name]/
│   │       ├── transformer.ts
│   │       └── config.ts
│   ├── utils/
│   │   ├── error-handler.ts
│   │   └── logger.ts
│   └── config/
│       └── integrations-config.ts
├── types/
│   └── web-event-item.ts
└── tests/
    └── integrations/
        └── [integration-name]/
            └── transformer.test.ts
    

API Usage

To use the API, send a POST request to /api/transform-events with the following structure:

{
  "integration": "integration-name",
  "data": {
    // Raw data from the integration's API
  }
}

Data is optional; if not provided, it will be fetched from the integration's API in the config file.

The API will respond with an array of WebEventItem objects.

Adding New Integrations

1. Create a new folder under src/server/integrations/[integration-name].
2. Implement the transformer in transformer.ts.
3. Add any necessary configuration in config.ts.
4. Register the new integration in integration-registry.ts.
5. Add unit tests in tests/integrations/[integration-name]/transformer.test.ts.

Transform Data Extructure

    export interface WebEventItem  {
        backgroundImage: string;
        eventCategoryName: string;
        eventCategoryId: string;
        eventSubCategoryName: string;
        eventSubCategoryId: string;
        eventTitle: string;
        eventSubtitle: string;
        eventDataId: string;
        eventMetatile?: string;
        eventMetaDescription?: string;
        eventOgImage?: string;
        eventOgFocusKeyWords?: string;
        eventModificationDate?: Date;
        eventStatus: EventStatus;
        eventTypologyId: TypologyIds | string;
        eventisActive: boolean;
        eventVivaTypes: string[];
        eventImageUrl?: string;
        areaCode: string;
        areaDescription: string;
        currency: string;
        currentavailability: string;
        eventDescription: string;
        eventGroupId: string;
        eventGroupDescription: string;
        eventId: string;
        isGA: boolean;
        lang: string;
        performanceDate: Date;
        performanceId: string;
        price: string;
        priceMax: string;
        priceMin: string;
        promoterDescription: string;
        promoterId: string;
        reductionCode: string;
        reductionDescription: string;
        redirectUrl: string;
        saleEnd: Date;
        saleStart: Date;
        salesUrl: string;
        serverCode: 'janto' | 'viva' | 'eata' | 'cms';
        systemCode: string;
        totalavailability: string;
        url: string;
        venueAddress: string;
        venueCountry: string;
        venueDescription: string;
        venueId: string;
        googlePlacesId?: string;
        venueImageUrl?: string;
        htmlDescription?: string;
        venueInfoDescription?: string;
        venueInfoSchedule?: string;
        venueInfoUrl?: string;
        venueInfoPhone?: string;
        venueInfoEmail?: string;
        venueInfoMap?: string;
        venueInfoAddress?: string;
        venueInfoCity?: string;
        venueInfoState?: string;
        venueInfoZip?: string;
        venueInfoCountry?: string;
        widget: boolean;
        seoCanBeIndexed?: boolean;
        pixels?:Pixel[];
        recaptchaSiteKey?: string;
        widgetImageUrl?: string;
        headerImageUrl?: string;
        privacyPolicyUrl?: string;
        termsOfServiceUrl?: string;
    };

    interface Pixel {
        type: string;
        provider: string;
        data: PixelData;
    }

    interface PixelData {
        token: number;
    }


    export enum TypologyIds {
        Ticket = "0",
        Tour = "1",
        Programming = "2"
    }

    export enum TypologyTypes {
        Programming = "programming",
        Ticket = "ticket",
        Tour = "tour",
    }

    export enum EventStatus {
        NotVisible = 0,
        VisibleAndSearchable = 1,
        VisibleButNotSearchable = 2
    }