mirror of
https://github.com/classchartsapi/classcharts-api-js.git
synced 2026-05-14 11:58:13 +00:00
feat: restructure src/
This commit is contained in:
James Cook
parent
3aa119a063
commit
e91fb1688d
6 changed files with 9 additions and 9 deletions
322
src/core/baseClient.ts
Normal file
322
src/core/baseClient.ts
Normal file
|
|
@ -0,0 +1,322 @@
|
|||
import ky, { type Options as KyOptions } from "ky-universal";
|
||||
import type {
|
||||
ActivityResponse,
|
||||
AnnouncementsResponse,
|
||||
AttendanceResponse,
|
||||
BadgesResponse,
|
||||
BehaviourResponse,
|
||||
ClassChartsResponse,
|
||||
DetentionsResponse,
|
||||
GetActivityOptions,
|
||||
GetAttendanceOptions,
|
||||
GetBehaviourOptions,
|
||||
GetFullActivityOptions,
|
||||
GetHomeworkOptions,
|
||||
GetLessonsOptions,
|
||||
GetStudentInfoResponse,
|
||||
HomeworksResponse,
|
||||
LessonsResponse,
|
||||
} from "../types.js";
|
||||
import { PING_INTERVAL } from "../utils/consts.js";
|
||||
|
||||
/**
|
||||
* Shared client for both parent and student. This is not exported and should not be used directly
|
||||
* @internal
|
||||
*/
|
||||
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<string>;
|
||||
/**
|
||||
* @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 = "";
|
||||
/**
|
||||
*
|
||||
* @param API_BASE Base API URL, this is different depending if its called as a parent or student
|
||||
*/
|
||||
constructor(API_BASE: string) {
|
||||
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");
|
||||
const pingData = await this.makeAuthedRequest(
|
||||
this.API_BASE + "/ping",
|
||||
{
|
||||
method: "POST",
|
||||
body: pingFormData,
|
||||
},
|
||||
{ revalidateToken: false }
|
||||
);
|
||||
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,
|
||||
options?: { revalidateToken?: boolean }
|
||||
) {
|
||||
if (!this.sessionId) throw new Error("No session ID");
|
||||
if (!options) {
|
||||
options = {};
|
||||
}
|
||||
if (typeof options?.revalidateToken == "undefined") {
|
||||
options.revalidateToken = true;
|
||||
}
|
||||
const requestOptions = {
|
||||
...kyOptions,
|
||||
headers: {
|
||||
Cookie: this?.authCookies?.join(";") ?? [],
|
||||
Authorization: "Basic " + this.sessionId,
|
||||
...kyOptions.headers,
|
||||
},
|
||||
credentials: undefined,
|
||||
} satisfies KyOptions;
|
||||
if (options?.revalidateToken === true && this.lastPing) {
|
||||
if (Date.now() - this.lastPing + 5000 > PING_INTERVAL) {
|
||||
await this.getNewSessionId();
|
||||
}
|
||||
}
|
||||
const request = await ky(path, requestOptions);
|
||||
const responseJSON = (await request.json()) as ClassChartsResponse<
|
||||
unknown,
|
||||
unknown
|
||||
>;
|
||||
if (responseJSON.success == 0) {
|
||||
throw new Error(responseJSON.error);
|
||||
}
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
return responseJSON as any;
|
||||
}
|
||||
/**
|
||||
* Gets general information about the current student
|
||||
* @returns Student object
|
||||
*/
|
||||
async getStudentInfo(): Promise<GetStudentInfoResponse> {
|
||||
const body = new URLSearchParams();
|
||||
body.append("include_data", "true");
|
||||
const data = await this.makeAuthedRequest(this.API_BASE + "/ping", {
|
||||
method: "POST",
|
||||
body: body,
|
||||
});
|
||||
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<ActivityResponse> {
|
||||
const params = new URLSearchParams();
|
||||
options?.from && params.append("from", options?.from);
|
||||
options?.to && params.append("to", options?.to);
|
||||
options?.last_id && params.append("last_id", options?.last_id);
|
||||
return this.makeAuthedRequest(
|
||||
this.API_BASE + "/activity/" + this.studentId + "?" + params.toString(),
|
||||
{
|
||||
method: "GET",
|
||||
}
|
||||
);
|
||||
}
|
||||
/**
|
||||
* 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
|
||||
): Promise<ActivityResponse["data"]> {
|
||||
let data: ActivityResponse["data"] = [];
|
||||
let prevLast: number | undefined;
|
||||
let gotData = true;
|
||||
while (gotData) {
|
||||
const params: GetActivityOptions = {
|
||||
from: options.from,
|
||||
to: options.to,
|
||||
};
|
||||
if (prevLast) {
|
||||
params.last_id = String(prevLast);
|
||||
}
|
||||
const fragment = (await this.getActivity(params)).data;
|
||||
if (!fragment || !fragment.length) {
|
||||
gotData = false;
|
||||
} else {
|
||||
data = data.concat(fragment);
|
||||
prevLast = fragment[fragment.length - 1].id;
|
||||
}
|
||||
}
|
||||
return data;
|
||||
}
|
||||
/**
|
||||
* Gets the current student's behaviour
|
||||
* @param options GetBehaviourOptions
|
||||
* @returns Array of behaviour points
|
||||
*/
|
||||
async getBehaviour(
|
||||
options?: GetBehaviourOptions
|
||||
): Promise<BehaviourResponse> {
|
||||
const params = new URLSearchParams();
|
||||
options?.from && params.append("from", options?.from);
|
||||
options?.to && params.append("to", options?.to);
|
||||
return await this.makeAuthedRequest(
|
||||
this.API_BASE + "/behaviour/" + this.studentId + "?" + params.toString(),
|
||||
{
|
||||
method: "GET",
|
||||
}
|
||||
);
|
||||
}
|
||||
/**
|
||||
* Gets the current student's homework
|
||||
* @param options GetHomeworkOptions
|
||||
* @returns Array of homeworks
|
||||
*/
|
||||
async getHomeworks(options?: GetHomeworkOptions): Promise<HomeworksResponse> {
|
||||
const params = new URLSearchParams();
|
||||
if (options?.displayDate)
|
||||
params.append("display_date", String(options?.displayDate));
|
||||
|
||||
options?.from && params.append("from", String(options?.from));
|
||||
options?.to && params.append("to", String(options?.to));
|
||||
const data: HomeworksResponse = await this.makeAuthedRequest(
|
||||
this.API_BASE + "/homeworks/" + this.studentId + "?" + params.toString(),
|
||||
{
|
||||
method: "GET",
|
||||
}
|
||||
);
|
||||
|
||||
for (let i = 0; i < data.data.length; i++) {
|
||||
data.data[i].description_raw = data.data[i].description;
|
||||
// homework.lesson.replace(/\\/g, '')
|
||||
data.data[i].description = data.data[i].description.replace(
|
||||
/(<([^>]+)>)/gi,
|
||||
""
|
||||
);
|
||||
data.data[i].description = data.data[i].description.replace(
|
||||
/ /g,
|
||||
""
|
||||
);
|
||||
data.data[i].description = data.data[i].description.trim();
|
||||
}
|
||||
return data;
|
||||
}
|
||||
/**
|
||||
* Gets the current student's lessons for a given date
|
||||
* @param options GetLessonsOptions
|
||||
* @returns Array of lessons
|
||||
*/
|
||||
async getLessons(options?: GetLessonsOptions): Promise<LessonsResponse> {
|
||||
if (!options?.date) throw new Error("No date specified");
|
||||
const params = new URLSearchParams();
|
||||
params.append("date", String(options?.date));
|
||||
return await this.makeAuthedRequest(
|
||||
this.API_BASE + "/timetable/" + this.studentId + "?" + params.toString(),
|
||||
{
|
||||
method: "GET",
|
||||
}
|
||||
);
|
||||
}
|
||||
/**
|
||||
* Gets the current student's earned badges
|
||||
* @returns Array of badges
|
||||
*/
|
||||
async getBadges(): Promise<BadgesResponse> {
|
||||
return await this.makeAuthedRequest(
|
||||
this.API_BASE + "/eventbadges/" + this.studentId,
|
||||
{
|
||||
method: "GET",
|
||||
}
|
||||
);
|
||||
}
|
||||
/**
|
||||
* Gets the current student's announcements
|
||||
* @returns Array of announcements
|
||||
*/
|
||||
async getAnnouncements(): Promise<AnnouncementsResponse> {
|
||||
return (
|
||||
await this.makeAuthedRequest(
|
||||
this.API_BASE + "/announcements/" + this.studentId,
|
||||
{
|
||||
method: "GET",
|
||||
}
|
||||
)
|
||||
).data;
|
||||
}
|
||||
/**
|
||||
* Gets the current student's detentions
|
||||
* @returns Array of detentions
|
||||
*/
|
||||
async getDetentions(): Promise<DetentionsResponse> {
|
||||
return (
|
||||
await this.makeAuthedRequest(
|
||||
this.API_BASE + "/detentions/" + this.studentId,
|
||||
{
|
||||
method: "GET",
|
||||
}
|
||||
)
|
||||
).data;
|
||||
}
|
||||
/**
|
||||
* Gets the current student's attendance
|
||||
* @param options GetAttendanceOptions
|
||||
* @returns Array of dates of attendance
|
||||
*/
|
||||
async getAttendance(
|
||||
options?: GetAttendanceOptions
|
||||
): Promise<AttendanceResponse> {
|
||||
const params = new URLSearchParams();
|
||||
options?.from && params.append("from", options?.from);
|
||||
options?.to && params.append("to", options?.to);
|
||||
return (
|
||||
await this.makeAuthedRequest(
|
||||
this.API_BASE +
|
||||
"/attendance/" +
|
||||
this.studentId +
|
||||
"?" +
|
||||
params.toString(),
|
||||
{
|
||||
method: "GET",
|
||||
}
|
||||
)
|
||||
).data;
|
||||
}
|
||||
}
|
||||
92
src/core/parentClient.ts
Normal file
92
src/core/parentClient.ts
Normal file
|
|
@ -0,0 +1,92 @@
|
|||
import ky from "ky-universal";
|
||||
import type { GetPupilsResponse } from "../types.js";
|
||||
|
||||
import { BaseClient } from "./baseClient.js";
|
||||
import { API_BASE_PARENT, BASE_URL } from "../utils/consts.js";
|
||||
import { parseCookies } from "../utils/utils.js";
|
||||
/**
|
||||
* Parent Client
|
||||
*/
|
||||
export class ParentClient extends BaseClient {
|
||||
private password = "";
|
||||
private email = "";
|
||||
// @ts-expect-error Init in .login
|
||||
public pupils: GetPupilsResponse;
|
||||
/**
|
||||
*
|
||||
* @param email Parent's email address
|
||||
* @param password Parent's password
|
||||
*/
|
||||
constructor(email: string, password: string) {
|
||||
super(API_BASE_PARENT);
|
||||
this.email = String(email);
|
||||
this.password = String(password);
|
||||
}
|
||||
|
||||
/**
|
||||
* Authenticates with classcharts
|
||||
*/
|
||||
async login(): Promise<void> {
|
||||
if (!this.email) throw new Error("Email not inputted");
|
||||
const formData = new URLSearchParams();
|
||||
formData.append("_method", "POST");
|
||||
formData.append("email", this.email);
|
||||
formData.append("logintype", "existing");
|
||||
formData.append("password", this.password);
|
||||
formData.append("recaptcha-token", "no-token-avaliable");
|
||||
const headers = new Headers({
|
||||
"Content-Type": "application/x-www-form-urlencoded",
|
||||
});
|
||||
const response = await ky(BASE_URL + "/parent/login", {
|
||||
method: "POST",
|
||||
body: formData,
|
||||
headers: headers,
|
||||
credentials: undefined,
|
||||
});
|
||||
if (response.status != 302 || !response.headers.get("set-cookie"))
|
||||
throw new Error(
|
||||
"Unauthenticated: Classcharts returned an error: " +
|
||||
response.status +
|
||||
" " +
|
||||
response.statusText
|
||||
);
|
||||
|
||||
const cookies = String(response.headers.get("set-cookie"));
|
||||
// this.authCookies = cookies.split(";");
|
||||
const sessionCookies = parseCookies(cookies);
|
||||
const sessionID = JSON.parse(
|
||||
String(sessionCookies["parent_session_credentials"])
|
||||
);
|
||||
super.sessionId = sessionID.session_id;
|
||||
this.pupils = await this.getPupils();
|
||||
if (!this.pupils) throw new Error("Account has no pupils attached");
|
||||
super.studentId = this.pupils[0].id;
|
||||
}
|
||||
/**
|
||||
* 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<GetPupilsResponse> {
|
||||
return super.makeAuthedRequest(super.API_BASE + "/pupils", {
|
||||
method: "GET",
|
||||
});
|
||||
}
|
||||
/**
|
||||
* Selects a pupil to be used with API requests
|
||||
* @param pupilId Pupil ID obtained from this.pupils or getPupils()
|
||||
*
|
||||
* @see getPupils
|
||||
*/
|
||||
async selectPupil(pupilId: number): Promise<void> {
|
||||
if (!pupilId) throw new Error("No pupil ID specified");
|
||||
const pupils = this.pupils;
|
||||
for (let i = 0; i < pupils.length; i++) {
|
||||
const pupil = pupils[i];
|
||||
if (pupil.id == pupilId) {
|
||||
super.studentId = pupil.id;
|
||||
return;
|
||||
}
|
||||
}
|
||||
throw new Error("No pupil with specified ID returned");
|
||||
}
|
||||
}
|
||||
69
src/core/studentClient.ts
Normal file
69
src/core/studentClient.ts
Normal file
|
|
@ -0,0 +1,69 @@
|
|||
import { API_BASE_STUDENT, BASE_URL } from "../utils/consts.js";
|
||||
import { BaseClient } from "./baseClient.js";
|
||||
import { parseCookies } from "../utils/utils.js";
|
||||
import ky from "ky-universal";
|
||||
|
||||
/**
|
||||
* Student Client
|
||||
*/
|
||||
export class StudentClient extends BaseClient {
|
||||
/**
|
||||
* @property studentCode Classcharts student code
|
||||
* @internal
|
||||
*/
|
||||
private studentCode = "";
|
||||
/**
|
||||
* @property dateOfBirth Student's date of birth
|
||||
* @internal
|
||||
*/
|
||||
private dateOfBirth = "";
|
||||
|
||||
/**
|
||||
*
|
||||
* @param studentCode Classcharts student code
|
||||
* @param dateOfBirth Student's date of birth
|
||||
*/
|
||||
constructor(studentCode: string, dateOfBirth?: string) {
|
||||
super(API_BASE_STUDENT);
|
||||
this.studentCode = String(studentCode);
|
||||
this.dateOfBirth = String(dateOfBirth);
|
||||
}
|
||||
|
||||
/**
|
||||
* Authenticates with classcharts
|
||||
*/
|
||||
async login(): Promise<void> {
|
||||
if (!this.studentCode) throw new Error("Student Code not inputted");
|
||||
const formData = new URLSearchParams();
|
||||
formData.append("_method", "POST");
|
||||
formData.append("code", this.studentCode.toUpperCase());
|
||||
formData.append("dob", this.dateOfBirth);
|
||||
formData.append("remember_me", "1");
|
||||
formData.append("recaptcha-token", "no-token-avaliable");
|
||||
const request = await ky(BASE_URL + "/student/login", {
|
||||
method: "POST",
|
||||
body: formData,
|
||||
redirect: "manual",
|
||||
throwHttpErrors: false,
|
||||
credentials: undefined,
|
||||
});
|
||||
if (request.status != 302 || !request.headers.get("set-cookie")) {
|
||||
throw new Error(
|
||||
"Unauthenticated: Classcharts returned an error: " +
|
||||
request.status +
|
||||
" " +
|
||||
request.statusText
|
||||
);
|
||||
}
|
||||
const cookies = String(request.headers.get("set-cookie"));
|
||||
this.authCookies = cookies.split(",");
|
||||
const sessionCookies = parseCookies(cookies);
|
||||
const sessionID = JSON.parse(
|
||||
String(sessionCookies["student_session_credentials"])
|
||||
);
|
||||
this.sessionId = sessionID.session_id;
|
||||
await this.getNewSessionId();
|
||||
const user = await this.getStudentInfo();
|
||||
this.studentId = user.data.user.id;
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue