@goralys/core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,259 @@
+type UserRole = {
+    role: "admin" | "teacher" | "student" | "none";
+};
+declare const USER_ROLES: readonly ["admin", "teacher", "student", "none"];
+type UserData = {
+    username: string;
+    full_name: string;
+    role: UserRole["role"];
+    public_id: string;
+    email: string | null | undefined;
+};
+type User = {
+    username: string;
+    publicId: string;
+    fullName: string;
+    role: UserRole["role"];
+};
+type AuthEvent = "unauthenticated" | "expired";
+type UserEvent = "login" | "logout" | "register";
+type ConfirmOptions = {
+    title: string;
+    message: string;
+};
+
+type Toast = {
+    type: "error" | "warning" | "info" | "success";
+    title: string;
+    message: string;
+    expires?: number;
+};
+type ToastFn = (toast: Toast, duration?: number) => void;
+
+type SubjectStatus = "not_submitted" | "submitted" | "rejected" | "approved";
+declare const SubjectStatusConfig: Record<SubjectStatus, {
+    label: string;
+    helper: Record<UserRole["role"], string>;
+}>;
+type Subject = {
+    comment: string;
+    hasDraft: boolean;
+    lastRejected?: string;
+    status: SubjectStatus;
+    student: string;
+    studentToken: string;
+    subject: string;
+    teacher: string;
+    teacherToken: string;
+    topic: string;
+    interdisciplinary: boolean;
+};
+declare const searchFields: {
+    readonly all: "Tout";
+    readonly student: "Élèves";
+    readonly teacher: "Professeur";
+    readonly topic: "Matière";
+};
+type SubjectsSearchField = keyof typeof searchFields;
+type DraftModalResult = {
+    type: "withDraft";
+    file: File | null;
+} | {
+    type: "withoutDraft";
+} | {
+    type: "closed";
+};
+declare const getStatusLabel: (status: SubjectStatus) => string;
+declare const getStatusHelper: (status: SubjectStatus, role: UserRole["role"]) => string;
+
+declare function useSubjects(role: UserRole["role"], showToast: ToastFn): {
+    subjects: Subject[] | null;
+    refetch: () => Promise<undefined | void>;
+    syncKey: string;
+};
+
+interface PHPDateTime {
+    date: string;
+    timezone_type: number;
+    timezone: string;
+}
+type CookieValue = string | boolean | number | null | undefined;
+
+declare const reasonsConfig: {
+    readonly "password-forgot": {
+        readonly label: "Mot de passe oublié";
+    };
+    readonly "subject-error": {
+        readonly label: "Question envoyée/validée/rejetée par erreur";
+    };
+    readonly "personal-info-error": {
+        readonly label: "Informations personnelles erronées (ex: Nom/Prénom)";
+    };
+    readonly other: {
+        readonly label: "Autre (précisez)";
+    };
+};
+type SupportReasons = keyof typeof reasonsConfig;
+type SupportTicket = {
+    id: number;
+    reason: SupportReasons;
+    opener: string;
+    openerToken: string;
+    message: string;
+    createdAt: PHPDateTime;
+};
+
+declare function useSupportTickets(showToast: ToastFn): {
+    supportTickets: SupportTicket[] | null;
+    refetch: () => Promise<undefined | void>;
+    syncKey: string;
+};
+
+interface UserFetchResult {
+    users: User[] | null;
+    refetch: () => Promise<void | undefined>;
+    syncKey: string;
+}
+declare function useUsers(showToast: ToastFn): UserFetchResult;
+declare function useVirtualUsers(showToast: ToastFn): UserFetchResult;
+declare function useAdmins(showToast: ToastFn): UserFetchResult;
+declare function useVirtualAdmins(showToast: ToastFn): UserFetchResult;
+
+declare const LOGO_PATH: {
+    main: string;
+    eye: string;
+};
+
+declare const PERSISTANT_COOKIES: string[];
+declare const PERSISTANT_LOCALS: string[];
+declare const USERNAME_KEY = "username";
+declare const ROLE_KEY = "user-role";
+declare const FULL_NAME_KEY = "full-name";
+declare const EMAIL_KEY = "email";
+declare const PUB_ID_KEY = "public-id";
+declare const SUBJECT_SYNC_RADIX = "subjects-synced-";
+declare const SUBJECT_CACHE_RADIX = "subjects-cache-";
+declare const USER_CACHE_RADIX = "users-cache-";
+declare const USER_SYNC_RADIX = "users-synced-";
+declare const ADMIN_CACHE_RADIX = "admins-cache-";
+declare const ADMIN_SYNC_RADIX = "admins-synced-";
+declare const SUPPORT_TICKET_CACHE = "support-tickets-cache";
+declare const SUPPORT_TICKET_SYNC = "support-tickets-synced";
+declare const SUBJECT_SYNCS: Record<UserRole["role"], string>;
+declare const SUBJECT_CACHES: Record<UserRole["role"], string>;
+type UserType = {
+    type: "users-virtual" | "users-real" | "admins-virtual" | "admins-real";
+};
+declare const USER_SYNCS: Record<UserType["type"], string>;
+declare const USER_CACHES: Record<UserType["type"], string>;
+type Item = {
+    q: string;
+    a: string;
+};
+type Detail = {
+    title: string;
+    description: string;
+    format: string;
+};
+type Subsection = {
+    id: string;
+    title: string;
+    items: Item[];
+    details?: Detail[];
+};
+type Section = {
+    id: string;
+    title: string;
+    subsections: Subsection[];
+};
+declare const helpContent: Section[];
+
+declare function setCookiesExpire(duration: number): void;
+
+declare function isFoolsDay(): boolean;
+
+declare function buildArray<T>(...items: (T | false | null | undefined)[]): T[];
+declare const parsePhpDateTime: (phpDate: PHPDateTime) => string;
+
+declare function emitAuthEvent(event: AuthEvent): void;
+declare function onAuthEvent(callback: (event: AuthEvent) => void): () => void;
+
+type CheckAuthImpl = () => boolean;
+declare function configureCheckAuth(impl: CheckAuthImpl): void;
+declare function isAuthenticated(): boolean;
+
+declare function emitUserEvent(event: UserEvent): void;
+declare function onUserEvent(callback: (event: UserEvent) => void): () => void;
+
+interface GoralysClientConfig {
+    apiDomain: string;
+}
+declare function configureGoralysClient(cfg: GoralysClientConfig): void;
+declare function getGoralysClientConfig(): GoralysClientConfig;
+
+/**
+ * This filed is a slightly modified version of Next.js own http method declaration.
+ */
+declare const HTTP_METHODS: readonly ["GET", "HEAD", "OPTIONS", "POST", "PUT", "DELETE", "PATCH", "BREW"];
+type HttpMethod = (typeof HTTP_METHODS)[number];
+/**
+ * Checks to see if the passed string is an HTTP method. Note that this is case-sensitive.
+ *
+ * @param maybeMethod the string that may be an HTTP method.
+ * @returns true if the string is an HTTP method.
+ */
+declare function isHTTPMethod(maybeMethod: string): maybeMethod is HttpMethod;
+
+declare function goralysFetchClient(method: HttpMethod, input: string | URL | Request, payload?: Record<string, string | number | boolean | null> | FormData, requestOptions?: RequestInit): Promise<Response>;
+declare function fetchCsrfClient(formId: string): Promise<string | null>;
+declare function buildApiUrl(endpoint: string, params: Record<string, string | null>, domain?: boolean): string;
+declare function handleToastRequest(r: Response, showToast: (payload: Toast, duration?: number) => void, redirect?: boolean, duration?: number): Promise<boolean>;
+
+declare class GoralysActionHandler {
+    handle: (r: Response) => Promise<void>;
+    private onLogin;
+}
+
+type NavigationEvent = {
+    type: "teapot";
+    toastType: string;
+    toastTitle: string;
+    toastMessage: string;
+} | {
+    type: "redirect";
+    url: string;
+};
+type Listener = (event: NavigationEvent) => void;
+declare function emitNavigationEvent(event: NavigationEvent): void;
+declare function onNavigationEvent(listener: Listener): () => void;
+
+interface StorageAdapter {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+declare function configureStorage(customAdapter: StorageAdapter): void;
+declare function storageGet(key: string): Promise<string | null>;
+declare function storageSet(key: string, value: string): Promise<void>;
+declare function storageRemove(key: string): Promise<void>;
+
+/**
+ * Returns the full name of a subject based on its short name or an alias.
+ * It searches for the first subject in {@link SUBJECTS} whose short name starts with the given string.
+ *
+ * @param short The short name, alias, or prefix to search for.
+ * @returns The full subject name if a match is found; otherwise, returns the input string itself.
+ */
+declare function getLongFromShort(short: string): string;
+
+declare function fetchSubjectsForRoleClient(role: UserRole): Promise<Response | null>;
+
+declare function configUserCacheCallbacks(cache: () => Promise<void>, empty: () => void): void;
+declare function cacheUserDataClient(): Promise<void>;
+declare function emptyUserCacheClient(): void;
+declare function fetchUsersClient(): Promise<Response>;
+declare function fetchVirtualUsersClient(): Promise<Response>;
+declare function fetchAdminsClient(): Promise<Response>;
+declare function fetchVirtualAdminsClient(): Promise<Response>;
+
+export { ADMIN_CACHE_RADIX, ADMIN_SYNC_RADIX, type AuthEvent, type ConfirmOptions, type CookieValue, type DraftModalResult, EMAIL_KEY, FULL_NAME_KEY, GoralysActionHandler, type GoralysClientConfig, HTTP_METHODS, type HttpMethod, LOGO_PATH, PERSISTANT_COOKIES, PERSISTANT_LOCALS, type PHPDateTime, PUB_ID_KEY, ROLE_KEY, SUBJECT_CACHES, SUBJECT_CACHE_RADIX, SUBJECT_SYNCS, SUBJECT_SYNC_RADIX, SUPPORT_TICKET_CACHE, SUPPORT_TICKET_SYNC, type StorageAdapter, type Subject, type SubjectStatus, SubjectStatusConfig, type SubjectsSearchField, type SupportReasons, type SupportTicket, type Toast, type ToastFn, USERNAME_KEY, USER_CACHES, USER_CACHE_RADIX, USER_ROLES, USER_SYNCS, USER_SYNC_RADIX, type User, type UserData, type UserEvent, type UserRole, type UserType, buildApiUrl, buildArray, cacheUserDataClient, configUserCacheCallbacks, configureCheckAuth, configureGoralysClient, configureStorage, emitAuthEvent, emitNavigationEvent, emitUserEvent, emptyUserCacheClient, fetchAdminsClient, fetchCsrfClient, fetchSubjectsForRoleClient, fetchUsersClient, fetchVirtualAdminsClient, fetchVirtualUsersClient, getGoralysClientConfig, getLongFromShort, getStatusHelper, getStatusLabel, goralysFetchClient, handleToastRequest, helpContent, isAuthenticated, isFoolsDay, isHTTPMethod, onAuthEvent, onNavigationEvent, onUserEvent, parsePhpDateTime, reasonsConfig, searchFields, setCookiesExpire, storageGet, storageRemove, storageSet, useAdmins, useSubjects, useSupportTickets, useUsers, useVirtualAdmins, useVirtualUsers };