From 3aa119a0632fa522a8f161f87937d25fe500dca3 Mon Sep 17 00:00:00 2001 From: James Cook Date: Sun, 16 Apr 2023 20:47:40 +0100 Subject: [PATCH] feat: better documentation --- .gitignore | 4 ++- .vscode/extensions.json | 2 +- package.json | 2 +- readme.md | 8 +++-- src/baseClient.ts | 64 +++++++++++++++++++++++++++++++-------- src/index.ts | 13 +++++++- src/parentClient.ts | 16 +++++----- src/studentClient.ts | 20 ++++++++---- src/types.ts | 31 ++++++++++++------- src/utils.ts | 6 ++++ tests/config.example.json | 2 +- typedoc.config.cjs | 17 +++++++++++ 12 files changed, 141 insertions(+), 44 deletions(-) create mode 100644 typedoc.config.cjs diff --git a/.gitignore b/.gitignore index 815af20..d09bd88 100644 --- a/.gitignore +++ b/.gitignore @@ -118,4 +118,6 @@ dist .pnp.* tests/config.json -tests/sandbox.js \ No newline at end of file +tests/sandbox.js + +docs/ \ No newline at end of file diff --git a/.vscode/extensions.json b/.vscode/extensions.json index 9c2760f..e7cd390 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -4,4 +4,4 @@ "esbenp.prettier-vscode", "EditorConfig.EditorConfig" ] -} \ No newline at end of file +} diff --git a/package.json b/package.json index a93be43..48a294f 100644 --- a/package.json +++ b/package.json @@ -19,7 +19,7 @@ "main": "./dist/index.js", "scripts": { "build": "tsc", - "generateDocs": "typedoc --entryPointStrategy expand ./src", + "generateDocs": "typedoc --options typedoc.config.cjs", "test": "jest", "prepublishOnly": "pnpm run build", "publishNow": "pnpx np --no-publish && npm publish" diff --git a/readme.md b/readme.md index 6ba2f51..522b4fe 100644 --- a/readme.md +++ b/readme.md @@ -2,10 +2,12 @@ A client for the classcharts API -* [Documentation](https://classchartsapi.github.io/classcharts-api-js/) -* [API Documentation (with library examples)](https://classchartsapi.github.io/api-docs/#introduction) -* [Discord](https://discord.gg/DTcwugcgZ2) +- [Documentation](https://classchartsapi.github.io/classcharts-api-js/) +- [API Documentation (with library examples)](https://classchartsapi.github.io/api-docs/#introduction) +- [Discord](https://discord.gg/DTcwugcgZ2) + # Examples + Docs are very much a WIP, for any help with the library, please join the discord above ```typescript diff --git a/src/baseClient.ts b/src/baseClient.ts index 50a6c30..fae6b4c 100644 --- a/src/baseClient.ts +++ b/src/baseClient.ts @@ -20,13 +20,31 @@ import type { import { PING_INTERVAL } from "./consts.js"; /** - * The base client + * Shared client for both parent and student. This is not exported and should not be used directly + * @internal */ -export class ClasschartsClient { +export class BaseClient { + /** + * @property studentId Currently selected student ID + */ public studentId = 0; + /** + * @internal + * @property authCookies Cookies used for authentication (set during login and can be empty) + */ public authCookies: Array; + /** + * @property sessionId Session ID used for authentication + */ public sessionId = ""; + /** + * @property lastPing Last time the sessionId was updated + */ public lastPing = 0; + /** + * @property API_BASE Base API URL, this is different depending if its called as a parent or student + * @internal + */ protected API_BASE = ""; /** * @@ -36,6 +54,12 @@ export class ClasschartsClient { this.authCookies = []; this.API_BASE = API_BASE; } + /** + * Revalidates the session ID. + * + * This is called automatically when the session ID is older than 3 minutes or when intially using the .login() method + * @internal + */ public async getNewSessionId() { const pingFormData = new URLSearchParams(); pingFormData.append("include_data", "true"); @@ -50,6 +74,17 @@ export class ClasschartsClient { this.sessionId = pingData.meta.session_id; this.lastPing = Date.now(); } + /** + * Makes a request to the Classcharts API with the required authentication headers + * + * @param path Path to the API endpoint + * @param kyOptions Ky (fetch library) request options + * @param options + * @param options.revalidateToken Whether to revalidate the session ID if it is older than 3 minutes + * + * @returns Response + * @internal + */ public async makeAuthedRequest( path: string, kyOptions: KyOptions, @@ -87,9 +122,8 @@ export class ClasschartsClient { // eslint-disable-next-line @typescript-eslint/no-explicit-any return responseJSON as any; } - /** - * Gets general information about the logged in student + * Gets general information about the current student * @returns Student object */ async getStudentInfo(): Promise { @@ -102,9 +136,12 @@ export class ClasschartsClient { return data; } /** + * Gets the current student's activity + * * This function is only used for pagination, you likely want client.getFullActivity * @param options GetActivityOptions * @returns Activity data + * @see getFullActivity */ async getActivity(options?: GetActivityOptions): Promise { const params = new URLSearchParams(); @@ -119,9 +156,12 @@ export class ClasschartsClient { ); } /** - * Helper function for getActivity, returns all the data from the selected dates + * Gets the current student's activity between two dates + * + * This function will automatically paginate through all the data returned by getActivity * @param options GetFullActivityOptions * @returns Activity Data + * @see getActivity */ async getFullActivity( options: GetFullActivityOptions @@ -148,7 +188,7 @@ export class ClasschartsClient { return data; } /** - * Gets the logged in students behaviour points + * Gets the current student's behaviour * @param options GetBehaviourOptions * @returns Array of behaviour points */ @@ -166,7 +206,7 @@ export class ClasschartsClient { ); } /** - * Gets a list of the logged in student's homeworks + * Gets the current student's homework * @param options GetHomeworkOptions * @returns Array of homeworks */ @@ -200,7 +240,7 @@ export class ClasschartsClient { return data; } /** - * Gets the logged in student's lessons for a day + * Gets the current student's lessons for a given date * @param options GetLessonsOptions * @returns Array of lessons */ @@ -216,7 +256,7 @@ export class ClasschartsClient { ); } /** - * Gets a list of the students badges + * Gets the current student's earned badges * @returns Array of badges */ async getBadges(): Promise { @@ -228,7 +268,7 @@ export class ClasschartsClient { ); } /** - * Gets the logged in student's announcements + * Gets the current student's announcements * @returns Array of announcements */ async getAnnouncements(): Promise { @@ -242,7 +282,7 @@ export class ClasschartsClient { ).data; } /** - * Gets the logged in student's detentions + * Gets the current student's detentions * @returns Array of detentions */ async getDetentions(): Promise { @@ -256,7 +296,7 @@ export class ClasschartsClient { ).data; } /** - * Gets the logged in student's attendance + * Gets the current student's attendance * @param options GetAttendanceOptions * @returns Array of dates of attendance */ diff --git a/src/index.ts b/src/index.ts index fbd8b56..d3bf997 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,2 +1,13 @@ -export * from "./parentClient.js"; export * from "./studentClient.js"; +export * from "./parentClient.js"; +export { + Student, + ActivityPoint, + BehaviourTimelinePoint, + Homework, + Lesson, + Badge, + Announcement, + Detention, + AttendanceDate, +} from "./types.js"; diff --git a/src/parentClient.ts b/src/parentClient.ts index dafad5c..0d441fd 100644 --- a/src/parentClient.ts +++ b/src/parentClient.ts @@ -1,21 +1,21 @@ import ky from "ky-universal"; import type { GetPupilsResponse } from "./types.js"; -import { ClasschartsClient } from "./baseClient.js"; +import { BaseClient } from "./baseClient.js"; import { API_BASE_PARENT, BASE_URL } from "./consts.js"; import { parseCookies } from "./utils.js"; /** * Parent Client */ -export class ParentClient extends ClasschartsClient { +export class ParentClient extends BaseClient { private password = ""; private email = ""; // @ts-expect-error Init in .login public pupils: GetPupilsResponse; /** * - * @param email Parents email address - * @param password Parents password + * @param email Parent's email address + * @param password Parent's password */ constructor(email: string, password: string) { super(API_BASE_PARENT); @@ -24,7 +24,7 @@ export class ParentClient extends ClasschartsClient { } /** - * Logs the user in the client and authenticates with classcharts + * Authenticates with classcharts */ async login(): Promise { if (!this.email) throw new Error("Email not inputted"); @@ -63,7 +63,7 @@ export class ParentClient extends ClasschartsClient { super.studentId = this.pupils[0].id; } /** - * Get Pupil details + * Get a list of pupils connected to this parent's account * @returns an array of Pupils connected to this parent's account */ async getPupils(): Promise { @@ -73,7 +73,9 @@ export class ParentClient extends ClasschartsClient { } /** * Selects a pupil to be used with API requests - * @param pupilId Pupil ID obtained from this.pupils or getPupils + * @param pupilId Pupil ID obtained from this.pupils or getPupils() + * + * @see getPupils */ async selectPupil(pupilId: number): Promise { if (!pupilId) throw new Error("No pupil ID specified"); diff --git a/src/studentClient.ts b/src/studentClient.ts index 1fceae1..b6e3d59 100644 --- a/src/studentClient.ts +++ b/src/studentClient.ts @@ -1,14 +1,22 @@ import { API_BASE_STUDENT, BASE_URL } from "./consts.js"; -import { ClasschartsClient } from "./baseClient.js"; +import { BaseClient } from "./baseClient.js"; import { parseCookies } from "./utils.js"; import ky from "ky-universal"; + /** * Student Client */ - -export class StudentClient extends ClasschartsClient { - public studentCode = ""; - public dateOfBirth = ""; +export class StudentClient extends BaseClient { + /** + * @property studentCode Classcharts student code + * @internal + */ + private studentCode = ""; + /** + * @property dateOfBirth Student's date of birth + * @internal + */ + private dateOfBirth = ""; /** * @@ -22,7 +30,7 @@ export class StudentClient extends ClasschartsClient { } /** - * Initialises the client and authenticates with classcharts + * Authenticates with classcharts */ async login(): Promise { if (!this.studentCode) throw new Error("Student Code not inputted"); diff --git a/src/types.ts b/src/types.ts index 9b0b671..aa3c5f1 100644 --- a/src/types.ts +++ b/src/types.ts @@ -1,4 +1,9 @@ /* eslint-disable @typescript-eslint/no-explicit-any */ + +/** + * Helper type to define response from classcharts + * @internal + */ export type ClassChartsResponse = { data: T; meta: E; @@ -44,11 +49,11 @@ export interface Student { survey_id: number | null; detention_alias_plural_uc: string; } -interface GetStudentInfoData { +export interface GetStudentInfoData { user: Student; } -interface GetStudentInfoMeta { +export interface GetStudentInfoMeta { version: string; } export type GetStudentInfoResponse = ClassChartsResponse< @@ -74,7 +79,7 @@ export interface BehaviourTimelinePoint { start: string; end: string; } -interface BehaviourResponseData { +export interface BehaviourResponseData { timeline: Array; positive_reasons: Record; negative_reasons: Record; @@ -83,7 +88,7 @@ interface BehaviourResponseData { other_positive_count: Array>; other_negative_count: Array>; } -interface BehaviourResponseMeta { +export interface BehaviourResponseMeta { start_date: string; end_date: string; step_size: string; @@ -132,7 +137,7 @@ export interface ActivityPoint { detention_location: string | null; detention_type: string | null; } -type ActivityResponseData = Array; +export type ActivityResponseData = Array; interface ActivityResponseMeta { start_date: string; end_date: string; @@ -149,6 +154,10 @@ export type DisplayDate = "due_date" | "issue_date"; export interface GetHomeworkOptions { /** * Way to sort homeworks + * + * Used to sort homeworks by when they are due or when they were issued + * @default "issue_date" + * */ displayDate?: DisplayDate; /** @@ -196,8 +205,8 @@ export interface Homework { validated_links: Array; validated_attachments: Array; } -type HomeworksResponseData = Array; -interface HomeworksResponseMeta { +export type HomeworksResponseData = Array; +export interface HomeworksResponseMeta { start_date: string; end_date: string; display_type: DisplayDate; @@ -238,13 +247,13 @@ export interface Lesson { pupil_note: string; pupil_note_raw: string; } -type LessonsResponseData = Lesson[]; +export type LessonsResponseData = Lesson[]; interface PeriodMeta { number: string; start_time: string; end_time: string; } -interface LessonsResponseMeta { +export interface LessonsResponseMeta { dates: string[]; timetable_dates: string[]; periods: PeriodMeta[]; @@ -285,8 +294,8 @@ export interface Badge { pupil_badges: Array; icon_url: string; } -type BadgesResponseData = Array; -type BadgesResponseMeta = []; +export type BadgesResponseData = Array; +export type BadgesResponseMeta = []; export type BadgesResponse = ClassChartsResponse< BadgesResponseData, BadgesResponseMeta diff --git a/src/utils.ts b/src/utils.ts index d2e108d..cbe4d04 100644 --- a/src/utils.ts +++ b/src/utils.ts @@ -1,3 +1,9 @@ +/** + * Parse cookies from string + * @param input Input string + * @returns Object of cookies + * @internal + */ export function parseCookies(input: string) { const output: Record = {}; const cookies = input.split(","); diff --git a/tests/config.example.json b/tests/config.example.json index a7cefa2..3d3aba6 100644 --- a/tests/config.example.json +++ b/tests/config.example.json @@ -1,4 +1,4 @@ { "code": "", "dob": "" -} \ No newline at end of file +} diff --git a/typedoc.config.cjs b/typedoc.config.cjs new file mode 100644 index 0000000..fd57425 --- /dev/null +++ b/typedoc.config.cjs @@ -0,0 +1,17 @@ +/** @type {import('typedoc').TypeDocOptions} */ +module.exports = { + entryPointStrategy: "resolve", + entryPoints: [ + "src/studentClient.ts", + "src/parentClient.ts", + "src/baseClient.ts", + "src/types.ts", + ], + navigationLinks: { + Discord: "https://discord.gg/DTcwugcgZ2", + Github: "https://github.com/classchartsapi/classcharts-api-js", + }, + includeVersion: true, + out: "docs", + sort: "required-first", +};