@cloud-000/school-api

A modern, fast, zero-dependency TypeScript SDK for interacting with StudentVUE and Schoology APIs. Designed to run seamlessly in Bun, Node.js, and other modern JavaScript runtimes.

Features

• ⚡ Zero Dependencies: Built entirely using modern native Web APIs (like fetch) and built-in Node modules (node:crypto). No heavy external HTTP clients or OAuth libraries.
• 🗺️ Built-in District Finder: Search for StudentVUE district portal URLs directly by zip code.
• 🎓 StudentVUE Client:
  • Full SOAP/XML communication under the hood with a custom, lightweight XML-to-JSON parser.
  • Strongly typed methods for accessing Student Info, Gradebook, Attendance, Class Schedules, Documents, Report Cards (PDFs), Messages, and School Contact Info.
  • Built-in support for parent accounts (ParentVUE).
• 📝 Schoology Client:
  • Complete, from-scratch RFC 3986-compliant OAuth 1.0a authorization signing (HMAC-SHA1 and PLAINTEXT).
  • Handles Schoology API redirects internally (including signing the redirected requests with correct OAuth headers).
  • Fetch user profiles, courses, sections, assignments, grades, calendar events, updates, and submissions.
• 🧬 Fully Typed: Includes full TypeScript interfaces for all data structures returned by both platforms.

Installation

Install using Bun (recommended):

bun add @cloud-000/school-api

Or using standard package managers:

npm install @cloud-000/school-api
yarn add @cloud-000/school-api
pnpm add @cloud-000/school-api

Quick Start

1. StudentVUE API Client

import { StudentVueClient, findDistricts } from "@cloud-000/school-api";

// Optional: Find the district URL by Zip Code
const districts = await findDistricts("94127");
console.log(`Found district: ${districts[0].name} at ${districts[0].url}`);

// Initialize the client
const client = new StudentVueClient(
    "https://portal.sfusd.edu", // District portal URL
    "student_id_123", // Student/Parent Username
    "secret_password", // Password
    false, // isParent (set to true for ParentVUE)
);

// Validate credentials
const isValid = await client.validate();
if (isValid) {
    // Fetch basic profile info
    const info = await client.getStudentInfo();
    console.log(`Hello, ${info.name}!`);

    // Fetch gradebook
    const gradebook = await client.getGradebook();
    for (const course of gradebook.courses) {
        console.log(`${course.courseTitle}: ${course.mark} (${course.score}%)`);
    }

    // Fetch attendance
    const attendance = await client.getAttendance();
    console.log(
        `Days Absent: ${attendance.daysAbsent}, Days Tardy: ${attendance.daysTardy}`,
    );
}

2. Schoology API Client (2-Legged OAuth)

import { SchoologyClient } from "@cloud-000/school-api";

// Initialize the Schoology client
const client = new SchoologyClient(
    "your_consumer_key",
    "your_consumer_secret",
    {
        // Optional: District API Host (defaults to https://api.schoology.com/v1)
        apiHost: "https://api.schoology.com/v1",
        signatureMethod: "HMAC-SHA1", // or "PLAINTEXT"
    },
);

// Fetch your own profile
const me = await client.getSelf();
console.log(`Logged in as: ${me.name_display} (${me.primary_email})`);

// Fetch your course sections
const sectionsResult = await client.getUserSections(me.id);
for (const section of sectionsResult.section) {
    console.log(
        `Course: ${section.course_title} - Section: ${section.section_title} [ID: ${section.id}]`,
    );

    // Get assignments for this section
    const assignmentsResult = await client.getAssignments(section.id);
    console.log(`Assignments for ${section.course_title}:`);
    for (const assignment of assignmentsResult.assignment) {
        console.log(
            `- ${assignment.title} (Max points: ${assignment.max_points}, Due: ${assignment.due})`,
        );
    }
}

Interactive Sandbox

This repository includes a full-featured command-line sandbox to test authentication and fetch data in real-time.

To run the sandbox:

bun run sandbox

It will prompt you to:

1. Find districts by Zip Code.
2. Log in to StudentVUE and query schedules, grades, attendance, report cards, and documents.
3. Log in to Schoology and inspect courses, assignments, updates, and calendar events.
4. Run the XML Parser self-test.

API Reference

StudentVUE API (StudentVueClient)

| Method | Return Type | Description | | :------------------------------- | :--------------------------- | :----------------------------------------------------------------- | | findDistricts(zipCode) | Promise<DistrictInfo[]> | Static. Looks up District URLs and names by zip code. | | validate() | Promise<boolean> | Tests credentials by executing getStudentInfo. | | getStudentInfo() | Promise<StudentInfo> | Gets general student details (name, email, school, grade level). | | getGradebook(termIndex?) | Promise<Gradebook> | Retrieves course grades and individual assignment scores. | | getAttendance() | Promise<Attendance> | Fetes summary of absences/tardies and detailed historical records. | | getSchedule(termIndex?) | Promise<ClassSchedule> | Retrieves periods, teachers, room names, and teacher emails. | | getSchoolInfo() | Promise<SchoolInfo> | Retrieves school contact details and full staff directory. | | getDocuments() | Promise<StudentDocument[]> | Lists school documents uploaded for the student. | | getReportCards() | Promise<ReportCard[]> | Lists available PDF report cards. | | downloadDocument(documentGU) | Promise<string> | Downloads document content as a Base64-encoded string. | | downloadReportCard(documentGU) | Promise<string> | Downloads report card PDF content as a Base64-encoded string. | | getMessages() | Promise<Message[]> | Queries StudentVUE/ParentVUE mailbox messages. |

Schoology API (SchoologyClient)

| Method | Return Type | Description | | :------------------------------------------------------------ | :----------------------------------------------- | :--------------------------------------------------------------------- | | getSelf() | Promise<SchoologyUser> | Retrieves the profile of the current authenticated user (/users/me). | | getUser(userId) | Promise<SchoologyUser> | Retrieves profile of a specific user. | | getCourses(options?) | Promise<{ course: SchoologyCourse[] }> | Lists courses accessible by the authenticated user. | | getCourseSections(courseId) | Promise<{ section: SchoologySection[] }> | Lists sections under a specific course. | | getUserSections(userId) | Promise<{ section: SchoologySection[] }> | Lists section enrollments for a specific user. | | getAssignments(sectionId) | Promise<{ assignment: SchoologyAssignment[] }> | Fetches all assignments for a section. | | getSectionGrades(sectionId, enrollmentId?) | Promise<any> | Retrieves grades for a course section. | | getUserGrades(userId, options?) | Promise<any> | Gets user grades across all sections, optionally filtering by section. | | getSectionUpdates(sectionId, options?) | Promise<{ update: SchoologyUpdate[] }> | Lists updates (announcements/posts) for a section. | | getSectionEvents(sectionId, options?) | Promise<{ event: SchoologyEvent[] }> | Lists calendar events for a section. | | getAssignmentSubmissions(sectionId, assignmentId, options?) | Promise<{ submission: SchoologySubmission[] }> | Gets student submissions for a specific assignment. |

Development

Clone the repository and install dependencies:

bun install

Build

Compile the project and generate TypeScript declarations (dist/ directory):

bun run build

License

MIT