@studyportals/fawkes 7.3.2-0 → 7.3.3-1

package/dist/src/structured-data/ProgrammeStructuredDataFactory.d.ts

@@ -0,0 +1,18 @@
+import { SearchStructuredDataFactory } from "./SearchStructuredDataFactory";
+import { IProgrammeCard } from "@studyportals/domain-client";
+import { ReviewRatingDTO } from "./dto/ReviewRatingDTO";
+import { OfferDTO } from "./dto/OfferDTO";
+import { Course } from "schema-dts";
+import { EntityDTO } from "./dto/EntityDTO";
+import { StructuredDataCurrencyConversionService } from "../structured-data/interface/StructuredDataCurrencyConversionService";
+export declare class ProgrammeStructuredDataFactory extends SearchStructuredDataFactory<IProgrammeCard> {
+    private currencyConversionService;
+    constructor(currencyConversionService: StructuredDataCurrencyConversionService);
+    private regionalDataPriority;
+    protected getRating(card: IProgrammeCard): ReviewRatingDTO | undefined;
+    protected getOfferData(card: IProgrammeCard): Promise<OfferDTO | undefined>;
+    protected buildStructuredDataForCard(entity: EntityDTO<IProgrammeCard>): Course;
+    private getCourseMode;
+    private getCourseWorkload;
+    private getCourseStartDate;
+}

package/dist/src/structured-data/ProgrammeStructuredDataFactory.js

@@ -0,0 +1,86 @@
+import { SearchStructuredDataFactory } from "./SearchStructuredDataFactory";
+export class ProgrammeStructuredDataFactory extends SearchStructuredDataFactory {
+    currencyConversionService;
+    constructor(currencyConversionService) {
+        super();
+        this.currencyConversionService = currencyConversionService;
+    }
+    regionalDataPriority = ['international', 'general', 'eea', 'national'];
+    getRating(card) {
+        if (typeof card.getReviewRating === 'undefined')
+            return;
+        const rating = card.getReviewRating();
+        if (!rating)
+            return;
+        return {
+            rating: rating?.getAverageStarRating(),
+            quantity: rating?.getQuantity(),
+        };
+    }
+    async getOfferData(card) {
+        const tuitionFees = card.getTuitionFees();
+        let tuition;
+        let timing;
+        for (const target of this.regionalDataPriority) {
+            if (!tuition) {
+                tuition = tuitionFees.find(t => t.getTarget() === target);
+            }
+            if (!timing) {
+                timing = card.canShowTimings() ? card.getTimings().find(t => t.getType() === target && t.canShowStartDate()) : undefined;
+            }
+        }
+        if (!tuition) {
+            return;
+        }
+        return {
+            price: await this.currencyConversionService.convert(tuition.getAmount(), tuition.getCurrency(), 'USD'),
+            category: 'tuition',
+            validFrom: timing ? timing.getStartDate().getDate() : undefined
+        };
+    }
+    buildStructuredDataForCard(entity) {
+        const card = entity.card;
+        return {
+            "@type": "Course",
+            "name": card.getTitle(),
+            "description": card.getSummary(),
+            "url": card.getProgrammeLink().getUrl(),
+            "provider": {
+                "@type": "EducationalOrganization",
+                "name": card.getUniversityLink().getDescription(),
+                "url": `https://${window.location.host}${card.getUniversityLink().getUrl()}`
+            },
+            "offers": this.constructOffer(entity.offer),
+            "aggregateRating": this.constructAggregateRating(entity.reviewRating),
+            "hasCourseInstance": {
+                "@type": "CourseInstance",
+                "startDate": this.getCourseStartDate(card),
+                "courseWorkload": this.getCourseWorkload(card),
+                "courseMode": this.getCourseMode(card),
+            }
+        };
+    }
+    getCourseMode(card) {
+        if (card.isBlended())
+            return 'blended';
+        if (card.isOnline())
+            return 'online';
+        if (card.isOnCampus())
+            return 'onsite';
+    }
+    getCourseWorkload(card) {
+        if (card.isFullTime())
+            return 'PT40H';
+        if (card.isPartTime())
+            return 'PT20H';
+        return undefined;
+    }
+    getCourseStartDate(card) {
+        for (const target of this.regionalDataPriority) {
+            const timing = card.canShowTimings() ? card.getTimings().find(t => t.getType() === target && t.canShowStartDate()) : undefined;
+            if (timing) {
+                return timing.getStartDate().getDate().toISOString().split('T')[0];
+            }
+        }
+    }
+}

package/dist/src/structured-data/SearchStructuredDataFactory.d.ts

@@ -0,0 +1,35 @@
+import { SearchResultsPage, WithContext, Offer, AggregateRating, Thing, FAQPage } from "schema-dts";
+import { ReviewRatingDTO } from "./dto/ReviewRatingDTO";
+import { OfferDTO } from "./dto/OfferDTO";
+import { EntityDTO } from "./dto/EntityDTO";
+import { FAQItemDto } from "./dto/FAQItemDto";
+import { BreadcrumbDTO } from "./dto/BreadcrumbDTO";
+export declare abstract class SearchStructuredDataFactory<TCard> {
+    buildStructuredData(title: string, description: string, cards: TCard[], faqItems?: FAQItemDto[], breadcrumbs?: BreadcrumbDTO[]): Promise<WithContext<SearchResultsPage>>;
+    protected abstract buildStructuredDataForCard(entity: EntityDTO<TCard>): Thing;
+    /**
+     * Get the rating for a card.
+     * This method should be overridden by subclasses to provide the specific rating logic.
+     * If no rating is available, return undefined and no aggregate rating will be constructed for the card & page.
+     *
+     * @param card
+     * @protected
+     */
+    protected getRating(card: TCard): ReviewRatingDTO | undefined;
+    /**
+     * Get the offer data for a card.
+     * This method should be overridden by subclasses to provide the specific offer logic.
+     * If no offer is available, return undefined and no aggregate offer will be constructed for the card & page.
+     *
+     * @param card
+     * @protected
+     */
+    protected getOfferData(card: TCard): Promise<OfferDTO | undefined>;
+    private constructOptionalPageAggregateRating;
+    private constructOptionalPageOffers;
+    protected constructOptionalFaqPage(faqItems: FAQItemDto[]): FAQPage | undefined;
+    private constructOptionalBreadcrumbs;
+    protected constructAggregateRating(reviewRating?: ReviewRatingDTO): AggregateRating | undefined;
+    protected constructOffer(offerData?: OfferDTO): Offer | undefined;
+    private stripHtmlWithListRetain;
+}

package/dist/src/structured-data/SearchStructuredDataFactory.js

@@ -0,0 +1,154 @@
+export class SearchStructuredDataFactory {
+    async buildStructuredData(title, description, cards, faqItems = [], breadcrumbs = []) {
+        const entities = [];
+        const ratings = [];
+        const offersData = [];
+        for (const card of cards) {
+            const reviewRating = this.getRating(card);
+            const offer = await this.getOfferData(card);
+            if (reviewRating)
+                ratings.push(reviewRating);
+            if (offer)
+                offersData.push(offer);
+            entities.push({ card, offer, reviewRating });
+        }
+        const data = {
+            "@context": "https://schema.org",
+            "@type": "SearchResultsPage",
+            "name": title,
+            description,
+            "mainEntity": entities.map(entity => this.buildStructuredDataForCard(entity))
+        };
+        data.aggregateRating = this.constructOptionalPageAggregateRating(ratings);
+        data.offers = this.constructOptionalPageOffers(offersData);
+        data.hasPart = this.constructOptionalFaqPage(faqItems);
+        data.breadcrumb = this.constructOptionalBreadcrumbs(breadcrumbs);
+        return data;
+    }
+    /**
+     * Get the rating for a card.
+     * This method should be overridden by subclasses to provide the specific rating logic.
+     * If no rating is available, return undefined and no aggregate rating will be constructed for the card & page.
+     *
+     * @param card
+     * @protected
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    getRating(card) {
+        return undefined;
+    }
+    /**
+     * Get the offer data for a card.
+     * This method should be overridden by subclasses to provide the specific offer logic.
+     * If no offer is available, return undefined and no aggregate offer will be constructed for the card & page.
+     *
+     * @param card
+     * @protected
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    async getOfferData(card) {
+        return undefined;
+    }
+    constructOptionalPageAggregateRating(ratings) {
+        if (ratings.length <= 0)
+            return;
+        let totalQuantity = 0;
+        let totalRatingValue = 0;
+        for (const rating of ratings) {
+            totalQuantity += rating.quantity;
+            totalRatingValue += rating.rating;
+        }
+        const totalAverageRating = Math.round((totalRatingValue / ratings.length) * 10) / 10;
+        return this.constructAggregateRating({ rating: totalAverageRating, quantity: totalQuantity });
+    }
+    constructOptionalPageOffers(offersData) {
+        if (offersData.length <= 0)
+            return;
+        let minPrice = 0;
+        let maxPrice = 0;
+        let totalPrice = 0;
+        for (const offer of offersData) {
+            if (offer.price < minPrice || minPrice === 0) {
+                minPrice = offer.price;
+            }
+            if (offer.price > maxPrice) {
+                maxPrice = offer.price;
+            }
+            totalPrice += offer.price;
+        }
+        return {
+            "@type": "AggregateOffer",
+            "lowPrice": minPrice,
+            "highPrice": maxPrice,
+            "priceCurrency": "USD",
+            "offerCount": offersData.length,
+            "priceSpecification": {
+                "@type": "PriceSpecification",
+                "price": Math.round(totalPrice / offersData.length),
+                "priceCurrency": "USD"
+            }
+        };
+    }
+    constructOptionalFaqPage(faqItems) {
+        if (faqItems.length <= 0)
+            return;
+        return {
+            "@type": "FAQPage",
+            "mainEntity": faqItems.map(item => ({
+                "@type": "Question",
+                "name": item.question,
+                "acceptedAnswer": {
+                    "@type": "Answer",
+                    "text": this.stripHtmlWithListRetain(item.answer)
+                }
+            }))
+        };
+    }
+    constructOptionalBreadcrumbs(breadcrumbs) {
+        if (breadcrumbs.length <= 0)
+            return;
+        return {
+            "@type": "BreadcrumbList",
+            "itemListElement": breadcrumbs.map((breadcrumb) => ({
+                "@type": "ListItem",
+                "@id": `${breadcrumb.url}#listitem#thing`,
+                "name": breadcrumb.name,
+                "position": breadcrumb.position,
+                "item": breadcrumb.url
+            }))
+        };
+    }
+    constructAggregateRating(reviewRating) {
+        if (!reviewRating)
+            return;
+        return {
+            "@type": "AggregateRating",
+            "ratingValue": reviewRating.rating,
+            "reviewCount": reviewRating.quantity,
+            "bestRating": 5,
+            "worstRating": 1
+        };
+    }
+    constructOffer(offerData) {
+        if (!offerData)
+            return;
+        return {
+            "@type": "Offer",
+            "price": offerData.price,
+            "priceCurrency": "USD",
+            "availability": "https://schema.org/InStock",
+            "validFrom": offerData.validFrom ? offerData.validFrom.toISOString().split('T')[0] : undefined,
+            "category": "tuition"
+        };
+    }
+    stripHtmlWithListRetain(html) {
+        const tempDiv = document.createElement('div');
+        tempDiv.innerHTML = html;
+        // Replace all <li> elements with bullet points manually
+        tempDiv.querySelectorAll('li').forEach(li => {
+            li.textContent = '• ' + li.textContent;
+        });
+        // Get the text content, which includes newlines for block elements
+        return tempDiv.textContent?.trim() ?? '';
+    }
+}

package/dist/src/structured-data/dto/BreadcrumbDTO.d.ts

@@ -0,0 +1,5 @@
+export interface BreadcrumbDTO {
+    name: string;
+    position: number;
+    url: string;
+}

package/dist/src/structured-data/dto/BreadcrumbDTO.js

@@ -0,0 +1 @@
+export {};

package/dist/src/structured-data/dto/EntityDTO.d.ts

@@ -0,0 +1,7 @@
+import { OfferDTO } from "./OfferDTO";
+import { ReviewRatingDTO } from "./ReviewRatingDTO";
+export interface EntityDTO<TCard> {
+    card: TCard;
+    offer?: OfferDTO;
+    reviewRating?: ReviewRatingDTO;
+}

package/dist/src/structured-data/dto/EntityDTO.js

@@ -0,0 +1 @@
+export {};

package/dist/src/structured-data/dto/FAQItemDto.d.ts

@@ -0,0 +1,4 @@
+export interface FAQItemDto {
+    question: string;
+    answer: string;
+}

package/dist/src/structured-data/dto/FAQItemDto.js

@@ -0,0 +1 @@
+export {};

package/dist/src/structured-data/dto/OfferDTO.d.ts

@@ -0,0 +1,5 @@
+export interface OfferDTO {
+    price: number;
+    validFrom: Date | undefined;
+    category: 'tuition';
+}

package/dist/src/structured-data/dto/OfferDTO.js

@@ -0,0 +1 @@
+export {};

package/dist/src/structured-data/dto/ReviewRatingDTO.d.ts

@@ -0,0 +1,4 @@
+export interface ReviewRatingDTO {
+    rating: number;
+    quantity: number;
+}

package/dist/src/structured-data/dto/ReviewRatingDTO.js

@@ -0,0 +1 @@
+export {};

package/dist/src/structured-data/index.d.ts

@@ -0,0 +1 @@
+export * from './ProgrammeStructuredDataFactory';

package/dist/src/structured-data/index.js

@@ -0,0 +1 @@
+export * from './ProgrammeStructuredDataFactory';

package/dist/src/structured-data/interface/StructuredDataCurrencyConversionService.d.ts

@@ -0,0 +1,3 @@
+export interface StructuredDataCurrencyConversionService {
+    convert(originalAmount: number, originalCurrency: string, targetCurrency?: string): Promise<number>;
+}

package/dist/src/structured-data/interface/StructuredDataCurrencyConversionService.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@studyportals/fawkes",
-	"version": "7.3.2-0",
+	"version": "7.3.3-1",
 	"description": "A package to centralize SEO related logic for SBLP and Sitemap Generator.",
 	"files": [
 		"./dist"
@@ -67,6 +67,7 @@
 	"author": "The Jedi Council",
 	"license": "ISC",
 	"devDependencies": {
+		"@adobe/structured-data-validator": "^1.4.1",
 		"@studyportals/code-style": "^2.2.1",
 		"@studyportals/webpack-helper": "^6.0.6",
 		"@vitest/coverage-istanbul": "^2.1.8",
@@ -79,10 +80,11 @@
 		"vitest": "^2.1.8"
 	},
 	"dependencies": {
-		"@studyportals/domain-client": "^6.0.0",
+		"@studyportals/domain-client": "^6.2.0",
 		"@studyportals/ranking-api-interface": "^1.3.12",
 		"@studyportals/search-filters": "^4.9.1",
 		"@studyportals/static-domain-data": "^6.1.0",
+		"schema-dts": "^1.1.5",
 		"ts-loader": "^9.5.2"
 	},
 	"optionalDependencies": {