@udondan/dsbmobile 1.1.0

package/dist/services/dsbmobile.js

@@ -0,0 +1,341 @@
+import axios from 'axios';
+import { DSB_API_BASE_URL, DSB_APP_VERSION, DSB_BUNDLE_ID, DSB_OS_VERSION, REQUEST_TIMEOUT_MS, } from '../constants.js';
+import { createAuthError, handleApiError } from '../utils/errors.js';
+/** Decode common HTML entities and trim whitespace. */
+function decodeHtmlEntities(s) {
+    return s
+        .replaceAll(' ', ' ')
+        .replaceAll('&', '&')
+        .replaceAll('&lt;', '<')
+        .replaceAll('&gt;', '>')
+        .replaceAll('&quot;', '"')
+        .trim();
+}
+/** Strip all HTML tags and trim whitespace. */
+function stripHtmlTags(s) {
+    return s.replaceAll(/<[^>]+>/g, '').trim();
+}
+/**
+ * Client for the DSBmobile Mobile API.
+ *
+ * Accepts explicit credentials via {@link DsbmobileConfig} and provides
+ * methods to fetch timetables, news, documents, and substitution plans.
+ *
+ * The authentication token is cached in memory for the session lifetime.
+ */
+export class DsbmobileClient {
+    username;
+    password;
+    http;
+    token;
+    constructor(config) {
+        this.username = config.username;
+        this.password = config.password;
+        this.http = axios.create({
+            baseURL: DSB_API_BASE_URL,
+            timeout: REQUEST_TIMEOUT_MS,
+            headers: {
+                Accept: 'application/json',
+                'User-Agent': `Dalvik/2.1.0 (Linux; U; Android 5.1; ${DSB_BUNDLE_ID})`,
+            },
+        });
+    }
+    /**
+     * Authenticates with DSBmobile and caches the token.
+     * The token is stable per username, so it can be cached indefinitely.
+     *
+     * @throws Error if credentials are invalid or the request fails
+     */
+    async authenticate() {
+        const response = await this.http.get('/authid', {
+            params: {
+                bundleid: DSB_BUNDLE_ID,
+                appversion: DSB_APP_VERSION,
+                osversion: DSB_OS_VERSION,
+                pushid: '',
+                user: this.username,
+                password: this.password,
+            },
+        });
+        // The API returns the token as a JSON string (with quotes), e.g. "uuid-here"
+        // An empty string "" means invalid credentials
+        const token = response.data;
+        if (!token || token === '""' || token === '') {
+            throw new Error(createAuthError());
+        }
+        // Remove surrounding quotes if present
+        this.token = token.replaceAll(/^"|"$/g, '');
+    }
+    /**
+     * Ensures a valid token is available, authenticating if necessary.
+     */
+    async ensureAuthenticated() {
+        if (!this.token) {
+            await this.authenticate();
+        }
+        return this.token;
+    }
+    /**
+     * Fetches all available substitution plan (Vertretungsplan) entries.
+     *
+     * @returns Array of timetable entries with URLs to HTML plan pages
+     * @throws Error if authentication fails or the request fails
+     */
+    async getTimetables() {
+        try {
+            const token = await this.ensureAuthenticated();
+            const response = await this.http.get('/dsbtimetables', {
+                params: { authid: token },
+            });
+            return this.parseTimetables(response.data);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.startsWith('Error:')) {
+                throw error;
+            }
+            throw new Error(handleApiError(error), { cause: error });
+        }
+    }
+    /**
+     * Fetches all news and announcements.
+     *
+     * @returns Array of news entries
+     * @throws Error if authentication fails or the request fails
+     */
+    async getNews() {
+        try {
+            const token = await this.ensureAuthenticated();
+            const response = await this.http.get('/newstab', {
+                params: { authid: token },
+            });
+            return this.parseNews(response.data);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.startsWith('Error:')) {
+                throw error;
+            }
+            throw new Error(handleApiError(error), { cause: error });
+        }
+    }
+    /**
+     * Fetches all available documents.
+     *
+     * @returns Array of document entries with download URLs
+     * @throws Error if authentication fails or the request fails
+     */
+    async getDocuments() {
+        try {
+            const token = await this.ensureAuthenticated();
+            const response = await this.http.get('/dsbdocuments', {
+                params: { authid: token },
+            });
+            return this.parseDocuments(response.data);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.startsWith('Error:')) {
+                throw error;
+            }
+            throw new Error(handleApiError(error), { cause: error });
+        }
+    }
+    /**
+     * Parses raw DSBmobile timetable items into structured TimetableEntry objects.
+     * Timetables have ConType=2 with children that contain the actual plan URLs.
+     * The parent item holds the descriptive title; children are individual pages.
+     */
+    parseTimetables(items) {
+        const entries = [];
+        for (const item of items) {
+            if (item.ConType === 2 && item.Childs && item.Childs.length > 0) {
+                const validChildren = item.Childs.filter((c) => c.Detail);
+                const multiPage = validChildren.length > 1;
+                // Each child represents a page of the plan
+                for (const [index, validChild] of validChildren.entries()) {
+                    const child = validChild;
+                    // Use the parent's descriptive title; append page number if multi-page
+                    const title = multiPage ? `${item.Title} (Seite ${index + 1})` : item.Title;
+                    const entry = {
+                        id: child.Id,
+                        title,
+                        date: item.Date,
+                        url: child.Detail,
+                    };
+                    if (child.Preview) {
+                        entry.previewUrl = `https://light.dsbcontrol.de/DSBlightWebsite/Data/${child.Preview}`;
+                    }
+                    entries.push(entry);
+                }
+            }
+            else if (item.Detail) {
+                // Direct URL in Detail field
+                const entry = {
+                    id: item.Id,
+                    title: item.Title,
+                    date: item.Date,
+                    url: item.Detail,
+                };
+                if (item.Preview) {
+                    entry.previewUrl = `https://light.dsbcontrol.de/DSBlightWebsite/Data/${item.Preview}`;
+                }
+                entries.push(entry);
+            }
+        }
+        return entries;
+    }
+    /**
+     * Parses raw DSBmobile news items into structured NewsEntry objects.
+     */
+    parseNews(items) {
+        const entries = [];
+        for (const item of items) {
+            entries.push({
+                id: item.Id,
+                title: item.Title,
+                detail: item.Detail,
+                date: item.Date,
+                tags: item.Tags,
+            });
+            // Also process nested children if present
+            if (item.Childs && item.Childs.length > 0) {
+                for (const child of item.Childs) {
+                    entries.push({
+                        id: child.Id,
+                        title: child.Title || item.Title,
+                        detail: child.Detail,
+                        date: child.Date || item.Date,
+                        tags: child.Tags || item.Tags,
+                    });
+                }
+            }
+        }
+        return entries;
+    }
+    /**
+     * Fetches and parses all substitution plan pages, returning structured entries.
+     * This fetches the actual HTML content of each timetable page and parses the
+     * substitution table into structured data.
+     *
+     * @returns Array of parsed substitution plans (one per HTML page)
+     * @throws Error if authentication fails or the request fails
+     */
+    async getSubstitutions() {
+        try {
+            const timetables = await this.getTimetables();
+            const plans = [];
+            for (const timetable of timetables) {
+                try {
+                    // Use a standalone axios call with the full URL (not the base-URL-bound instance)
+                    // responseType 'arraybuffer' lets us decode the latin-1 charset ourselves
+                    const response = await axios.get(timetable.url, {
+                        responseType: 'arraybuffer',
+                        timeout: REQUEST_TIMEOUT_MS,
+                    });
+                    // The HTML is encoded in iso-8859-1/windows-1252 — decode it properly
+                    const htmlText = new TextDecoder('windows-1252').decode(response.data);
+                    const plan = parseSubstitutionHtml(htmlText, timetable.title, timetable.date, timetable.url);
+                    plans.push(plan);
+                }
+                catch {
+                    // Skip pages that fail to load; don't abort the whole request
+                }
+            }
+            return plans;
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.startsWith('Error:')) {
+                throw error;
+            }
+            throw new Error(handleApiError(error), { cause: error });
+        }
+    }
+    /**
+     * Parses raw DSBmobile document items into structured DocumentEntry objects.
+     */
+    parseDocuments(items) {
+        const entries = [];
+        for (const item of items) {
+            if (item.ConType === 2 && item.Childs && item.Childs.length > 0) {
+                // Documents are often nested
+                for (const child of item.Childs) {
+                    if (child.Detail) {
+                        entries.push({
+                            id: child.Id,
+                            title: child.Title || item.Title,
+                            url: child.Detail,
+                            date: child.Date || item.Date,
+                        });
+                    }
+                }
+            }
+            else if (item.Detail) {
+                entries.push({
+                    id: item.Id,
+                    title: item.Title,
+                    url: item.Detail,
+                    date: item.Date,
+                });
+            }
+        }
+        return entries;
+    }
+}
+/**
+ * Parses the HTML content of a DSBmobile substitution plan page.
+ * The HTML is generated by Untis and has a consistent structure.
+ * Exported for unit testing.
+ */
+export function parseSubstitutionHtml(html, title, lastUpdated, url) {
+    // Extract plan date (e.g. "20.3.2026 Freitag (Seite 1 / 8)")
+    const dateMatch = /class="mon_title">(.*?)<\/div>/.exec(html);
+    const planDate = dateMatch ? decodeHtmlEntities(stripHtmlTags(dateMatch[1])) : '';
+    // Extract affected classes from info table
+    let affectedClasses = '';
+    const infoRows = html.matchAll(/<tr class="info"><td[^>]*>(.*?)<\/td><td[^>]*>(.*?)<\/td><\/tr>/gs);
+    for (const match of infoRows) {
+        const label = decodeHtmlEntities(stripHtmlTags(match[1]));
+        const value = decodeHtmlEntities(stripHtmlTags(match[2]));
+        if (label.toLowerCase().includes('klassen')) {
+            affectedClasses = value;
+        }
+    }
+    // Parse all table rows
+    const entries = [];
+    let currentClass = '';
+    const allRows = html.matchAll(/<tr[^>]*>(.*?)<\/tr>/gs);
+    for (const rowMatch of allRows) {
+        const rowHtml = rowMatch[1];
+        const cells = [...rowHtml.matchAll(/<t[dh][^>]*>(.*?)<\/t[dh]>/gs)].map((m) => decodeHtmlEntities(stripHtmlTags(m[1])));
+        if (cells.length === 0)
+            continue;
+        // Class header row: single cell with class name (e.g. "10a  10a" or just "10a")
+        if (cells.length === 1) {
+            currentClass = cells[0].split(/\s+/)[0] ?? '';
+            continue;
+        }
+        // Skip header row and info rows
+        if (cells.length < 5 || cells[0] === 'Art')
+            continue;
+        // Substitution row: Art | Stunde | Vertreter | Fach | Raum | Text
+        const [type = '', period = '', teacherField = '', subject = '', roomField = '', text = ''] = cells;
+        // Teacher field: "OriginalTeacher?SubstituteTeacher" or just "SubstituteTeacher"
+        const [originalTeacher = '', substituteTeacher = ''] = teacherField.includes('?')
+            ? teacherField.split('?')
+            : ['', teacherField];
+        // Room field: "OriginalRoom?SubstituteRoom" or just "SubstituteRoom"
+        const [originalRoom = '', substituteRoom = ''] = roomField.includes('?')
+            ? roomField.split('?')
+            : ['', roomField];
+        entries.push({
+            className: currentClass,
+            type,
+            period,
+            originalTeacher,
+            substituteTeacher,
+            subject,
+            originalRoom,
+            substituteRoom,
+            text: text === '\u00A0' ? '' : text,
+        });
+    }
+    return { title, planDate, lastUpdated, url, affectedClasses, entries };
+}

package/dist/tools/documents.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { DsbmobileClient } from '../services/dsbmobile.js';
+/**
+ * Registers the get_documents tool with the MCP server.
+ *
+ * This tool retrieves all documents and files available on DSBmobile.
+ */
+export declare function registerDocumentsTool(server: McpServer, client: DsbmobileClient): void;

package/dist/tools/documents.js

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import { CHARACTER_LIMIT } from '../constants.js';
+/**
+ * Registers the get_documents tool with the MCP server.
+ *
+ * This tool retrieves all documents and files available on DSBmobile.
+ */
+export function registerDocumentsTool(server, client) {
+    server.registerTool('get_documents', {
+        title: 'Get DSBmobile Documents',
+        description: `Retrieves all documents and files available on DSBmobile.
+
+Returns a list of document entries, each with:
+- id: Unique identifier for the document
+- title: Document name or title
+- url: Download URL for the document (typically a PDF or image)
+- date: Upload date in DD.MM.YYYY HH:MM format
+
+Use this tool when:
+- A user asks about school documents or files
+- A user wants to download a specific document
+- A user asks "Are there any documents on DSBmobile?"
+
+Returns "No documents available" if no documents are currently published.
+
+Error handling:
+- Returns an error message if authentication fails (check DSB_USERNAME and DSB_PASSWORD)
+- Returns an error message if the DSBmobile service is unavailable`,
+        inputSchema: z.object({}).strict(),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async () => {
+        try {
+            const entries = await client.getDocuments();
+            if (entries.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Aktuell sind keine Dokumente auf DSBmobile verfügbar.',
+                        },
+                    ],
+                };
+            }
+            const output = {
+                count: entries.length,
+                documents: entries,
+            };
+            const text = formatDocuments(entries);
+            const finalText = text.length > CHARACTER_LIMIT
+                ? text.slice(0, CHARACTER_LIMIT) + '\n\n[Response truncated due to length.]'
+                : text;
+            return {
+                content: [{ type: 'text', text: finalText }],
+                structuredContent: output,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'An unexpected error occurred.';
+            return {
+                content: [{ type: 'text', text: message }],
+                isError: true,
+            };
+        }
+    });
+}
+/**
+ * Formats document entries as human-readable markdown.
+ */
+function formatDocuments(entries) {
+    const lines = [`# DSBmobile Documents (${entries.length} available)`, ''];
+    for (const entry of entries) {
+        lines.push(`## ${entry.title}`, `- **ID**: ${entry.id}`, `- **Date**: ${entry.date}`, `- **Download URL**: ${entry.url}`, '');
+    }
+    return lines.join('\n');
+}

package/dist/tools/news.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { DsbmobileClient } from '../services/dsbmobile.js';
+/**
+ * Registers the get_news tool with the MCP server.
+ *
+ * This tool retrieves all news and announcements from DSBmobile.
+ */
+export declare function registerNewsTool(server: McpServer, client: DsbmobileClient): void;

package/dist/tools/news.js

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+import { CHARACTER_LIMIT } from '../constants.js';
+/**
+ * Registers the get_news tool with the MCP server.
+ *
+ * This tool retrieves all news and announcements from DSBmobile.
+ */
+export function registerNewsTool(server, client) {
+    server.registerTool('get_news', {
+        title: 'Get DSBmobile News and Announcements',
+        description: `Retrieves all news and announcements posted on DSBmobile.
+
+Returns a list of news items, each with:
+- id: Unique identifier for the news item
+- title: News headline or title
+- detail: News content, URL to more details, or plain text announcement
+- date: Publication date in DD.MM.YYYY HH:MM format
+- tags: Associated tags or categories (may be empty)
+
+Use this tool when:
+- A user asks about school announcements or news
+- A user wants to know about upcoming school events
+- A user asks "What's new at school?"
+
+Returns "No news available" if no news items are currently published.
+
+Error handling:
+- Returns an error message if authentication fails (check DSB_USERNAME and DSB_PASSWORD)
+- Returns an error message if the DSBmobile service is unavailable`,
+        inputSchema: z.object({}).strict(),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async () => {
+        try {
+            const entries = await client.getNews();
+            if (entries.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Aktuell sind keine Neuigkeiten auf DSBmobile verfügbar.',
+                        },
+                    ],
+                };
+            }
+            const output = {
+                count: entries.length,
+                news: entries,
+            };
+            const text = formatNews(entries);
+            const finalText = text.length > CHARACTER_LIMIT
+                ? text.slice(0, CHARACTER_LIMIT) + '\n\n[Response truncated due to length.]'
+                : text;
+            return {
+                content: [{ type: 'text', text: finalText }],
+                structuredContent: output,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'An unexpected error occurred.';
+            return {
+                content: [{ type: 'text', text: message }],
+                isError: true,
+            };
+        }
+    });
+}
+/**
+ * Formats news entries as human-readable markdown.
+ */
+function formatNews(entries) {
+    const lines = [`# DSBmobile News (${entries.length} items)`, ''];
+    for (const entry of entries) {
+        lines.push(`## ${entry.title}`, `- **ID**: ${entry.id}`, `- **Date**: ${entry.date}`);
+        if (entry.tags) {
+            lines.push(`- **Tags**: ${entry.tags}`);
+        }
+        if (entry.detail) {
+            lines.push(`- **Content**: ${entry.detail}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}

package/dist/tools/substitutions.d.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { DsbmobileClient } from '../services/dsbmobile.js';
+/**
+ * Registers the get_substitutions tool with the MCP server.
+ *
+ * This tool fetches and parses the actual substitution plan HTML pages,
+ * returning structured substitution entries grouped by class.
+ */
+export declare function registerSubstitutionsTool(server: McpServer, client: DsbmobileClient): void;