@qrush/types 2.1.32 → 2.1.33

package/dist/CSVImport.d.ts

@@ -0,0 +1,147 @@
+/**
+ * CSV Import Types and Utilities
+ *
+ * This module provides types, validation rules, and utility functions
+ * for importing events from CSV files.
+ */
+import { TicketType, IFireEvent, EventCategorySlug } from "./Events.js";
+import { SupportedLanguage } from "./Common.js";
+import musicGenres from "./Genres.js";
+/**
+ * Represents a single row from the CSV import file.
+ * Column names are human-readable for ease of use by non-technical users.
+ */
+export interface CSVEventRow {
+    "Event Title": string;
+    Description: string;
+    "Start Date": string;
+    "End Date": string;
+    "Venue Name": string;
+    City: string;
+    "Image URL": string;
+    "Ticket Link"?: string;
+    "Base Price"?: string;
+    "Ticket Options"?: string;
+    "Sold Out"?: string;
+    Artists?: string;
+    Categories?: string;
+    "Main Genre"?: string;
+    "Sub Genres"?: string;
+    Tags?: string;
+    "Host Name"?: string;
+    Language?: string;
+    "Description (DE)"?: string;
+    "Description (EN)"?: string;
+    "Description (ES)"?: string;
+}
+/**
+ * Maps CSV column names to internal IFireEvent field paths.
+ * Used for transforming CSV data to Firestore documents.
+ */
+export declare const CSV_COLUMN_MAPPING: {
+    readonly "Event Title": "name";
+    readonly Description: "descriptionMarkdown";
+    readonly "Start Date": "eventStart";
+    readonly "End Date": "eventEnd";
+    readonly "Venue Name": "_venueNameForMatching";
+    readonly City: "_cityForMatching";
+    readonly "Image URL": "imageURI";
+    readonly "Ticket Link": "properties.ticketURL";
+    readonly "Base Price": "properties.price";
+    readonly "Ticket Options": "properties.tickets";
+    readonly "Sold Out": "properties.ticketsSoldOut";
+    readonly Artists: "artists";
+    readonly Categories: "categorySlug";
+    readonly "Main Genre": "genres.mainGenre";
+    readonly "Sub Genres": "genres.subGenres";
+    readonly Tags: "tags";
+    readonly "Host Name": "hostName";
+    readonly Language: "primaryLang";
+    readonly "Description (DE)": "descriptionTranslations.de";
+    readonly "Description (EN)": "descriptionTranslations.en";
+    readonly "Description (ES)": "descriptionTranslations.es";
+};
+export type CSVColumnName = keyof typeof CSV_COLUMN_MAPPING;
+export type CSVFieldPath = (typeof CSV_COLUMN_MAPPING)[CSVColumnName];
+export type CSVFieldType = "string" | "date" | "url" | "number" | "boolean" | "list";
+export interface ValidationResult {
+    valid: boolean;
+    error?: string;
+    transformed?: unknown;
+}
+export interface CSVValidationRule {
+    required: boolean;
+    type: CSVFieldType;
+    validate?: (value: string) => ValidationResult;
+}
+export interface CSVRowValidationResult {
+    rowIndex: number;
+    valid: boolean;
+    errors: {
+        field: string;
+        message: string;
+    }[];
+    warnings: {
+        field: string;
+        message: string;
+    }[];
+    data?: Partial<IFireEvent>;
+}
+export interface CSVImportSummary {
+    totalRows: number;
+    validRows: number;
+    invalidRows: number;
+    warningRows: number;
+    results: CSVRowValidationResult[];
+}
+/**
+ * Validation rules for each CSV column.
+ * Defines required/optional status, type, and custom validation functions.
+ */
+export declare const CSV_VALIDATION_RULES: Record<keyof CSVEventRow, CSVValidationRule>;
+/**
+ * Parses a date string in EU format (DD.MM.YYYY HH:mm) or ISO 8601.
+ * @param dateStr The date string to parse
+ * @returns A Date object or null if parsing fails
+ */
+export declare function parseEUDate(dateStr: string): Date | null;
+/**
+ * Parses ticket options string in format "Name:Price;Name:Price"
+ * @param optionsStr The ticket options string
+ * @returns Array of TicketType objects
+ */
+export declare function parseTicketOptions(optionsStr: string): TicketType[];
+/**
+ * Parses a comma-separated list into an array of trimmed strings
+ * @param str The comma-separated string
+ * @returns Array of trimmed strings
+ */
+export declare function parseCommaSeparatedList(str: string): string[];
+/**
+ * Validates if a string is a valid event category slug
+ */
+export declare function isValidEventCategorySlug(slug: string): slug is EventCategorySlug;
+/**
+ * Validates if a string is a valid music genre
+ */
+export declare function isValidGenre(genre: string): genre is keyof typeof musicGenres;
+/**
+ * Validates if a string is a valid supported language
+ */
+export declare function isValidLanguage(lang: string): lang is SupportedLanguage;
+/**
+ * Validates a single CSV row and returns validation result
+ */
+export declare function validateCSVRow(row: Partial<CSVEventRow>, rowIndex: number): CSVRowValidationResult;
+/**
+ * Returns the required CSV headers for import
+ */
+export declare function getCSVHeaders(): string[];
+/**
+ * Returns only the required CSV headers
+ */
+export declare function getRequiredCSVHeaders(): string[];
+/**
+ * Sample CSV template row with example data
+ */
+export declare const CSV_TEMPLATE_EXAMPLE: CSVEventRow;

package/dist/CSVImport.js

@@ -0,0 +1,529 @@
+/**
+ * CSV Import Types and Utilities
+ *
+ * This module provides types, validation rules, and utility functions
+ * for importing events from CSV files.
+ */
+import { EVENT_CATEGORY_SLUGS } from "./Common.js";
+import musicGenres from "./Genres.js";
+// ==========================================
+// B. CSV_COLUMN_MAPPING Constant
+// ==========================================
+/**
+ * Maps CSV column names to internal IFireEvent field paths.
+ * Used for transforming CSV data to Firestore documents.
+ */
+export const CSV_COLUMN_MAPPING = {
+    "Event Title": "name",
+    Description: "descriptionMarkdown",
+    "Start Date": "eventStart",
+    "End Date": "eventEnd",
+    "Venue Name": "_venueNameForMatching", // Internal use for location matching
+    City: "_cityForMatching", // Internal use for location matching
+    "Image URL": "imageURI",
+    "Ticket Link": "properties.ticketURL",
+    "Base Price": "properties.price",
+    "Ticket Options": "properties.tickets",
+    "Sold Out": "properties.ticketsSoldOut",
+    Artists: "artists",
+    Categories: "categorySlug",
+    "Main Genre": "genres.mainGenre",
+    "Sub Genres": "genres.subGenres",
+    Tags: "tags",
+    "Host Name": "hostName",
+    Language: "primaryLang",
+    "Description (DE)": "descriptionTranslations.de",
+    "Description (EN)": "descriptionTranslations.en",
+    "Description (ES)": "descriptionTranslations.es",
+};
+// ==========================================
+// D. CSV_VALIDATION_RULES Constant
+// ==========================================
+/**
+ * Validation rules for each CSV column.
+ * Defines required/optional status, type, and custom validation functions.
+ */
+export const CSV_VALIDATION_RULES = {
+    "Event Title": {
+        required: true,
+        type: "string",
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return { valid: false, error: "Event title is required" };
+            }
+            if (value.length > 200) {
+                return { valid: false, error: "Event title must be 200 characters or less" };
+            }
+            return { valid: true, transformed: value.trim() };
+        },
+    },
+    Description: {
+        required: true,
+        type: "string",
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return { valid: false, error: "Description is required" };
+            }
+            return { valid: true, transformed: value.trim() };
+        },
+    },
+    "Start Date": {
+        required: true,
+        type: "date",
+        validate: (value) => {
+            const parsed = parseEUDate(value);
+            if (!parsed) {
+                return {
+                    valid: false,
+                    error: "Invalid date format. Use DD.MM.YYYY HH:mm or ISO 8601",
+                };
+            }
+            return { valid: true, transformed: parsed };
+        },
+    },
+    "End Date": {
+        required: true,
+        type: "date",
+        validate: (value) => {
+            const parsed = parseEUDate(value);
+            if (!parsed) {
+                return {
+                    valid: false,
+                    error: "Invalid date format. Use DD.MM.YYYY HH:mm or ISO 8601",
+                };
+            }
+            return { valid: true, transformed: parsed };
+        },
+    },
+    "Venue Name": {
+        required: true,
+        type: "string",
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return { valid: false, error: "Venue name is required" };
+            }
+            return { valid: true, transformed: value.trim() };
+        },
+    },
+    City: {
+        required: true,
+        type: "string",
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return { valid: false, error: "City is required" };
+            }
+            return { valid: true, transformed: value.trim() };
+        },
+    },
+    "Image URL": {
+        required: true,
+        type: "url",
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return { valid: false, error: "Image URL is required" };
+            }
+            try {
+                new URL(value);
+                return { valid: true, transformed: value.trim() };
+            }
+            catch {
+                return { valid: false, error: "Invalid URL format" };
+            }
+        },
+    },
+    "Ticket Link": {
+        required: false,
+        type: "url",
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return { valid: true, transformed: undefined };
+            }
+            try {
+                new URL(value);
+                return { valid: true, transformed: value.trim() };
+            }
+            catch {
+                return { valid: false, error: "Invalid URL format" };
+            }
+        },
+    },
+    "Base Price": {
+        required: false,
+        type: "number",
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return { valid: true, transformed: undefined };
+            }
+            const num = parseFloat(value.replace(",", "."));
+            if (isNaN(num) || num < 0) {
+                return { valid: false, error: "Price must be a positive number" };
+            }
+            return { valid: true, transformed: num };
+        },
+    },
+    "Ticket Options": {
+        required: false,
+        type: "string",
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return { valid: true, transformed: undefined };
+            }
+            const tickets = parseTicketOptions(value);
+            if (tickets.length === 0) {
+                return {
+                    valid: false,
+                    error: "Invalid ticket format. Use Name:Price;Name:Price",
+                };
+            }
+            return { valid: true, transformed: tickets };
+        },
+    },
+    "Sold Out": {
+        required: false,
+        type: "boolean",
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return { valid: true, transformed: undefined };
+            }
+            const lower = value.toLowerCase().trim();
+            if (lower === "true" || lower === "yes" || lower === "1") {
+                return { valid: true, transformed: true };
+            }
+            if (lower === "false" || lower === "no" || lower === "0") {
+                return { valid: true, transformed: false };
+            }
+            return {
+                valid: false,
+                error: 'Invalid boolean. Use true/false, yes/no, or 1/0',
+            };
+        },
+    },
+    Artists: {
+        required: false,
+        type: "list",
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return { valid: true, transformed: [] };
+            }
+            const artists = parseCommaSeparatedList(value);
+            return { valid: true, transformed: artists };
+        },
+    },
+    Categories: {
+        required: false,
+        type: "list",
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return { valid: true, transformed: [] };
+            }
+            const categories = parseCommaSeparatedList(value);
+            // Validate against known category slugs
+            const validCategories = categories.filter((cat) => isValidEventCategorySlug(cat));
+            const invalidCategories = categories.filter((cat) => !isValidEventCategorySlug(cat));
+            if (invalidCategories.length > 0) {
+                return {
+                    valid: false,
+                    error: `Invalid categories: ${invalidCategories.join(", ")}`,
+                };
+            }
+            return { valid: true, transformed: validCategories };
+        },
+    },
+    "Main Genre": {
+        required: false,
+        type: "string",
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return { valid: true, transformed: undefined };
+            }
+            const genre = value.trim().toLowerCase();
+            if (!isValidGenre(genre)) {
+                return {
+                    valid: false,
+                    error: `Invalid genre: ${genre}. Check allowed genres.`,
+                };
+            }
+            return { valid: true, transformed: genre };
+        },
+    },
+    "Sub Genres": {
+        required: false,
+        type: "list",
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return { valid: true, transformed: [] };
+            }
+            const genres = parseCommaSeparatedList(value);
+            return { valid: true, transformed: genres };
+        },
+    },
+    Tags: {
+        required: false,
+        type: "list",
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return { valid: true, transformed: [] };
+            }
+            return { valid: true, transformed: parseCommaSeparatedList(value) };
+        },
+    },
+    "Host Name": {
+        required: false,
+        type: "string",
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return { valid: true, transformed: undefined };
+            }
+            return { valid: true, transformed: value.trim() };
+        },
+    },
+    Language: {
+        required: false,
+        type: "string",
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return { valid: true, transformed: undefined };
+            }
+            const lang = value.toLowerCase().trim();
+            if (!isValidLanguage(lang)) {
+                return {
+                    valid: false,
+                    error: `Invalid language: ${lang}. Use de, en, or es`,
+                };
+            }
+            return { valid: true, transformed: lang };
+        },
+    },
+    "Description (DE)": {
+        required: false,
+        type: "string",
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return { valid: true, transformed: undefined };
+            }
+            return { valid: true, transformed: value.trim() };
+        },
+    },
+    "Description (EN)": {
+        required: false,
+        type: "string",
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return { valid: true, transformed: undefined };
+            }
+            return { valid: true, transformed: value.trim() };
+        },
+    },
+    "Description (ES)": {
+        required: false,
+        type: "string",
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return { valid: true, transformed: undefined };
+            }
+            return { valid: true, transformed: value.trim() };
+        },
+    },
+};
+// ==========================================
+// E. Parsing Utilities
+// ==========================================
+/**
+ * Parses a date string in EU format (DD.MM.YYYY HH:mm) or ISO 8601.
+ * @param dateStr The date string to parse
+ * @returns A Date object or null if parsing fails
+ */
+export function parseEUDate(dateStr) {
+    if (!dateStr || typeof dateStr !== "string") {
+        return null;
+    }
+    const trimmed = dateStr.trim();
+    // Try ISO 8601 first
+    const isoDate = new Date(trimmed);
+    if (!isNaN(isoDate.getTime()) && trimmed.includes("-")) {
+        return isoDate;
+    }
+    // Try EU format: DD.MM.YYYY HH:mm or DD.MM.YYYY
+    const euPattern = /^(\d{1,2})\.(\d{1,2})\.(\d{4})(?:\s+(\d{1,2}):(\d{2}))?$/;
+    const match = trimmed.match(euPattern);
+    if (!match) {
+        return null;
+    }
+    const day = parseInt(match[1], 10);
+    const month = parseInt(match[2], 10) - 1; // JavaScript months are 0-indexed
+    const year = parseInt(match[3], 10);
+    const hour = match[4] ? parseInt(match[4], 10) : 0;
+    const minute = match[5] ? parseInt(match[5], 10) : 0;
+    // Validate ranges
+    if (month < 0 ||
+        month > 11 ||
+        day < 1 ||
+        day > 31 ||
+        hour < 0 ||
+        hour > 23 ||
+        minute < 0 ||
+        minute > 59) {
+        return null;
+    }
+    const date = new Date(year, month, day, hour, minute);
+    // Check if the date is valid (e.g., catches Feb 30)
+    if (date.getFullYear() !== year ||
+        date.getMonth() !== month ||
+        date.getDate() !== day) {
+        return null;
+    }
+    return date;
+}
+/**
+ * Parses ticket options string in format "Name:Price;Name:Price"
+ * @param optionsStr The ticket options string
+ * @returns Array of TicketType objects
+ */
+export function parseTicketOptions(optionsStr) {
+    if (!optionsStr || typeof optionsStr !== "string") {
+        return [];
+    }
+    const tickets = [];
+    const options = optionsStr.split(";").map((s) => s.trim());
+    for (const option of options) {
+        if (!option)
+            continue;
+        const parts = option.split(":").map((s) => s.trim());
+        if (parts.length !== 2)
+            continue;
+        const [name, priceStr] = parts;
+        const price = parseFloat(priceStr.replace(",", "."));
+        if (!name || isNaN(price) || price < 0)
+            continue;
+        tickets.push({
+            id: generateTicketId(),
+            name,
+            price,
+        });
+    }
+    return tickets;
+}
+/**
+ * Parses a comma-separated list into an array of trimmed strings
+ * @param str The comma-separated string
+ * @returns Array of trimmed strings
+ */
+export function parseCommaSeparatedList(str) {
+    if (!str || typeof str !== "string") {
+        return [];
+    }
+    return str
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+// ==========================================
+// F. Helper Functions
+// ==========================================
+/**
+ * Generates a unique ID for ticket types
+ */
+function generateTicketId() {
+    return `ticket_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+}
+/**
+ * Validates if a string is a valid event category slug
+ */
+export function isValidEventCategorySlug(slug) {
+    return EVENT_CATEGORY_SLUGS.includes(slug.toLowerCase());
+}
+/**
+ * Validates if a string is a valid music genre
+ */
+export function isValidGenre(genre) {
+    return genre in musicGenres;
+}
+/**
+ * Validates if a string is a valid supported language
+ */
+export function isValidLanguage(lang) {
+    return ["de", "en", "es"].includes(lang);
+}
+/**
+ * Validates a single CSV row and returns validation result
+ */
+export function validateCSVRow(row, rowIndex) {
+    const errors = [];
+    const warnings = [];
+    const data = {};
+    for (const [field, rule] of Object.entries(CSV_VALIDATION_RULES)) {
+        const columnName = field;
+        const value = row[columnName] ?? "";
+        // Check required fields
+        if (rule.required && (!value || String(value).trim().length === 0)) {
+            errors.push({ field: columnName, message: `${columnName} is required` });
+            continue;
+        }
+        // Run custom validation if provided
+        if (rule.validate && value) {
+            const result = rule.validate(String(value));
+            if (!result.valid) {
+                if (rule.required) {
+                    errors.push({ field: columnName, message: result.error ?? "Validation failed" });
+                }
+                else {
+                    warnings.push({ field: columnName, message: result.error ?? "Validation failed" });
+                }
+            }
+            else if (result.transformed !== undefined) {
+                const fieldPath = CSV_COLUMN_MAPPING[columnName];
+                data[fieldPath] = result.transformed;
+            }
+        }
+    }
+    return {
+        rowIndex,
+        valid: errors.length === 0,
+        errors,
+        warnings,
+        data: errors.length === 0 ? data : undefined,
+    };
+}
+// ==========================================
+// G. CSV Template
+// ==========================================
+/**
+ * Returns the required CSV headers for import
+ */
+export function getCSVHeaders() {
+    return Object.keys(CSV_VALIDATION_RULES);
+}
+/**
+ * Returns only the required CSV headers
+ */
+export function getRequiredCSVHeaders() {
+    return Object.entries(CSV_VALIDATION_RULES)
+        .filter(([, rule]) => rule.required)
+        .map(([field]) => field);
+}
+/**
+ * Sample CSV template row with example data
+ */
+export const CSV_TEMPLATE_EXAMPLE = {
+    "Event Title": "Summer Night Party",
+    Description: "Join us for an unforgettable summer night!",
+    "Start Date": "14.06.2025 22:00",
+    "End Date": "15.06.2025 06:00",
+    "Venue Name": "Club Matrix",
+    City: "Berlin",
+    "Image URL": "https://example.com/event-image.jpg",
+    "Ticket Link": "https://example.com/tickets",
+    "Base Price": "15.00",
+    "Ticket Options": "Early Bird:12.00;Regular:15.00;VIP:30.00",
+    "Sold Out": "false",
+    Artists: "DJ Shadow, Bonobo, Four Tet",
+    Categories: "clubnight,party",
+    "Main Genre": "techno",
+    "Sub Genres": "house,minimal",
+    Tags: "summer,nightlife,electronic",
+    "Host Name": "Matrix Events",
+    Language: "de",
+    "Description (DE)": "Feiert mit uns eine unvergessliche Sommernacht!",
+    "Description (EN)": "Join us for an unforgettable summer night!",
+    "Description (ES)": "Celebra con nosotros una noche de verano inolvidable!",
+};

package/dist/index.d.ts

@@ -9,3 +9,4 @@ export * from './Meta.js';
 export * from './firebase.js';
 export * from './WebappUsers.js';
 export * from './Artist.js';
+export * from './CSVImport.js';

package/dist/index.js

@@ -9,3 +9,4 @@ export * from './Meta.js';
 export * from './firebase.js';
 export * from './WebappUsers.js';
 export * from './Artist.js';
+export * from './CSVImport.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qrush/types",
-  "version": "2.1.32",
+  "version": "2.1.33",
   "description": "Shared TypeScript types for the QRush ecosystem",
   "type": "module",
   "main": "./dist/index.js",