@studyportals/domain-client 6.0.0 → 6.1.0-beta.0

package/src/clients/protobuf-client.ts

@@ -0,0 +1,57 @@
+import { DomainClient } from "../domain-client";
+import { PortalMap } from "../types/portal-map";
+import { PortalType } from "../types/portal-type";
+
+
+export abstract class ProtobufClient<T> {
+	public static portalMap: PortalMap = new Map<PortalType, string>();
+	private readonly domainClient: DomainClient<Record<string, unknown>>;
+
+	constructor(
+		baseUrl: string,
+		seed: number,
+		apiKey?: string,
+		portalMap?: PortalMap
+	) {
+		if(portalMap) {
+			ProtobufClient.portalMap = portalMap;
+		}
+
+		this.domainClient = new DomainClient(
+			baseUrl,
+			apiKey,
+			this.getModelName(),
+			this.getVersion(),
+			this.isPublic(),
+			seed
+		);
+	}
+
+
+	public async fetch(id: number): Promise<T> {
+		const results = await this.domainClient.doRequest([id])
+		return this.constructModel(results[0]);
+	}
+
+	public async fetchMultiple(ids: number[]): Promise<T[]> {
+		const results = await this.domainClient.doRequest(ids);
+		return results.map((data) => this.constructModel(data));
+	}
+
+	protected abstract constructModel(data: Record<string, any>): T;
+	protected abstract getModelName(): string;
+
+	protected abstract getVersion(): string;
+
+	public abstract isPublic(): boolean;
+
+
+	public static transformUrlUsingPortalMap(path: string, portalType: PortalType): string {
+		const baseUrl = ProtobufClient.portalMap.get(portalType)
+		if(baseUrl && !path.includes('https')) {
+			return baseUrl + path;
+		}
+
+		return path;
+	}
+}

package/src/clients/public-mini-programme-card-client.ts

@@ -0,0 +1,20 @@
+import { MiniProgrammeCard } from "../../protobuf";
+import { ProtobufClient } from "./protobuf-client";
+
+export class PublicMiniProgrammeCardClient extends ProtobufClient<MiniProgrammeCard> {
+	protected constructModel(data: Record<string, any>): MiniProgrammeCard {
+		return MiniProgrammeCard.fromJSON(data);
+	}
+
+	protected getModelName(): string {
+		return 'mini-programme-card';
+	}
+
+	protected getVersion(): string {
+		return 'v1';
+	}
+
+	public isPublic(): boolean {
+		return true;
+	}
+}

package/src/domain-client.ts

@@ -0,0 +1,110 @@
+import { BadRequestException } from "./exceptions/bad-request-exception";
+import { InternalServerException } from "./exceptions/internal-server-exception";
+import { NotFoundException } from "./exceptions/not-found-exception";
+import { IApiResponse } from "./i-api-response";
+
+const decoder = new TextDecoder();
+
+export class DomainClient<T> {
+
+	constructor(
+		public readonly baseUrl: string,
+		public readonly apiKey: string | undefined,
+		public readonly model: string,
+		public readonly version: string,
+		public readonly isPublic: boolean,
+		public readonly seed: number
+	) {
+	}
+
+	public async doRequest(ids: number[]): Promise<T[]> {
+		const url = `${this.baseUrl}/${this.buildUrl(ids)}`;
+		const headers: Record<string, string> = {};
+
+		if (this.apiKey !== undefined) {
+			headers["x-api-key"] = this.apiKey
+		}
+
+		try {
+
+			const response = await fetch(url, {headers});
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+			const data: IApiResponse = await response.json();
+
+			if (!response.ok || data.status !== 200) {
+				this.handleErrors(data);
+			}
+
+			const models: T[] = [];
+
+			for (const id of ids) {
+				const modelData = data.data[id];
+				if (!modelData) {
+					continue;
+				}
+
+				if(typeof modelData === 'string') {
+					try {
+						models.push(await this.decompressModelData(modelData));
+						continue;
+					} catch (error) {
+						console.error(error);
+						continue;
+					}
+				}
+
+
+
+				models.push(modelData as T);
+			}
+
+			return models;
+
+		} catch (error) {
+			console.error('Error fetching data from API:', error);
+			if(error instanceof InternalServerException || error instanceof BadRequestException || error instanceof NotFoundException) {
+				throw error;
+			}
+
+			throw new InternalServerException('Unable to fetch data from the API', error);
+		}
+	}
+
+	private async decompressModelData(compressedData: string): Promise<T> {
+		const bytes = Uint8Array.from(atob(compressedData), c => c.charCodeAt(0));
+
+		const stream = new DecompressionStream('deflate');
+		const response = new Response(bytes as any);
+		const decompressedStream = response.body?.pipeThrough(stream);
+		const decompressedBytes =  new Uint8Array(await new Response(decompressedStream).arrayBuffer());
+
+		return JSON.parse(decoder.decode(decompressedBytes)) as T;
+	}
+
+	private handleErrors(response: IApiResponse): void {
+		if (!response.status) {
+			throw new InternalServerException(response.message);
+		}
+
+		if (response.status === 400) {
+			throw new BadRequestException(response.message);
+		}
+
+		if (response.status === 404) {
+			throw new NotFoundException(response.message);
+		}
+	}
+
+	private buildUrl(ids: number[]): string {
+		const publicPrefix = this.shouldAddPublicPrefix() ? 'public/' : '';
+		let query = `${publicPrefix}${this.model}/${this.version}/?seed=${this.seed}`;
+		for (const id of ids) {
+			query += `&id=${id}`;
+		}
+		return query;
+	}
+
+	private shouldAddPublicPrefix(): boolean {
+		return this.isPublic && this.apiKey === undefined;
+	}
+}

package/src/factories/DateFactory.ts

@@ -0,0 +1,8 @@
+import { IClassFactory } from "../i-class-factory";
+import { CallableReturnType, Model } from "../types";
+
+export class DateFactory implements IClassFactory {
+	public create(data: Model, parameters: string[]): CallableReturnType {
+		return new Date(parameters[0]);
+	}
+}

package/src/factories/InternalLinkFactory.ts

@@ -0,0 +1,32 @@
+import { IClassFactory } from "../i-class-factory";
+import { PortalType } from "../types/portal-type";
+import { CallableReturnType, Model } from "../types";
+import { PortalMap } from "../types/portal-map";
+
+export class InternalLinkFactory implements IClassFactory {
+	private portalMap: PortalMap;
+
+	constructor(portalMap: PortalMap) {
+		this.portalMap = portalMap;
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	public create(link: Model, parameters?: unknown): CallableReturnType {
+		const getPortalType = link['getPortalType'];
+		const portalType = getPortalType ? getPortalType() as PortalType : null;
+		const portalBaseUrl = portalType ? this.getPortalBaseUrl(portalType) : '';
+
+		const getUrl = link['getUrl'];
+		if (getUrl) {
+			const path = getUrl() as string;
+			link['getUrl'] = (): string => portalBaseUrl + path;
+		}
+
+		return link;
+	}
+
+	private getPortalBaseUrl(portalType: PortalType): string {
+		const url = this.portalMap.get(portalType);
+		return url || '';
+	}
+}

package/src/i-api-response.ts

@@ -0,0 +1,7 @@
+import { IModelDescription } from "./i-model-description";
+
+export interface IApiResponse {
+	status: number;
+	data: Record<number, IModelDescription|string>;
+	message: string
+}

package/src/i-class-factory.ts

@@ -0,0 +1,5 @@
+import { CallableReturnType, Model } from "./types";
+
+export interface IClassFactory {
+	create(data: Model, parameters?: any[]): CallableReturnType
+}

package/src/i-model-description.ts

@@ -0,0 +1,13 @@
+import { AcceptedType } from "./types";
+
+export interface IModelDescription {
+	class: string;
+	func: Record<string, AcceptedType | IModelDescription>;
+	parameters?: any[];
+}
+
+// eslint-disable-next-line
+export function isModelDescription(arg: any): arg is IModelDescription {
+	// eslint-disable-next-line
+	return arg && arg.class && (arg.func || arg.parameters);
+}

package/src/model-client.ts

@@ -0,0 +1,77 @@
+import { DomainClient } from "./domain-client";
+import { ClientException } from "./exceptions/client-exception";
+import { IModelDescription } from "./i-model-description";
+import { ModelFactory } from "./model-factory";
+import { PortalMap } from "./types/portal-map";
+
+
+export abstract class ModelClient<T> {
+	private readonly domainClient: DomainClient<IModelDescription> | null;
+	private readonly modelFactory: ModelFactory<T>;
+
+	constructor(
+		baseUrl?: string,
+		apiKey?: string,
+		seed?: number,
+		portalMap?: PortalMap
+	) {
+		if (!baseUrl || !seed) {
+			return;
+		}
+
+		this.modelFactory = new ModelFactory<T>(portalMap);
+		this.domainClient = new DomainClient(
+			baseUrl,
+			apiKey,
+			this.getModelName(),
+			this.getVersion(),
+			this.isPublic(),
+			seed
+		);
+	}
+
+	public async fetch(id: number): Promise<T> {
+		const modelDescriptions = await this.fetchDescription(id);
+		return this.modelFactory.fromDescription(modelDescriptions);
+	}
+
+	public async fetchDescription(id: number): Promise<IModelDescription> {
+		if (!this.domainClient) {
+			throw new ClientException(
+				"Offline mode active: did you provide all parameters " +
+				"in the constructor?"
+			);
+		}
+		const result = await this.domainClient.doRequest([id]);
+		return result[0];
+	}
+
+	public async fetchMultiple(ids: number[]): Promise<T[]> {
+		const descriptions = await this.fetchMultipleDescriptions(ids);
+		return this.modelFactory.fromDescriptions(descriptions);
+	}
+
+	public async fetchMultipleDescriptions(ids: number[]): Promise<IModelDescription[]> {
+		if (!this.domainClient) {
+			throw new ClientException(
+				'Offline mode active: did you provide all parameters ' +
+				'in the constructor?'
+			);
+		}
+		return await this.domainClient.doRequest(ids);
+	}
+
+	public fromDescription(description: IModelDescription): T {
+		return this.modelFactory.fromDescription(description);
+	}
+
+	public fromDescriptions(descriptions: IModelDescription[]): T[] {
+		return this.modelFactory.fromDescriptions(descriptions);
+	}
+
+	protected abstract getModelName(): string;
+
+	protected abstract getVersion(): string;
+
+	public abstract isPublic(): boolean;
+}

package/src/model-factory.ts

@@ -0,0 +1,94 @@
+import { InternalLinkFactory } from "./factories/InternalLinkFactory";
+import { DateFactory } from "./factories/DateFactory";
+import { IClassFactory } from "./i-class-factory";
+import { IModelDescription, isModelDescription } from "./i-model-description";
+import { PropertyNotAvailableException } from "./exceptions/property-not-available-exception";
+import { Callable, CallableReturnType, Model } from "./types";
+import { PortalMap } from "./types/portal-map";
+import { PortalType } from "./types/portal-type";
+
+export class ModelFactory<T> {
+
+	private customClassFactories: Map<string, IClassFactory>;
+
+	constructor(portalMap: PortalMap = new Map<PortalType, string>()) {
+		const factories = new Map<string, IClassFactory>();
+		factories.set('IInternalLink', new InternalLinkFactory(portalMap));
+		factories.set('SerializableDateTime', new DateFactory());
+
+		this.customClassFactories = factories;
+	}
+
+	public fromDescription(data: IModelDescription): T {
+		return this.unpackClass(data) as unknown as T;
+	}
+
+	public fromDescriptions(data: IModelDescription[]): T[] {
+		const models: T[] = [];
+		for (const modelDescription of data) {
+			models.push(this.unpackClass(modelDescription) as unknown as T);
+		}
+		return models;
+	}
+
+	private unpackClass(data: IModelDescription): CallableReturnType {
+
+
+		const unpacked: Model = {};
+		for (const functionName in data.func) {
+			unpacked[functionName] = this.getCallable(functionName, data);
+		}
+
+		const factory = this.customClassFactories.get(data.class);
+		if (factory !== undefined) {
+			return factory.create(unpacked, data.parameters);
+		}
+
+		return unpacked;
+	}
+
+	private getCallable(
+		functionName: string,
+		data: IModelDescription
+	): Callable {
+		const propertyName = functionName.substr(3);
+		const canShowFunction = 'canShow' + propertyName;
+
+		const value: unknown = data.func[functionName];
+		let returnValue: CallableReturnType|CallableReturnType[];
+
+		if (isModelDescription(value)) {
+			returnValue = this.unpackClass(value);
+		} else if (Array.isArray(value)) {
+			returnValue = this.unpackArray(value);
+		} else {
+			returnValue = value as CallableReturnType;
+		}
+
+		if (canShowFunction in data.func) {
+			return (): any => {
+				if (data.func[canShowFunction] === false) {
+					throw new PropertyNotAvailableException(
+						`Property '${propertyName}' not available`
+					);
+				}
+				return returnValue;
+			};
+		}
+		return (): any => {
+			return returnValue;
+		};
+	}
+
+	private unpackArray(list: any[]): CallableReturnType[] {
+		return list.map(
+			item => {
+				if (isModelDescription(item)) {
+					return this.unpackClass(item)
+				}
+
+				return item as CallableReturnType;
+			}
+		);
+	}
+}

package/src/models/bestfit-programme/bestfit-programme-client.ts

@@ -0,0 +1,16 @@
+import { IBestFitProgramme } from "../../..";
+import { ModelClient } from "../../model-client";
+
+export class BestfitProgrammeClient extends ModelClient<IBestFitProgramme> {
+	protected getModelName(): string {
+		return 'bestfit-programme';
+	}
+
+	protected getVersion(): string {
+		return 'v1';
+	}
+
+	public isPublic(): boolean {
+		return false;
+	}
+}

package/src/models/bestfit-programme/i-best-fit-programme.ts

@@ -0,0 +1,102 @@
+import { ICity, IEnglishRequirements, IGPARequirement, ILivingCost, ITuitionFee } from "../../..";
+
+export interface IBestFitProgramme {
+
+	/**
+	 * Average university ranking across multiple ranking institutes.
+	 *
+	 * @return number
+	 */
+	getAverageRankingPosition(): number;
+
+	canShowAverageRankingPosition(): boolean;
+
+	/**
+	 * City which programme is given in
+	 *
+	 * @return ICity
+	 */
+	getCity(): ICity;
+
+	/**
+	 * Get country id the programme is teached in
+	 *
+	 * @return number
+	 */
+	getCountryId(): number;
+
+	/**
+	 * Discipline ids which the program is linked to.
+	 *
+	 * @return number[]
+	 */
+	getDisciplineIds(): number[];
+
+	canShowDisciplineIds(): boolean;
+
+	/**
+	 * English level requirements.
+	 *
+	 * @return IEnglishRequirements
+	 */
+	getEnglishRequirements(): IEnglishRequirements;
+
+	/**
+	 * GPA requirements
+	 *
+	 * @return IGPARequirement
+	 */
+	getGPA(): IGPARequirement;
+
+	canShowGPA(): boolean;
+
+	/**
+	 * Id of the programme.
+	 *
+	 * @return number
+	 */
+	getId(): number;
+
+	/**
+	 * Estimated living cost based on universities location.
+	 *
+	 * @return ILivingCost
+	 */
+	getLivingCost(): ILivingCost;
+
+	canShowLivingCost(): boolean;
+
+	/**
+	 * Minimum required education level
+	 *
+	 * @return string | null
+	 */
+	getRequiredEducationalLevel(): string | null;
+
+	canShowRequiredEducationalLevel(): boolean;
+
+	/**
+	 * The programmes tuition fees
+	 *
+	 * @return ITuitionFee[]
+	 */
+	getTuitionFees(): ITuitionFee[];
+
+	canShowTuitionFees(): boolean;
+
+	/**
+	 * Amount of years required as work experience
+	 *
+	 * @return number
+	 */
+	getWorkExperienceYears(): number;
+
+	canShowWorkExperienceYears(): boolean;
+
+	/**
+	 * Indicates whenever a programme is fully online or not
+	 *
+	 * @return boolean
+	 */
+	isFullyOnline(): boolean;
+}

package/src/models/bestfit-programme/i-city.ts

@@ -0,0 +1,16 @@
+export interface ICity {
+
+	/**
+	 * Get city id
+	 *
+	 * @return number
+	 */
+	getId(): number;
+
+	/**
+	 * Get city name
+	 *
+	 * @return string
+	 */
+	getName(): string;
+}

package/src/models/bestfit-programme/i-living-cost.ts

@@ -0,0 +1,23 @@
+export interface ILivingCost {
+
+	/**
+	 * Get the applicable currency.
+	 *
+	 * @return string
+	 */
+	getCurrency(): string;
+
+	/**
+	 * Get the maximum living cost in the provided currency.
+	 *
+	 * @return number
+	 */
+	getMax(): number;
+
+	/**
+	 * Get the minimum living cost in the provided currency.
+	 *
+	 * @return number
+	 */
+	getMin(): number;
+}

package/src/models/common/i-city.ts

@@ -0,0 +1,16 @@
+export interface ICity {
+
+	/**
+	 * Get city id
+	 *
+	 * @return number
+	 */
+	getId(): number;
+
+	/**
+	 * Get city name
+	 *
+	 * @return string
+	 */
+	getName(): string;
+}

package/src/models/common/i-country.ts

@@ -0,0 +1,23 @@
+export interface ICountry {
+
+	/**
+	 * Get country iso code
+	 *
+	 * @return string
+	 */
+	getISOCode(): string;
+
+	/**
+	 * Get country id
+	 *
+	 * @return number
+	 */
+	getId(): number;
+
+	/**
+	 * Get country name
+	 *
+	 * @return string
+	 */
+	getName(): string;
+}

package/src/models/common/i-english-requirements.ts

@@ -0,0 +1,66 @@
+export interface IEnglishRequirements {
+
+	/**
+	 * Required score for Cambridge english
+	 *
+	 * @return number
+	 */
+	getCambridgeEnglish(): number;
+
+	canShowCambridgeEnglish(): boolean;
+
+	/**
+	 * Required score for Duolingo
+	 *
+	 * @return number
+	 */
+	getDuolingo(): number;
+
+	canShowDuolingo(): boolean;
+
+	/**
+	 * Required score for IELTS tests
+	 *
+	 * @return number
+	 */
+	getIELTS(): number;
+
+	canShowIELTS(): boolean;
+
+	/**
+	 * Required score for PTE
+	 *
+	 * @return number
+	 */
+	getPTE(): number;
+
+	canShowPTE(): boolean;
+
+	/**
+	 * Required score for TOEFL internet
+	 *
+	 * @return number
+	 */
+	getTOEFLInternet(): number;
+
+	canShowTOEFLInternet(): boolean;
+
+	/**
+	 * Required score for TOEFL paper
+	 *
+	 * @return number
+	 */
+	getTOEFLPaper(): number;
+
+	canShowTOEFLPaper(): boolean;
+
+	/**
+	 * Required score for OTE
+	 *
+	 * @return number
+	 */
+	getOte(): number;
+	
+	canShowOte(): boolean;
+
+}