This paper introduces damn-my-slow-kt, an automated command-line interface (CLI) tool designed to monitor internet speeds provided by KT (Korea Telecom), detect violations of the Service Level Agreement (SLA), and automatically initiate compensation claims for subscribers. The primary problem addressed is the manual and cumbersome process required for KT internet users to claim daily fee reductions when their actual speed falls below the guaranteed minimum. This manual process typically involves logging into the KT website, waiting for a speed test, and manually filing an objection, which is prohibitive for daily claims required for full monthly compensation.

The core methodology of damn-my-slow-kt hinges on leveraging KT's official speed measurement program and its specific SLA criteria. The tool automates the process of:

1. Speed Measurement Execution: It orchestrates the execution of KT's proprietary speed measurement program (a standalone application for macOS or a web-based test via speed.kt.com for Windows) to accurately measure the current internet speed against KT's official speed testing servers.
2. SLA Violation Assessment: According to KT's Quality Assurance System (SLA), a speed violation leading to compensation is triggered if, within a 30-minute period, at least 60% of 5 consecutive speed measurements fall below the stipulated minimum guaranteed speed. Formally, if $N_{total} = 5$ measurements are taken within 30 minutes, and $N_{fail}$ measurements fall below the minimum guaranteed speed, compensation is due if $N_{fail} \ge \lceil 0.6 \times N_{total} \rceil = 3$.
3. Compensation Claim Automation: Upon detecting an SLA violation, the tool automates the submission of a compensation claim to KT, leveraging browser automation capabilities.
4. Daily Scheduling and Optimization: The tool is designed to run automatically on a predefined schedule (e.g., up to 10 times daily at 2-hour intervals). If an SLA violation is confirmed and a compensation claim is successfully filed for a given day, subsequent measurements and claims for that day are automatically skipped to prevent redundant actions.

Technical Details and Implementation:

• Platform Dependency: The tool's critical dependency is the KT official speed measurement program, which currently supports macOS (ktspeed.pkg) and Windows (speed.kt.com). This reliance makes the tool incompatible with Linux-based environments (including Docker and NAS setups) for actual speed measurement, despite the core CLI logic being portable.
• Technology Stack:
  • Language: TypeScript (ES2020)
  • CLI Framework: Commander for command-line parsing, Inquirer for interactive prompts, and Chalk for terminal styling.
  • Browser Automation: Playwright (headless Chromium) is utilized to simulate user interactions on KT's web portal for login, navigation, and compensation claim submission.
  • Configuration: User settings, including KT account credentials, measurement schedule parameters (e.g., max_attempts and retry_interval_minutes), and optional notification webhooks (Discord, Telegram), are stored in a YAML file (~/.damn-my-slow-isp/config-kt.yaml).
  • Data Storage: Internal state, such as daily compensation status, is persisted using node:sqlite (for Node.js 22+ environments) or a JSON file fallback.
  • Scheduling: While the tool itself provides schedule install and schedule remove commands, these actions typically configure system-level scheduling mechanisms like cron for automated, recurring execution.
• SLA Criteria and Compensation:
  • Minimum Guaranteed Speeds: KT's SLA defines minimum speeds based on the subscribed plan (e.g., 1000 Mbps contract speed has a 500 Mbps minimum guarantee). These are specified in KT's Terms of Service, Appendix 2.
  • Compensation Scope: Each successful claim results in the fee reduction for that specific day's service.
  • Termination Rights: If a subscriber receives compensation for 5 or more days within a month, they gain the right to terminate their contract without incurring early termination fees (discount refund fees).
  • Connection Type: The SLA specifically applies only to wired (LAN) connections, excluding Wi-Fi.

Usage Workflow:

5. Initial Setup: Install the KT official speed measurement program manually.
6. Tool Initialization: Run npx -y damn-my-slow-kt@latest init to configure the tool, including providing KT account credentials.
7. Schedule Installation: Execute npx -y damn-my-slow-kt@latest schedule install to set up automatic daily measurements and claim processes.
8. Updates: The init command also handles updates, automatically prompting for configuration changes with new versions.

The project emphasizes ease of use for the end-user while providing robust automation based on specific contractual obligations, aiming to democratize access to guaranteed service quality for KT internet subscribers.