@edifice.io/client 1.7.4-develop-pedago.20241211160712

package/README.md

@@ -0,0 +1,90 @@
+# Edifice TS Client
+
+Edifice TS Client exposes frameworks for interacting with [entcore-based servers APIs](https://github.com/opendigitaleducation/entcore).
+It is written in typescript, with minimal dependencies (rxjs and axios at the moment).
+
+## Prerequisites
+
+- `pnpm: >= 7 | 8`
+- `node: >= 16 | 18`
+
+## Getting Started
+
+```bash
+pnpm install
+```
+
+### Build
+
+```bash
+pnpm run build
+```
+
+## Documentation
+
+As rule of thumb, **@edifice.io/client never uses any browser-related technology** (no HTMLElement, Document, navigator...).
+It focus exclusively on data exchange with the servers.
+
+- [IConfigurationFramework](docs/interfaces/iconfigurationframework.md) is composed of 3 layers
+
+  - Platform (apps, theme, analytics, i18n...)
+  - School
+  - User (preferences)
+
+- [ISession](docs/interfaces/isession.md) of the connected user
+
+  - user
+  - description
+  - currentLanguage
+  - notLoggedIn
+  - avatarUrl
+  - currentApp (the one which initialized the framework)
+  - hasWorkflow
+  - hasRight
+
+- [INotifyFramework](docs/interfaces/inotifyframework.md) for async messages
+
+  - onLangReady
+  - onSessionReady
+  - onSkinReady
+  - onOverridesReady
+  - promisify (generic for creating/resolving/rejecting a Promise)
+  - events (a publish/subscribe event broker)
+
+- [ITransportFramework](docs/interfaces/itransportframework.md) wraps the HTTP protocol
+
+- [IExplorerFramework](docs/interfaces/iexplorerframework.md) to look for resources
+
+- [IWidgetFramework](docs/interfaces/iwidgetframework.md) dedicated to widgets conf/prefs
+
+- and specific app frameworks for modeling their data
+  - [ITimelineApp](docs/interfaces/itimelineapp.md)
+  - ...
+
+[Browse the full API documentation here](docs/modules.md)
+
+## Additional developers notes
+
+4 additional libs are installed by the `pnpm install` command.
+
+- [ViteJS](https://vitejs.dev/) as a Bundler
+- [Typedoc](https://typedoc.org/guides/doccomments/) to generate the markdown documentation, in **/docs**, from the Typescript comments in source code.
+- [husky](https://github.com/typicode/husky) to install a local [git pre-commit hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#_client_side_hooks), in order to run the unit-tests and update /docs before every commit.
+  => **/docs will always be up-to-date on the git server**.
+
+The `pnpm run build` command will populate the **/dist** directory
+
+- **/dist/ts** contains the JS code and associated _.d.ts_ and _.js.map_ files, later packaged in NPM (done by our CI).
+- **/dist/bundle** contains the production-ready code/map.
+
+So, **you'll just have to write nice documented code, and unit tests** where needed !
+
+## Push Force
+
+`git push --force` is not recommended!
+
+```
+After a git history rewrite due to a git push --force, the git tags and notes referencing the commits that were rewritten are lost.
+```
+
+If it happens, read this troubleshooting section: [Troubleshooting](https://semantic-release.gitbook.io/semantic-release/support/troubleshooting#release-not-found-release-branch-after-git-push-force)

package/dist/analytics/Service.d.ts

@@ -0,0 +1,17 @@
+import { IOdeServices } from '../services/OdeServices';
+import { IWebApp } from '../session/interfaces';
+export declare class AnalyticsService {
+    private context;
+    constructor(context: IOdeServices);
+    private get http();
+    private get session();
+    /**
+     * Xiti tracker for page loading.
+     * @param locationPath
+     * @param app
+     */
+    trackPageLoad(locationPath: string, app: IWebApp): Promise<void>;
+    private getXitiConfig;
+    private loadXitiScript;
+    private getXitiTrackingParams;
+}

package/dist/apps/timeline/Framework.d.ts

@@ -0,0 +1,25 @@
+import { IFlashMessageModel, ITimelineApp } from './interfaces';
+import { Notification } from './Notification.model';
+export declare class TimelineApp implements ITimelineApp {
+    private _notifications;
+    private _notificationTypes;
+    private _flashMessages;
+    private _pageNumber;
+    private _lastPage;
+    private _loading;
+    showMine: boolean;
+    get notifications(): Array<Notification>;
+    get isLoading(): boolean;
+    get page(): number;
+    get hasMorePage(): boolean;
+    get notificationTypes(): Array<string>;
+    get selectedNotificationTypes(): Array<string>;
+    get preferences(): any;
+    get flashMessages(): IFlashMessageModel[];
+    savePreferences(): Promise<void>;
+    resetPagination(): void;
+    initialize(): Promise<void>;
+    loadNotifications(force?: boolean): Promise<void>;
+    loadFlashMessages(): Promise<void>;
+    markAsRead(msg: IFlashMessageModel): Promise<void>;
+}

package/dist/apps/timeline/Notification.model.d.ts

@@ -0,0 +1,10 @@
+import { ITimelineNotification, NotificationModel } from './interfaces';
+export declare class Notification implements ITimelineNotification {
+    constructor(model: NotificationModel);
+    _id: string;
+    model: NotificationModel;
+    isUnread(): boolean;
+    delete(): Promise<any>;
+    discard(): Promise<any>;
+    report(): Promise<any>;
+}

package/dist/apps/timeline/interfaces.d.ts

@@ -0,0 +1,69 @@
+export declare abstract class ITimelineFactory {
+    static createInstance(): ITimelineApp;
+}
+export interface ITimelineApp {
+    initialize(): Promise<void>;
+    readonly notificationTypes: Array<string>;
+    readonly selectedNotificationTypes: Array<string>;
+    showMine: boolean;
+    /** Load more notifications, or force loading more by virtually incrementing the page. */
+    loadNotifications(force?: boolean): Promise<void>;
+    readonly notifications: Array<ITimelineNotification>;
+    resetPagination(): void;
+    readonly isLoading: boolean;
+    readonly page: number;
+    readonly hasMorePage: boolean;
+    savePreferences(): Promise<void>;
+    readonly preferences: any;
+    loadFlashMessages(): Promise<void>;
+    readonly flashMessages: Array<IFlashMessageModel>;
+    markAsRead(msg: IFlashMessageModel): Promise<void>;
+}
+export interface ITimelineNotification {
+    readonly _id: string;
+    readonly model: NotificationModel;
+    isUnread(): boolean;
+    delete(): Promise<void>;
+    discard(): Promise<void>;
+    report(): Promise<void>;
+}
+export type NotificationModel = {
+    _id: string;
+    type: string;
+    eventType: string;
+    resource: string;
+    sender: string;
+    params: {
+        uri: string;
+        username: string;
+        blogTitle: string;
+        resourceUri: string;
+    };
+    date: {
+        $date: number;
+    };
+    message: string;
+    recipients?: Array<Recipient>;
+    reported?: boolean;
+    reporters?: any;
+};
+export interface Recipient {
+    userId: string;
+}
+export interface IFlashMessageModel {
+    readonly id: string;
+    readonly title?: string;
+    readonly contents?: Object;
+    readonly startDate?: string;
+    readonly endDate?: string;
+    readonly readCount?: number;
+    readonly author?: string;
+    readonly profiles?: string[];
+    readonly color?: string;
+    readonly customColor?: string | null;
+    readonly lastModifier?: string;
+    readonly structureId?: string;
+    readonly subStructures?: string[];
+    readonly signature?: string;
+    readonly signatureColor?: string;
+}

package/dist/audience/ReactionsService.d.ts

@@ -0,0 +1,22 @@
+import { IOdeServices } from '../services/OdeServices';
+import { IReactionsService, ReactionDetailsData, ReactionSummaryData, ReactionType } from './interface';
+export type ReactionSummariesData = {
+    reactionsByResource: {
+        [resourceId: string]: ReactionSummaryData | undefined;
+    };
+};
+export declare class ReactionsService implements IReactionsService {
+    private context;
+    private module;
+    private resourceType;
+    constructor(context: IOdeServices, module: string, resourceType: string);
+    private get http();
+    loadAvailableReactions(): Promise<("REACTION_1" | "REACTION_2" | "REACTION_3" | "REACTION_4")[] | undefined>;
+    loadReactionSummaries(resourceIds: string[]): Promise<{
+        [resourceId: string]: ReactionSummaryData | undefined;
+    }>;
+    loadReactionDetails(resourceId: string, page: number, size: number): Promise<ReactionDetailsData | undefined>;
+    deleteReaction(resourceId: string): Promise<void>;
+    updateReaction(resourceId: string, reactionType: ReactionType): Promise<void>;
+    createReaction(resourceId: string, reactionType: ReactionType): Promise<void>;
+}

package/dist/audience/Service.d.ts

@@ -0,0 +1,13 @@
+import { App, ResourceType } from '../globals';
+import { IOdeServices } from '../services/OdeServices';
+import { ReactionsService } from './ReactionsService';
+import { ViewsService } from './ViewsService';
+import { IAudienceService } from './interface';
+export declare class AudienceService implements IAudienceService {
+    private context;
+    private module;
+    private resourceType;
+    constructor(context: IOdeServices, module: App, resourceType: ResourceType);
+    get views(): ViewsService;
+    get reactions(): ReactionsService;
+}

package/dist/audience/ViewsService.d.ts

@@ -0,0 +1,12 @@
+import { IOdeServices } from '../services/OdeServices';
+import { IViewsService, ViewsCounters, ViewsDetails } from './interface';
+export declare class ViewsService implements IViewsService {
+    private context;
+    private module;
+    private resourceType;
+    constructor(context: IOdeServices, module: string, resourceType: string);
+    private get http();
+    getCounters(resourceIds: string[]): Promise<ViewsCounters>;
+    getDetails(resourceId: string): Promise<ViewsDetails | undefined>;
+    trigger(resourceId: string): Promise<void>;
+}

package/dist/audience/interface.d.ts

@@ -0,0 +1,108 @@
+import { UserProfile } from '../session/interfaces';
+export interface IAudienceService {
+    readonly views: IViewsService;
+    readonly reactions: IReactionsService;
+}
+export interface IViewsService {
+    /**
+     * Load the views counter for a list of resources.
+     * @param resourceIds list of resource ids
+     * @returns map of counters, indexed by resource id.
+     */
+    getCounters(resourceIds: string[]): Promise<ViewsCounters>;
+    /**
+     * Load the views details for a resource.
+     * @param resourceId ID of the resource
+     * @returns detailed views counters, or `undefined` if an error occured.
+     */
+    getDetails(resourceId: string): Promise<ViewsDetails | undefined>;
+    /**
+     * Trigger a view for a resource.
+     * @param resourceId id
+     */
+    trigger(resourceId: string): Promise<void>;
+}
+/**
+ * ViewsCounters model
+ */
+export type ViewsCounters = {
+    [resourceId: string]: number;
+};
+/**
+ * Views details
+ */
+export interface ViewsDetails {
+    viewsCounter: number;
+    uniqueViewsCounter: number;
+    uniqueViewsPerProfile?: ViewsDetailsProfile[];
+}
+/**
+ * Views details
+ */
+export interface ViewsDetailsProfile {
+    profile: UserProfile[number];
+    counter: number;
+}
+export interface IReactionsService {
+    /**
+     * Load the list of available reactions types, which is configured on the platform.
+     * @return a list of types, or undefined if an error occured.
+     */
+    loadAvailableReactions(): Promise<ReactionType[] | undefined>;
+    /**
+     * Load the reactions summary for a list of resources.
+     * @param resourceIds list of resource ids
+     * @returns map of summaries, indexed by resource id.
+     */
+    loadReactionSummaries(resourceIds: string[]): Promise<{
+        [resourceId: string]: ReactionSummaryData | undefined;
+    }>;
+    /**
+     * Load the reactions details for a resource.
+     * @param resourceId ID of the resource
+     * @param page Page number
+     * @param size Number of results per page.
+     */
+    loadReactionDetails(resourceId: string, page: number, size: number): Promise<ReactionDetailsData | undefined>;
+    /**
+     * Remove the current user reaction to a resource.
+     * @param resourceId id
+     */
+    deleteReaction(resourceId: string): Promise<void>;
+    /**
+     * Change the current user reaction to a resource.
+     * @param resourceId id
+     * @param reactionType reaction to set
+     */
+    updateReaction(resourceId: string, reactionType: ReactionType): Promise<void>;
+    /**
+     * Set the current user reaction to a resource.
+     * @param resourceId id
+     * @param reactionType reaction to set
+     */
+    createReaction(resourceId: string, reactionType: ReactionType): Promise<void>;
+}
+/** Typing of a Reaction */
+export declare const ReactionTypes: readonly ["REACTION_1", "REACTION_2", "REACTION_3", "REACTION_4"];
+export type ReactionType = (typeof ReactionTypes)[number];
+/** Typing of a Reaction summary */
+export type ReactionSummaryData = {
+    reactionTypes?: Array<ReactionType> | null;
+    userReaction?: ReactionType | null;
+    totalReactionsCounter: number;
+};
+/** Typing of a Reaction details */
+export type ReactionDetailsData = {
+    reactionCounters: {
+        countByType: {
+            [type in ReactionType]?: number;
+        };
+        allReactionsCounter: number;
+    };
+    userReactions: Array<{
+        userId: string;
+        profile: 'Teacher' | 'Student' | 'Relative' | 'Personnel';
+        reactionType: ReactionType;
+        displayName: string;
+    }>;
+};

package/dist/cache/Service.d.ts

@@ -0,0 +1,14 @@
+import { IHttpParams, IHttpResponse } from '../transport/interfaces';
+import { IOdeServices } from '../services/OdeServices';
+export declare class CacheService {
+    private context;
+    constructor(context: IOdeServices);
+    private get http();
+    private fromCacheIfPossible;
+    clearCache(key?: string): void;
+    httpGet<R = any>(url: string, params?: IHttpParams): Promise<{
+        value: R;
+        response: IHttpResponse;
+    }>;
+    httpGetJson<R = any>(url: string, params?: IHttpParams): Promise<R>;
+}

package/dist/configure/Analytics.d.ts

@@ -0,0 +1,40 @@
+import { AnalyticStatus, IXitiTrackingParams, IMatomoTrackingParams, ITrackingParams, TrackingType } from './interfaces';
+export type ParamsByTrackingSystem = {
+    type: 'none' | 'internal' | 'matomo' | 'multiple';
+    internal?: ITrackingParams;
+    matomo?: IMatomoTrackingParams;
+    xiti?: IXitiTrackingParams;
+};
+export type XitiConf = {
+    ID_EXPLOITANT: string;
+    ID_PLATEFORME: string;
+    ID_PROJET: string;
+    active: boolean;
+    config: boolean;
+    structureMap?: {
+        [structureId: string]: {
+            UAI?: string;
+            active: boolean;
+            collectiviteId?: number;
+            plateformeId?: any;
+            projetId?: any;
+        };
+    };
+};
+export declare class Analytics {
+    private _status;
+    private _params?;
+    get status(): AnalyticStatus;
+    xiti(): Promise<IXitiTrackingParams | undefined>;
+    parameters<T extends ITrackingParams>(type: TrackingType): Promise<T | undefined>;
+    private parametersWithCheck;
+    /**
+     * This method loads the conf and waits for the user session to start.
+     * It can be called ASAP, but it will be automatically called if needed.
+     * @returns A promise of the end of the init process (it may throw errors)
+     * @throws ERROR_CODE.MALFORMED_DATA when config cannot be read.
+     */
+    private initialize;
+    /** 2021 implementation of XiTi. */
+    private initializeXiti;
+}

package/dist/configure/AppConf.d.ts

@@ -0,0 +1,17 @@
+import { App } from '../globals';
+import { IWebApp } from '../session/interfaces';
+export declare class AppConf {
+    private _publicConf;
+    private _currentApp?;
+    private _appConf;
+    /**
+     * Get the currently initialized App.
+     * @see getter SessionFramework.currentApp
+     */
+    get currentApp(): App | null;
+    setCurrentApp(app: App): AppConf;
+    initialize(app: App, alternativeApp?: boolean): Promise<void>;
+    getPublicConf(app: App): Promise<any>;
+    getWebAppConf(app: App): Promise<IWebApp | undefined>;
+    loadI18n(app: App): Promise<void>;
+}

package/dist/configure/Framework.d.ts

@@ -0,0 +1,22 @@
+import { IConfigurationFramework } from './interfaces';
+import { Theme } from './Theme';
+import { Idiom } from '../idiom/Idiom';
+import { User } from './User';
+import { AppConf } from './AppConf';
+import { Analytics } from './Analytics';
+export declare class ConfigurationFramework implements IConfigurationFramework {
+    readonly Platform: {
+        deploymentTag: string;
+        cdnDomain: string;
+        apps: AppConf;
+        theme: Theme;
+        analytics: Analytics;
+        idiom: Idiom;
+        listLanguages: () => Promise<any>;
+    };
+    readonly School: {};
+    readonly User: User;
+    initialize(version?: string | null, cdnDomain?: string | null): Promise<void>;
+}
+/** The whole framework is a singleton. */
+export declare const configure: ConfigurationFramework;

package/dist/configure/Service.d.ts

@@ -0,0 +1,21 @@
+import { App } from '../globals';
+import { IOdeServices } from '../services/OdeServices';
+import { IGetConf } from './interfaces';
+export declare class ConfService {
+    private context;
+    constructor(context: IOdeServices);
+    private get http();
+    private get cache();
+    private get cdnDomain();
+    private get notify();
+    getConf(app: App): Promise<IGetConf>;
+    getPublicConf<T>(app: App): Promise<T>;
+    getCdnUrl(): string | undefined;
+    savePreference<T>(key: string, value: T): Promise<void>;
+    getPreference<T>(key: string): Promise<T>;
+    private getThemeConf;
+    private getApplicationsList;
+    private getWebAppConf;
+    private getTheme;
+    getLogoutCallback(version?: string): Promise<any>;
+}

package/dist/configure/Theme.d.ts

@@ -0,0 +1,34 @@
+import { ITheme, IThemeConf, IThemeDesc, IThemeOverrides, IThemeConfOverriding } from './interfaces';
+export declare class Theme implements ITheme {
+    private _conf?;
+    private _loaded?;
+    skinName: string;
+    themeName: string;
+    skin: string;
+    themeUrl: string;
+    templateOverrides: IThemeOverrides;
+    portalTemplate: string;
+    basePath: string;
+    logoutCallback: string;
+    skins: Array<IThemeConfOverriding>;
+    is1D: boolean;
+    is2D: boolean;
+    initialize(version?: string): Promise<void>;
+    private get version();
+    private get cdnDomain();
+    onFullyReady(): Promise<ITheme>;
+    private _onSkinReady;
+    onSkinReady(): Promise<ITheme>;
+    private _onOverrideReady;
+    onOverrideReady(): Promise<IThemeOverrides>;
+    getConf(version?: string): Promise<IThemeConf>;
+    load(version?: string): Promise<void>;
+    private loadDisconnected;
+    private loadConnected;
+    /** Load the user's configured theme. */
+    private loadDefaultTheme;
+    listThemes(): Promise<IThemeDesc[]>;
+    setDefaultTheme(theme: IThemeDesc): Promise<void>;
+    listSkins(): Promise<IThemeConfOverriding[]>;
+    getHelpPath(): Promise<String>;
+}

package/dist/configure/User.d.ts

@@ -0,0 +1,21 @@
+import { App } from '../globals';
+import { IUserPreferences } from './interfaces';
+import { IWebApp } from '../session/interfaces';
+export declare class User {
+    private _me;
+    private _keepOpenOnLogout;
+    private _preferences;
+    private _bookmarkedApps;
+    get keepOpenOnLogout(): boolean;
+    get preferences(): IUserPreferences;
+    get bookmarkedApps(): Array<IWebApp>;
+    initialize(version?: string): Promise<void>;
+    private setCurrentModel;
+    private loadPublicConf;
+    /** Bookmarks : pinned apps */
+    private loadBookmarks;
+    loadAppPrefs(app: App): Promise<any>;
+    saveAppPrefs(app: App): Promise<void>;
+    loadLanguage(): Promise<string>;
+    saveLanguage(lang: string): Promise<void>;
+}