@hrarsha/evand-mcp 0.0.0-stage → 0.1.0

package/dist/evand.js

@@ -0,0 +1,948 @@
+import { formatTehranDate, htmlToText, normalizeIsoDate, normalizePrice, truncateText, } from "./format.js";
+import { flattenCategories, resolveCategory, resolveCity, suggestCategories, suggestCities, } from "./resolver.js";
+const DEFAULT_API_BASE = "https://api.evand.com";
+const DEFAULT_WEB_BASE = "https://evand.com";
+const DEFAULT_TIMEOUT_MS = 20_000;
+const METADATA_TTL_MS = 10 * 60 * 1000;
+const MAX_DESCRIPTION_CHARS = 40_000;
+const EVENT_INCLUDES = [
+    "tags",
+    "type",
+    "city",
+    "prices",
+    "category",
+    "category.parent",
+    "showtimes",
+    "organization",
+    "affiliate",
+    "tickets",
+];
+export class EvandApiError extends Error {
+    status;
+    constructor(message, status = null) {
+        super(message);
+        this.name = "EvandApiError";
+        this.status = status;
+    }
+}
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asString(value) {
+    return typeof value === "string" && value.trim() ? value : null;
+}
+function asNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function truthy(value) {
+    return value === true || value === "yes" || value === "true" || value === 1 || value === "1";
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function coverUrl(value) {
+    if (!value)
+        return null;
+    if (typeof value === "string")
+        return value || null;
+    return value.original ?? null;
+}
+function pickRecord(value) {
+    const record = asRecord(value);
+    if (!record)
+        return null;
+    const data = asRecord(record.data);
+    return data ?? record;
+}
+function joinUrl(base, path) {
+    return `${base.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+function eventUrl(webBase, slug) {
+    return joinUrl(webBase, `events/${encodeURIComponent(slug)}`);
+}
+function organizationUrl(webBase, slug) {
+    return joinUrl(webBase, `organizations/${encodeURIComponent(slug)}`);
+}
+function normalizeSocials(raw) {
+    if (!raw)
+        return {};
+    const keyMap = {
+        tel: "phone",
+        phone: "phone",
+        mobile: "phone",
+        website: "website",
+        instagram: "instagram",
+        linkedin: "linkedin",
+        twitter: "twitter",
+        x: "twitter",
+        facebook: "facebook",
+        telegram: "telegram",
+        telegram_channel: "telegram",
+        telegramChannel: "telegram",
+        youtube: "youtube",
+        github: "github",
+    };
+    const socials = {};
+    for (const [key, rawValue] of Object.entries(raw)) {
+        const value = asString(rawValue);
+        if (!value || value === "undefined" || value === "null")
+            continue;
+        const normalizedKey = keyMap[key] ?? key;
+        socials[normalizedKey] = value;
+    }
+    return socials;
+}
+function normalizeOrganizationRef(value, webBase) {
+    const record = asRecord(value);
+    if (!record)
+        return null;
+    const data = asRecord(record.data) ?? record;
+    const name = asString(data.name);
+    const slug = asString(data.slug);
+    if (!name && !slug)
+        return null;
+    return {
+        name,
+        slug,
+        url: slug ? organizationUrl(webBase, slug) : null,
+        logo: coverUrl(data.logo),
+    };
+}
+function parsePagination(meta) {
+    const metaRecord = asRecord(meta);
+    const pagination = asRecord(metaRecord?.pagination);
+    const currentPage = asNumber(pagination?.current_page) ?? 1;
+    const totalPages = asNumber(pagination?.total_pages);
+    return {
+        total: asNumber(pagination?.total),
+        count: asNumber(pagination?.count),
+        per_page: asNumber(pagination?.per_page),
+        current_page: currentPage,
+        total_pages: totalPages,
+        has_more: totalPages !== null ? currentPage < totalPages : false,
+    };
+}
+function parseEventDate(value, field) {
+    if (!value)
+        return null;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        throw new EvandApiError(`Invalid ${field} "${value}". Use YYYY-MM-DD (for example 2026-11-20).`);
+    }
+    const date = new Date(`${value}T00:00:00Z`);
+    if (Number.isNaN(date.getTime()) || date.toISOString().slice(0, 10) !== value) {
+        throw new EvandApiError(`Invalid ${field} "${value}". Use a real calendar date in YYYY-MM-DD format.`);
+    }
+    return value;
+}
+export class EvandClient {
+    apiBase;
+    webBase;
+    timeoutMs;
+    debug;
+    citiesCache = null;
+    citiesPromise = null;
+    categoriesCache = null;
+    categoriesPromise = null;
+    constructor(options = {}) {
+        this.apiBase = (options.apiBase ?? process.env.EVAND_API_BASE_URL ?? DEFAULT_API_BASE).replace(/\/+$/, "");
+        this.webBase = (options.webBase ?? process.env.EVAND_WEB_BASE_URL ?? DEFAULT_WEB_BASE).replace(/\/+$/, "");
+        this.timeoutMs = options.timeoutMs ?? Number(process.env.EVAND_TIMEOUT_MS ?? DEFAULT_TIMEOUT_MS);
+        this.debug = options.debug ?? process.env.EVAND_MCP_DEBUG === "1";
+    }
+    log(message, details) {
+        if (!this.debug)
+            return;
+        if (details === undefined) {
+            console.error(`[evand-mcp] ${message}`);
+        }
+        else {
+            console.error(`[evand-mcp] ${message}`, details);
+        }
+    }
+    async request(path, params = {}, attempt = 0) {
+        const url = new URL(path, `${this.apiBase}/`);
+        for (const [key, value] of Object.entries(params)) {
+            if (value === undefined || value === null || value === "")
+                continue;
+            url.searchParams.set(key, String(value));
+        }
+        const timeoutMs = Number.isFinite(this.timeoutMs)
+            ? Math.min(60_000, Math.max(1_000, this.timeoutMs))
+            : DEFAULT_TIMEOUT_MS;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        let response;
+        try {
+            response = await fetch(url, {
+                headers: {
+                    Accept: "application/json",
+                    "User-Agent": "evand-mcp/0.1.0 (+https://evand.com)",
+                },
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            clearTimeout(timeout);
+            const isAbort = controller.signal.aborted;
+            if (attempt < 2) {
+                this.log(`${isAbort ? "Timeout" : "Network error"} on ${url.pathname}; retrying`);
+                await sleep(500 * 2 ** attempt);
+                return this.request(path, params, attempt + 1);
+            }
+            const reason = isAbort ? `timed out after ${timeoutMs}ms` : error.message;
+            throw new EvandApiError(`Could not reach the Evand API (${reason}). Try again shortly.`);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+        const text = await response.text();
+        let body = null;
+        if (text) {
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                body = null;
+            }
+        }
+        if (!response.ok) {
+            const record = asRecord(body);
+            const apiMessage = asString(record?.message);
+            const errors = asRecord(record?.errors);
+            const validationMessage = errors
+                ? Object.values(errors)
+                    .flatMap((value) => (Array.isArray(value) ? value : [value]))
+                    .map((value) => String(value))
+                    .join("; ")
+                : null;
+            const message = validationMessage || apiMessage || response.statusText || "Unknown error";
+            const retryable = response.status === 429 || response.status >= 500;
+            if (retryable && attempt < 2) {
+                const retryAfter = Number(response.headers.get("retry-after"));
+                const delay = Number.isFinite(retryAfter) && retryAfter > 0
+                    ? Math.min(5_000, retryAfter * 1_000)
+                    : 500 * 2 ** attempt;
+                this.log(`HTTP ${response.status} on ${url.pathname}; retrying in ${delay}ms`);
+                await sleep(delay);
+                return this.request(path, params, attempt + 1);
+            }
+            throw new EvandApiError(`Evand API error (HTTP ${response.status}): ${message}`, response.status);
+        }
+        if (body === null) {
+            throw new EvandApiError(`Evand API returned an invalid JSON response for ${url.pathname}.`, response.status);
+        }
+        return body;
+    }
+    async getCities(forceRefresh = false) {
+        const now = Date.now();
+        if (!forceRefresh && this.citiesCache && this.citiesCache.expiresAt > now) {
+            return this.citiesCache.data;
+        }
+        if (!forceRefresh && this.citiesPromise)
+            return this.citiesPromise;
+        const promise = this.request("/cities", {
+            include: "province",
+            sort: "eventCount",
+        })
+            .then((response) => {
+            const cities = Array.isArray(response.data) ? response.data : [];
+            this.citiesCache = { expiresAt: Date.now() + METADATA_TTL_MS, data: cities };
+            return cities;
+        })
+            .catch((error) => {
+            this.citiesPromise = null;
+            throw error;
+        })
+            .finally(() => {
+            this.citiesPromise = null;
+        });
+        this.citiesPromise = promise;
+        return promise;
+    }
+    async getCategories(forceRefresh = false) {
+        const now = Date.now();
+        if (!forceRefresh && this.categoriesCache && this.categoriesCache.expiresAt > now) {
+            return this.categoriesCache.data;
+        }
+        if (!forceRefresh && this.categoriesPromise)
+            return this.categoriesPromise;
+        const promise = this.request("/categories", {
+            include: "children",
+            order: "-1",
+            sort: "eventCount",
+        })
+            .then((response) => {
+            const categories = Array.isArray(response.data) ? response.data : [];
+            this.categoriesCache = { expiresAt: Date.now() + METADATA_TTL_MS, data: categories };
+            return categories;
+        })
+            .catch((error) => {
+            this.categoriesPromise = null;
+            throw error;
+        })
+            .finally(() => {
+            this.categoriesPromise = null;
+        });
+        this.categoriesPromise = promise;
+        return promise;
+    }
+    async resolveFilters(input) {
+        const cities = [];
+        const cityInputs = (input.city ?? "")
+            .split(",")
+            .map((value) => value.trim())
+            .filter(Boolean);
+        if (cityInputs.length > 0) {
+            const allCities = await this.getCities();
+            for (const cityInput of cityInputs) {
+                const city = resolveCity(allCities, cityInput);
+                if (!city) {
+                    throw new EvandApiError(`City "${cityInput}" was not found on Evand. Try one of: ${suggestCities(allCities, cityInput).join(", ")}.`);
+                }
+                cities.push(city);
+            }
+        }
+        let category = null;
+        if (input.category?.trim()) {
+            const allCategories = flattenCategories(await this.getCategories());
+            category = resolveCategory(allCategories, input.category);
+            if (!category) {
+                throw new EvandApiError(`Category "${input.category}" was not found on Evand. Try one of: ${suggestCategories(allCategories, input.category).join(", ")}.`);
+            }
+        }
+        const appliedCity = cities.length === 1 && cities[0]
+            ? { name: cities[0].name, slug: cities[0].slug }
+            : null;
+        return {
+            cities,
+            category,
+            appliedCity,
+            appliedCategory: category
+                ? { title: category.title, slug: category.slug, parent: category.parentTitle }
+                : null,
+        };
+    }
+    async searchEvents(input) {
+        const page = Math.max(1, Math.trunc(input.page ?? 1));
+        const perPage = Math.min(50, Math.max(1, Math.trunc(input.per_page ?? 12)));
+        const from = parseEventDate(input.start_date_from, "start_date_from");
+        const to = parseEventDate(input.start_date_to, "start_date_to");
+        if (from && to && from > to) {
+            throw new EvandApiError("start_date_from must be before or equal to start_date_to.");
+        }
+        if (input.min_price !== undefined &&
+            input.max_price !== undefined &&
+            input.min_price > input.max_price) {
+            throw new EvandApiError("min_price must be less than or equal to max_price.");
+        }
+        const resolved = await this.resolveFilters(input);
+        const sort = input.sort ?? "nearest";
+        const sortParam = sort === "nearest"
+            ? undefined
+            : sort === "trending"
+                ? "trending"
+                : sort === "bestsellers"
+                    ? "bestsellers"
+                    : sort === "randomness"
+                        ? "randomness"
+                        : "start_date";
+        const response = await this.request("/v2/events", {
+            per_page: perPage,
+            page,
+            q: input.query?.trim() || undefined,
+            cities: resolved.cities.length ? resolved.cities.map((city) => city.slug).join(",") : undefined,
+            categories: resolved.category?.slug,
+            online: input.online === true ? "yes" : input.online === false ? "no" : undefined,
+            archive: input.include_past === true ? "yes" : undefined,
+            min_price: input.min_price,
+            max_price: input.max_price,
+            min_start_date: from ?? undefined,
+            max_start_date: to ?? undefined,
+            sort: sortParam,
+        });
+        const events = (Array.isArray(response.data) ? response.data : [])
+            .map((event) => this.normalizeEventSummary(event))
+            .filter((event) => event !== null);
+        return {
+            filters: {
+                query: input.query?.trim() || null,
+                city: resolved.appliedCity,
+                category: resolved.appliedCategory,
+                online: input.online ?? null,
+                include_past: input.include_past ?? false,
+                price: input.min_price !== undefined || input.max_price !== undefined
+                    ? {
+                        min: input.min_price ?? null,
+                        max: input.max_price ?? null,
+                        currency: "Toman",
+                    }
+                    : null,
+                start_date: from || to
+                    ? { from: from ?? null, to: to ?? null, timezone: "Asia/Tehran" }
+                    : null,
+                sort,
+            },
+            pagination: parsePagination(response.meta),
+            events,
+        };
+    }
+    async getEvent(slug, options = {}) {
+        const includeDescription = options.includeDescription !== false;
+        const maxDescriptionChars = Math.min(MAX_DESCRIPTION_CHARS, Math.max(0, Math.trunc(options.maxDescriptionChars ?? 8_000)));
+        let eventResponse;
+        try {
+            eventResponse = await this.request(`/events/${encodeURIComponent(slug)}`, { include: EVENT_INCLUDES.join(",") });
+        }
+        catch (error) {
+            if (error instanceof EvandApiError && error.status === 404) {
+                throw new EvandApiError(`Event "${slug}" was not found on Evand. Use search_events to find the correct slug, or pass a full https://evand.com/events/<slug> URL.`, 404);
+            }
+            throw error;
+        }
+        if (!eventResponse?.data) {
+            throw new EvandApiError(`Event "${slug}" was not found on Evand.`, 404);
+        }
+        if (!includeDescription || maxDescriptionChars <= 0) {
+            return normalizeEventDetail(eventResponse.data, this.webBase, null);
+        }
+        const descriptionResponse = await this.request(`/events/${encodeURIComponent(slug)}/description`).catch((error) => {
+            this.log(`Could not load description for ${slug}`, error.message);
+            return { data: [] };
+        });
+        const description = normalizeDescription(descriptionResponse.data, maxDescriptionChars);
+        return normalizeEventDetail(eventResponse.data, this.webBase, description);
+    }
+    async getSimilarEvents(slug, limit = 6) {
+        const perPage = Math.min(12, Math.max(1, Math.trunc(limit)));
+        let response;
+        try {
+            response = await this.request(`/recommendation/events/${encodeURIComponent(slug)}/similar`, { per_page: perPage });
+        }
+        catch (error) {
+            if (error instanceof EvandApiError && error.status === 404) {
+                throw new EvandApiError(`Event "${slug}" was not found on Evand, so similar events cannot be loaded. Use search_events to find the correct slug.`, 404);
+            }
+            throw error;
+        }
+        return (Array.isArray(response.data) ? response.data : [])
+            .slice(0, perPage)
+            .map((event) => this.normalizeSimilarEvent(event))
+            .filter((event) => event !== null);
+    }
+    async listCities(query, limit = 30, includeEmpty = false) {
+        const allCities = await this.getCities();
+        const needle = query?.trim().toLowerCase() ?? "";
+        const filtered = allCities.filter((city) => {
+            if (!includeEmpty && (city.events_count ?? 0) <= 0)
+                return false;
+            if (!needle)
+                return true;
+            const haystack = [city.name, city.slug, city.province?.data?.name ?? ""]
+                .join(" ")
+                .toLowerCase();
+            return haystack.includes(needle);
+        });
+        let results = filtered;
+        if (needle && results.length === 0) {
+            const resolved = resolveCity(allCities, query.trim());
+            if (resolved)
+                results = [resolved];
+        }
+        const max = Math.min(100, Math.max(1, Math.trunc(limit)));
+        return {
+            total: results.length,
+            cities: results.slice(0, max).map((city) => ({
+                id: city.id,
+                name: city.name,
+                slug: city.slug,
+                events_count: city.events_count ?? 0,
+                province: city.province?.data?.name ?? null,
+                url: joinUrl(this.webBase, `city/${encodeURIComponent(city.slug)}`),
+            })),
+        };
+    }
+    async listCategories(query, limit = 100) {
+        const flat = flattenCategories(await this.getCategories());
+        const needle = query?.trim().toLowerCase() ?? "";
+        let filtered = needle
+            ? flat.filter((category) => [category.title, category.slug, category.parentTitle ?? ""]
+                .join(" ")
+                .toLowerCase()
+                .includes(needle))
+            : flat;
+        if (needle && filtered.length === 0) {
+            const resolved = resolveCategory(flat, query.trim());
+            if (resolved)
+                filtered = [resolved];
+        }
+        const max = Math.min(300, Math.max(1, Math.trunc(limit)));
+        return {
+            total: filtered.length,
+            categories: filtered.slice(0, max).map((category) => ({
+                id: category.id,
+                title: category.title,
+                slug: category.slug,
+                parent: category.parentTitle,
+                events_count: category.events_count,
+                url: joinUrl(this.webBase, `categories/${encodeURIComponent(category.slug)}`),
+            })),
+        };
+    }
+    async searchOrganizations(input = {}) {
+        const page = Math.max(1, Math.trunc(input.page ?? 1));
+        const perPage = Math.min(50, Math.max(1, Math.trunc(input.per_page ?? 12)));
+        const sort = input.sort === "bestsellers"
+            ? "bestsellers"
+            : input.sort === "partnerships"
+                ? "partnerships"
+                : "followersCount";
+        const response = await this.request("/organizations", {
+            q: input.query?.trim() || undefined,
+            sort,
+            page,
+            per_page: perPage,
+        });
+        return {
+            pagination: parsePagination(response.meta),
+            organizations: (Array.isArray(response.data) ? response.data : [])
+                .map((organization) => this.normalizeOrganizationSummary(organization))
+                .filter((organization) => organization !== null),
+        };
+    }
+    async getOrganization(slug, options = {}) {
+        let response;
+        try {
+            response = await this.request(`/organizations/${encodeURIComponent(slug)}`);
+        }
+        catch (error) {
+            if (error instanceof EvandApiError && error.status === 404) {
+                throw new EvandApiError(`Organization "${slug}" was not found on Evand. Use search_organizations to find the correct slug, or pass a full https://evand.com/organizations/<slug> URL.`, 404);
+            }
+            throw error;
+        }
+        if (!response?.data) {
+            throw new EvandApiError(`Organization "${slug}" was not found on Evand.`, 404);
+        }
+        const includeEvents = options.includeEvents !== false;
+        const eventsLimit = Math.min(30, Math.max(1, Math.trunc(options.eventsLimit ?? 12)));
+        const maxDescriptionChars = Math.min(20_000, Math.max(0, Math.trunc(options.maxDescriptionChars ?? 4_000)));
+        let events = [];
+        if (includeEvents) {
+            const orgId = asString(response.data.id);
+            if (orgId) {
+                const eventResponse = await this.request("/v2/events", {
+                    organization_id: orgId,
+                    per_page: eventsLimit,
+                    archive: options.includePastEvents ? "yes" : undefined,
+                    sort: options.includePastEvents ? "start_date" : undefined,
+                }).catch((error) => {
+                    this.log(`Could not load events for organization ${slug}`, error.message);
+                    return { data: [] };
+                });
+                events = (Array.isArray(eventResponse.data) ? eventResponse.data : [])
+                    .map((event) => this.normalizeEventSummary(event))
+                    .filter((event) => event !== null);
+            }
+        }
+        const summary = this.normalizeOrganizationSummary(response.data, maxDescriptionChars);
+        if (!summary) {
+            throw new EvandApiError(`Organization "${slug}" could not be parsed.`, 404);
+        }
+        return {
+            ...summary,
+            events,
+        };
+    }
+    normalizeEventSummary(event) {
+        if (!event || typeof event.id !== "number" || !event.slug)
+            return null;
+        const organization = normalizeOrganizationRef(event.organization, this.webBase);
+        const price = normalizePrice(event.minimum_ticket_price ?? event.prices?.data?.min, event.maximum_ticket_price ?? event.prices?.data?.max);
+        return {
+            id: event.id,
+            name: event.name ?? "",
+            slug: event.slug,
+            url: eventUrl(this.webBase, event.slug),
+            start_date: normalizeIsoDate(event.start_date),
+            end_date: normalizeIsoDate(event.end_date),
+            start_date_tehran: formatTehranDate(event.start_date),
+            end_date_tehran: formatTehranDate(event.end_date),
+            online: truthy(event.online),
+            city: asString(event.city_name),
+            address: asString(event.address),
+            organization,
+            price,
+            status: {
+                ended: event.ended === true,
+                sold_out: event.soldout === true,
+                cancelled: event.cancelled === true,
+                partnership: asString(event.partnership?.status),
+            },
+            cover: coverUrl(event.cover),
+        };
+    }
+    normalizeSimilarEvent(event) {
+        if (!event || !event.slug)
+            return null;
+        const price = normalizePrice(event.minimum_ticket_price, event.maximum_ticket_price);
+        return {
+            id: event.id ?? null,
+            name: event.name ?? "",
+            slug: event.slug,
+            url: eventUrl(this.webBase, event.slug),
+            start_date: normalizeIsoDate(event.start_date),
+            end_date: normalizeIsoDate(event.end_date),
+            start_date_tehran: formatTehranDate(event.start_date),
+            end_date_tehran: formatTehranDate(event.end_date),
+            online: truthy(event.online),
+            city: asString(event.city_name),
+            address: null,
+            organization: event.organization_slug || event.organization_name
+                ? {
+                    name: asString(event.organization_name),
+                    slug: asString(event.organization_slug),
+                    url: event.organization_slug ? organizationUrl(this.webBase, event.organization_slug) : null,
+                    logo: asString(event.organization_logo),
+                }
+                : null,
+            price,
+            status: {
+                ended: false,
+                sold_out: false,
+                cancelled: false,
+                partnership: null,
+            },
+            cover: coverUrl(event.cover),
+        };
+    }
+    normalizeOrganizationSummary(organization, descriptionLimit = 400) {
+        const slug = asString(organization.slug);
+        const name = asString(organization.name);
+        if (!slug && !name)
+            return null;
+        const descriptionHtml = asString(organization.description) ?? asString(organization.striped_description) ?? "";
+        const description = htmlToText(descriptionHtml);
+        const recommended = organization;
+        const recommendedPercent = asNumber(recommended.recommended?.value?.percent_of_recommended);
+        const effectiveSlug = slug ?? name;
+        return {
+            id: asString(organization.id),
+            name: name ?? effectiveSlug,
+            slug: effectiveSlug,
+            url: organizationUrl(this.webBase, effectiveSlug),
+            logo: coverUrl(organization.logo),
+            cover: coverUrl(organization.cover),
+            description: truncateText(description, descriptionLimit).text,
+            followers_count: asNumber(organization.followers_count),
+            events_count: asNumber(organization.events_count),
+            active_events_count: asNumber(organization.active_events_count),
+            partnership: asString(organization.partnership?.status),
+            recommended_percent: recommendedPercent,
+            socials: normalizeSocials(organization.socials),
+        };
+    }
+}
+function normalizeDescriptionSections(raw) {
+    const sections = [];
+    let truncated = false;
+    for (const section of Array.isArray(raw) ? raw : []) {
+        const type = asString(section.type) ?? "description";
+        const title = asString(section.title);
+        const body = htmlToText(section.description) ||
+            (typeof section.content === "string" ? htmlToText(section.content) : "");
+        const content = section.content;
+        let items = null;
+        if (Array.isArray(content)) {
+            items = content
+                .map((item) => {
+                if (typeof item === "string" || typeof item === "number") {
+                    return { name: String(item) };
+                }
+                const itemRecord = asRecord(item);
+                if (!itemRecord)
+                    return null;
+                const normalized = {};
+                const preferredKeys = [
+                    "name",
+                    "title",
+                    "position",
+                    "role",
+                    "description",
+                    "image",
+                    "logo",
+                    "website",
+                    "linkedin",
+                    "instagram",
+                    "telegram",
+                    "twitter",
+                    "facebook",
+                    "github",
+                ];
+                for (const key of preferredKeys) {
+                    const value = asString(itemRecord[key]);
+                    if (!value)
+                        continue;
+                    normalized[key] =
+                        key === "description" ? truncateText(htmlToText(value), 400).text : value;
+                }
+                return Object.keys(normalized).length > 0 ? normalized : null;
+            })
+                .filter((item) => item !== null);
+            if (items.length === 0)
+                items = null;
+        }
+        if (!title && !body && !items)
+            continue;
+        sections.push({ type, title, text: body || null, items });
+    }
+    return { sections, truncated };
+}
+function normalizeDescription(raw, maxChars) {
+    try {
+        const { sections } = normalizeDescriptionSections(raw);
+        const fullText = sections
+            .map((section) => {
+            const parts = [];
+            if (section.title)
+                parts.push(section.title);
+            if (section.text)
+                parts.push(section.text);
+            if (section.items) {
+                for (const item of section.items) {
+                    const label = item.name ?? item.title ?? null;
+                    const position = item.position ?? item.role ?? null;
+                    if (label)
+                        parts.push(position ? `${label} — ${position}` : label);
+                }
+            }
+            return parts.join("\n");
+        })
+            .filter(Boolean)
+            .join("\n\n");
+        const budgeted = truncateText(fullText, maxChars);
+        let remaining = maxChars;
+        const trimmedSections = [];
+        for (const section of sections) {
+            if (remaining <= 0)
+                break;
+            const heading = section.title ?? "";
+            const body = section.text ?? "";
+            const combined = [heading, body].filter(Boolean).join("\n");
+            if (combined.length <= remaining) {
+                trimmedSections.push(section);
+                remaining -= combined.length;
+                continue;
+            }
+            if (remaining > 20) {
+                trimmedSections.push({
+                    ...section,
+                    title: heading.length <= remaining ? heading : null,
+                    text: truncateText(body || heading, Math.max(20, remaining - Math.min(heading.length, 100))).text,
+                    items: null,
+                });
+            }
+            remaining = 0;
+            break;
+        }
+        return {
+            text: budgeted.text,
+            sections: trimmedSections,
+            truncated: budgeted.truncated,
+            error: null,
+        };
+    }
+    catch (error) {
+        return {
+            text: "",
+            sections: [],
+            truncated: false,
+            error: error.message,
+        };
+    }
+}
+function normalizeEventDetail(event, webBase, description) {
+    if (!event || typeof event.id !== "number" || !event.slug) {
+        throw new EvandApiError("Evand returned an event without an id or slug.");
+    }
+    const organizationRaw = pickRecord(event.organization);
+    const cityRaw = pickRecord(event.city);
+    const categoryRaw = pickRecord(event.category);
+    const parentCategoryRaw = categoryRaw ? pickRecord(categoryRaw.parent) : null;
+    const typeRaw = pickRecord(event.type);
+    const pricesRaw = pickRecord(event.prices);
+    const tagsRaw = Array.isArray(event.tags?.data) ? event.tags.data : [];
+    const ticketsRaw = Array.isArray(event.tickets?.data) ? event.tickets.data : [];
+    const showtimesRaw = Array.isArray(event.showtimes?.data) ? event.showtimes.data : [];
+    const circlesRaw = Array.isArray(event.circles) ? event.circles : [];
+    const minPrice = asNumber(pricesRaw?.min) ?? asNumber(event.minimum_ticket_price);
+    const maxPrice = asNumber(pricesRaw?.max) ?? asNumber(event.maximum_ticket_price);
+    const price = normalizePrice(minPrice, maxPrice, event.is_free === true);
+    const tickets = ticketsRaw
+        .filter((ticket) => {
+        if (!ticket)
+            return false;
+        if (ticket.active === undefined || ticket.active === null)
+            return true;
+        return truthy(ticket.active);
+    })
+        .map((ticket) => ({
+        id: ticket.id,
+        title: asString(ticket.title) ?? "Ticket",
+        type: asString(ticket.type) ?? "normal",
+        price: asNumber(ticket.price) ?? 0,
+        price_display: normalizePrice(asNumber(ticket.price) ?? 0, asNumber(ticket.price) ?? 0).display,
+        available_count: asNumber(ticket.available_count),
+        capacity: asNumber(ticket.capacity),
+        min_count: asNumber(ticket.min_count),
+        max_count: asNumber(ticket.max_count),
+        active: truthy(ticket.active),
+        showtime_id: asNumber(ticket.showtime_id),
+        sale_start: normalizeIsoDate(ticket.start_date),
+        sale_end: normalizeIsoDate(ticket.end_date),
+        description: htmlToText(ticket.description),
+        login_required: truthy(ticket.login_required),
+    }));
+    const availableTickets = tickets
+        .map((ticket) => ticket.available_count)
+        .filter((value) => value !== null);
+    const ticketPrices = tickets.map((ticket) => ticket.price).filter((value) => Number.isFinite(value));
+    const showtimes = showtimesRaw.map((showtime) => ({
+        id: showtime.id,
+        label: asString(showtime.label) ?? "Showtime",
+        start_date: normalizeIsoDate(showtime.start_date),
+        end_date: normalizeIsoDate(showtime.end_date),
+        start_date_tehran: formatTehranDate(showtime.start_date),
+        end_date_tehran: formatTehranDate(showtime.end_date),
+        description: htmlToText(showtime.description),
+        has_purchasable_ticket: showtime.has_purchasable_ticket === true,
+    }));
+    const categoryTitle = categoryRaw ? asString(categoryRaw.title) : null;
+    const parentCategoryTitle = parentCategoryRaw ? asString(parentCategoryRaw.title) : null;
+    const categoryPath = [parentCategoryTitle, categoryTitle].filter((value) => Boolean(value));
+    const organization = organizationRaw
+        ? {
+            name: asString(organizationRaw.name),
+            slug: asString(organizationRaw.slug),
+            url: asString(organizationRaw.slug)
+                ? organizationUrl(webBase, asString(organizationRaw.slug))
+                : null,
+            logo: coverUrl(organizationRaw.logo),
+            description: truncateText(htmlToText(asString(organizationRaw.description)), 600).text || null,
+            followers_count: asNumber(organizationRaw.followers_count),
+            events_count: asNumber(organizationRaw.events_count),
+            socials: normalizeSocials(organizationRaw.socials),
+        }
+        : null;
+    const latitude = asNumber(event.latitude);
+    const longitude = asNumber(event.longitude);
+    const mapUrl = latitude !== null && longitude !== null && (latitude !== 0 || longitude !== 0)
+        ? `https://www.google.com/maps?q=${latitude},${longitude}`
+        : null;
+    return {
+        id: event.id,
+        name: event.name ?? "",
+        slug: event.slug,
+        url: eventUrl(webBase, event.slug),
+        start_date: normalizeIsoDate(event.start_date),
+        end_date: normalizeIsoDate(event.end_date),
+        start_date_tehran: formatTehranDate(event.start_date),
+        end_date_tehran: formatTehranDate(event.end_date),
+        online: truthy(event.online),
+        city: asString(cityRaw?.name) ?? asString(event.city_name),
+        address: asString(event.address),
+        organization,
+        price,
+        status: {
+            ended: event.ended === true,
+            sold_out: event.soldout === true,
+            cancelled: event.cancelled === true,
+            partnership: asString(event.partnership?.status),
+        },
+        cover: coverUrl(event.cover),
+        website: asString(event.website),
+        socials: normalizeSocials(event.socials),
+        category: categoryRaw && categoryTitle
+            ? {
+                id: asNumber(categoryRaw.id) ?? 0,
+                title: categoryTitle,
+                slug: asString(categoryRaw.slug) ?? "",
+                path: categoryPath,
+            }
+            : null,
+        type: typeRaw ? asString(typeRaw.title) : null,
+        tags: tagsRaw
+            .map((tag) => asString(tag?.name))
+            .filter((tag) => Boolean(tag)),
+        location: {
+            online: truthy(event.online),
+            city: asString(cityRaw?.name) ?? asString(event.city_name),
+            city_slug: asString(cityRaw?.slug),
+            address: asString(event.address),
+            latitude,
+            longitude,
+            map_url: mapUrl,
+        },
+        showtimes,
+        tickets,
+        ticket_summary: {
+            active_tickets: tickets.length,
+            available_tickets: availableTickets.length > 0
+                ? availableTickets.reduce((sum, count) => sum + count, 0)
+                : null,
+            min_price: ticketPrices.length ? Math.min(...ticketPrices) : price.min,
+            max_price: ticketPrices.length ? Math.max(...ticketPrices) : price.max,
+            sold_out: event.soldout === true || (tickets.length > 0 && tickets.every((ticket) => ticket.available_count === 0)),
+        },
+        circles: circlesRaw
+            .filter((circle) => asString(circle?.name) || asString(circle?.slug))
+            .map((circle) => ({
+            name: asString(circle.name) ?? asString(circle.slug) ?? "",
+            slug: asString(circle.slug) ?? asString(circle.name) ?? "",
+            logo: coverUrl(circle.logo),
+        })),
+        timing_status: asString(event.timing_status),
+        published: asString(event.published),
+        refund_policy: truncateText(htmlToText(event.refund_policy), 2_000).text || null,
+        description,
+        registration_url: eventUrl(webBase, event.slug),
+    };
+}
+/** Turns a slug, a relative /events/... path, or a full Evand URL into a slug. */
+export function parseEventSlug(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        throw new EvandApiError("An event slug or URL is required.");
+    if (/^https?:\/\//i.test(trimmed)) {
+        let url;
+        try {
+            url = new URL(trimmed);
+        }
+        catch {
+            throw new EvandApiError(`"${input}" is not a valid URL.`);
+        }
+        const hostname = url.hostname.toLowerCase();
+        if (hostname !== "evand.com" && !hostname.endsWith(".evand.com")) {
+            throw new EvandApiError(`Expected a URL on evand.com, got ${url.hostname}.`);
+        }
+        const match = url.pathname.match(/^\/events\/([^/]+)\/?$/);
+        if (!match?.[1]) {
+            throw new EvandApiError(`The URL does not point to an Evand event page: ${input}`);
+        }
+        return safeDecodeURIComponent(match[1]);
+    }
+    return safeDecodeURIComponent(trimmed
+        .replace(/^\/+/, "")
+        .replace(/^events\//i, "")
+        .replace(/\/+$/, ""));
+}
+function safeDecodeURIComponent(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+//# sourceMappingURL=evand.js.map