TimetableKit
Menu

Guide

Read a timetable, review its warnings, and export the result.

Start here

Install the core with npm install @ndycode/timetablekit. Pass it timetable text or CSV, and provide the timetable's locale and timezone. Add term dates when the input gives weekdays without exact dates. The parser runs in your process and needs no account, database, or model key.

This guide describes the current repository source. Published versions can differ. See the source setup when you need the current implementation.

import {
  analyzeTimetableResult,
  parseTimetable,
  toJSON,
} from "@ndycode/timetablekit"

const rawTimetable = "Synthetic Biology; Monday; 09:00-10:00"

const result = await parseTimetable(
  { kind: "text", text: rawTimetable },
  {
    locale: "en-PH",
    timezone: "Asia/Manila",
    term: { startsOn: "2026-08-17", endsOn: "2026-12-18" },
  },
)

const review = analyzeTimetableResult(result)
if (review.assessment.status === "unusable") {
  throw new Error(review.assessment.reasons.join(", "))
}

const normalized = toJSON(result)

Use kind: "csv" for CSV input. Exporters return strings. Your application decides whether to display or download them.

How it works

TimetableKit separates input reading from timetable parsing. The core parser validates the input, finds event fields, normalizes them, and returns events with warnings. It does not silently invent a date, title, or time when the input is unclear.

  1. Validate the input, options, and resource limits.
  2. Read text directly or use a provider for a binary file.
  3. Recognize titles, codes, days, dates, times, and details.
  4. Normalize events and keep source evidence when requested.
  5. Check dates, times, timezones, duplicates, and conflicts.
  6. Review the result before you create a calendar file.

Use onProgress to show stage updates andsignal to stop a parse. A provider failure leaves a structured warning and the deterministic result when possible.

Result format

Every result uses schema version 1.0. It contains the source descriptor, locale, timezone, optional term, events, warnings, conflicts, and parse metadata. Dates useYYYY-MM-DD. Times use HH:mm. Weekdays use the two-letter RFC 5545 codes MO throughSU. Timezones use IANA names such asAsia/Manila.

An event has a title, schedule, start time, end time, timezone, confidence, and optional details such as a course code, room, instructor, or notes. A schedule is either weekly or exact-date. Field confidence and source evidence help a review interface show which values need attention.

The result assessment is derived from the result. It is not part of the versioned result or export. UseanalyzeTimetableResult when a review screen needs both canonical warnings and the assessment in one bounded pass. Use assessTimetableResult when you only need the status.

Validate integrations against the public timetable result JSON Schema. The same schema is available from the core package.

Agent integrations

The @ndycode/timetablekit-agent package exposes the core parser as the timetablekit.parse tool. It uses plain objects, JSON Schema, structured errors, capability discovery, and cancellation. It does not require an agent SDK.

import { createTimetableAgentTool } from "@ndycode/timetablekit-agent"

const tool = createTimetableAgentTool()
const response = await tool.invoke({
  schemaVersion: "1",
  input: { kind: "text", text: rawTimetable },
})

if (!response.ok) {
  throw new Error(response.error.message)
}

if (response.assessment.status === "unusable") {
  throw new Error(response.assessment.reasons.join(", "))
}

The default agent tool accepts text and CSV. A host must inject a parser and declare its supported input kinds before it can accept bounded base64 image or PDF input. Thetimetablekit agent command reads one JSON request per line and writes one JSON response per line. It does not read paths or fetch URLs.

Remote recovery is disabled by default. A host needs a recovery provider, allowRemoteRecovery: true, and request options with options.recovery.enabled andoptions.recovery.consent set to true. The provider receives only bounded, unresolved fields. Treat the returned result as review input and validate it against the public schemas.

A successful response exposes the parsed data atresponse.result. A failed response hasok: false and a structuredresponse.error value. The agent package exportstimetableAgentOutputJsonSchema for the complete response wrapper.

Read the agent integration guide for request, response, and capability schemas.

File readers

The core package reads text and CSV. It does not import browser APIs, PDF.js, OCR libraries, React, or network clients. Optional providers add those boundaries without changing the core parser.

  • The browser image reader uses the local Tesseract provider for PNG, JPEG, and WebP input.
  • The browser PDF reader extracts PDF text and can hand text-free pages to an injected OCR provider.
  • A recovery provider can suggest unresolved field values after the host obtains consent. It does not replace local parsing.

Providers receive size limits, an abort signal, and a progress callback. They must validate their output and clean up their resources. The public playground uses local readers and has no remote recovery provider configured.

Export a schedule

Use toJSON, toCSV, ortoICS after review. The exporters reject an empty or unusable result, including results with error-severity warnings or unresolved conflicts. Fix the result with the typed correction API, then assess it again.

JSON preserves the normalized result. CSV writes one row per event. iCalendar writes exact-date events directly and weekly events as weekly recurrences. A weekly event needs a concrete start and end date from its schedule or term. If the range is missing, toICS reports an error instead of guessing.

Timezone-aware iCalendar output uses IANA timezone identifiers and does not embed VTIMEZONE definitions. Check the export notes in the repository before you promise compatibility with a calendar client.

Open the playground to inspect a synthetic result and download each format.

Limits and review

The default core limits are 2 MB of input, 25 million image pixels, 100 PDF pages, 30 seconds of processing time, and 5 MB of provider output. Each core export also has a 5 MB UTF-8 safety limit. Apps can set their own limits.

Date ranges expand to at most 366 generated dates per row or CSV date field. Invalid dates, reversed ranges, and sections outside a supplied term produce errors or warnings that need review. Ambiguous weekly labels need more information before the parser can assign dates.

A nonempty result can still be wrong. Show warnings, conflicts, confidence, and source evidence to the person who owns the schedule. Use synthetic or redacted data in tests, screenshots, issue reports, and examples. See the privacy model in the repository and the security page for data-handling rules.