webtop-api-client

A TypeScript/JavaScript client library for the Webtop (webtop.co.il) API - Israel's educational platform.

Features

• ✅ No reCAPTCHA required - Uses the mobile API
• ✅ Full TypeScript support - Complete type definitions
• ✅ Works everywhere - Node.js, browsers, Deno
• ✅ All Webtop features - Grades, homework, messages, timetable, and more

Installation

npm install webtop-api-client
# or
yarn add webtop-api-client

Quick Start

import { WebtopMobileClient } from 'webtop-api-client';

const client = new WebtopMobileClient('username', 'password');

// Login
const result = await client.login();
if (!result.success) {
  console.error('Login failed:', result.error);
  process.exit(1);
}

console.log('Logged in! User type:', result.userType);

// Get today's lessons
const lessons = await client.getTodayLessons();
console.log('Lessons:', lessons);

// Get homework
const homework = await client.getHomework();
console.log('Homework:', homework);

// Get messages
const messages = await client.getInboxMessages();
console.log('Messages:', messages);

// Logout when done
await client.logout();

API Reference

Constructor

const client = new WebtopMobileClient(username: string, password: string, config?: {
  debug?: boolean;      // Enable debug logging
  fetch?: typeof fetch; // Custom fetch implementation (for proxies)
});

Authentication

// Login - returns { success: boolean, error?: string, userType?: number }
await client.login();

// Check if logged in
client.isLoggedIn; // boolean

// Get user type (1=student, 2=parent, 3=teacher, 4=admin)
client.getUserType();

// Logout
await client.logout();

Dashboard / Daily View

// Get today's lessons
const lessons = await client.getTodayLessons();
// Returns: Lesson[]

// Get today's events
const events = await client.getTodayEvents();
// Returns: Event[]

// Get combined dashboard data
const { lessons, events } = await client.getDashboard();

Homework

// Get all homework
const homework = await client.getHomework();
// Returns: HomeworkItem[]

// Get homework for date range
const homework = await client.getHomeworkByDate('2024-01-01', '2024-01-31');

Grades

// Get grades (parsed from HTML)
const grades = await client.getGrades();
// Returns: Grade[]

// Get raw grades HTML (for custom parsing)
const html = await client.getGradesHtml();

Timetable

// Get weekly timetable HTML
const timetable = await client.getWeeklyTimetable();

// Get timetable changes
const changes = await client.getTimetableChanges();
// Returns: TimetableChange[]

// Get timetable changes HTML
const changesHtml = await client.getTimetableChangesHtml();

Tests & Exams

// Get upcoming tests (parsed)
const tests = await client.getTests();
// Returns: Test[]

// Get raw tests HTML
const html = await client.getTestsHtml();

Messages

// Get inbox messages (parsed)
const messages = await client.getInboxMessages(page);
// Returns: Message[]

// Get inbox HTML
const html = await client.getInboxHtml(page);

// Get sent messages HTML
const sent = await client.getSentMessagesHtml(page);

// Get specific message
const message = await client.getMessage(messageId);

// Search messages
const results = await client.searchMessages('query', page);

Contacts / Phone Book

// Get contacts (parsed)
const contacts = await client.getContacts();
// Returns: Contact[]

// Get phone book HTML
const html = await client.getPhoneBookHtml();

// Search users
const users = await client.searchUsers('name');

Student Card / Profile

// Get student card HTML
const card = await client.getStudentCardHtml();

// Get behavior events
const behavior = await client.getBehaviorEvents();

// Get attendance
const attendance = await client.getAttendance();

Settings

// Get settings HTML
const settings = await client.getSettingsHtml();

// Update a setting
await client.updateSetting('key', 'value');

Advanced / Custom Requests

// Custom API call
const result = await client.callApi('actionName', { param: 'value' });

// Fetch any page
const html = await client.fetchPage('page.aspx?param=value');

Types

interface Lesson {
  hour: number;
  subject: string;
  teacher: string;
  room: string;
  startTime?: string;
  endTime?: string;
  changes?: string;
}

interface Event {
  title: string;
  description?: string;
  date?: string;
  type?: string;
}

interface HomeworkItem {
  subject: string;
  description: string;
  dueDate?: string;
  teacher?: string;
  completed?: boolean;
}

interface Grade {
  subject: string;
  grade: number | string;
  date?: string;
  type?: string;
  teacher?: string;
  weight?: number;
}

interface Test {
  subject: string;
  date: string;
  description?: string;
  room?: string;
}

interface Message {
  id: string;
  subject: string;
  sender: string;
  date: string;
  read: boolean;
  preview?: string;
}

interface TimetableChange {
  date: string;
  hour: number;
  originalSubject?: string;
  newSubject?: string;
  type: 'cancelled' | 'replacement' | 'room_change' | 'other';
  description?: string;
}

interface Contact {
  name: string;
  role?: string;
  phone?: string;
  email?: string;
}

interface LoginResult {
  success: boolean;
  error?: string;
  userType?: number;
  token?: string;
}

Using with a Proxy (for browsers)

When running in a browser on a different domain, you'll need a proxy to bypass CORS:

// Custom fetch that routes through your proxy
const proxyFetch = (url, options) => {
  return fetch('/api/proxy?url=' + encodeURIComponent(url), options);
};

const client = new WebtopMobileClient('username', 'password', {
  fetch: proxyFetch
});

Node.js SSL Issues

If you encounter SSL certificate errors in Node.js:

NODE_TLS_REJECT_UNAUTHORIZED=0 node your-script.js

Examples

React Example

import { useState, useEffect } from 'react';
import { WebtopMobileClient, Lesson, HomeworkItem } from 'webtop-api-client';

function App() {
  const [lessons, setLessons] = useState<Lesson[]>([]);
  const [homework, setHomework] = useState<HomeworkItem[]>([]);
  const [client] = useState(() => new WebtopMobileClient('user', 'pass'));

  useEffect(() => {
    async function load() {
      await client.login();
      setLessons(await client.getTodayLessons());
      setHomework(await client.getHomework());
    }
    load();
    return () => { client.logout(); };
  }, []);

  return (
    <div>
      <h1>Today's Lessons</h1>
      {lessons.map((l, i) => (
        <div key={i}>{l.subject} - {l.teacher}</div>
      ))}
      
      <h1>Homework</h1>
      {homework.map((h, i) => (
        <div key={i}>{h.subject}: {h.description}</div>
      ))}
    </div>
  );
}

Express API Example

import express from 'express';
import { WebtopMobileClient } from 'webtop-api-client';

const app = express();
const clients = new Map<string, WebtopMobileClient>();

app.post('/api/login', async (req, res) => {
  const { username, password } = req.body;
  const client = new WebtopMobileClient(username, password);
  const result = await client.login();
  
  if (result.success) {
    const sessionId = crypto.randomUUID();
    clients.set(sessionId, client);
    res.json({ sessionId, userType: result.userType });
  } else {
    res.status(401).json({ error: result.error });
  }
});

app.get('/api/lessons', async (req, res) => {
  const client = clients.get(req.headers['x-session-id'] as string);
  if (!client) return res.status(401).json({ error: 'Not logged in' });
  
  const lessons = await client.getTodayLessons();
  res.json(lessons);
});

app.listen(3000);

License

MIT