Shiara ArauzoDesign Engineer
← All work

Case study 008

Published to npm, source-available2026CLI

Book EsSalud appointments from the terminal.

A terminal tool to check your profile, find open slots, and book or cancel EsSalud medical appointments, built on the API behind EsSalud's booking portal. I built it alone and published it to npm.

Role
Design engineer, solo build
Problem
EsSalud, Peru's social health insurer, has no public API, and booking an appointment through its portal is slow and fragile.
Decision
Your token is stored on your machine with 600 permissions and only sent to EsSalud's API. Booking and cancelling are dry runs unless you pass --confirm.
Result
Version 0.1.0 is on npm and the source is public. Newer work is on main but not yet published.
TypeScriptNodePlaywright

Context

Where it came from

The EsSalud flow first lived inside tramites-pe, a WhatsApp bot project. At a quarter to one in the morning on June 21, 2026, I moved it into its own repo. At that point it had no tests, no lint, no CI, and no way for anyone else to install it. Two days later, version 0.1.0 was on npm.

Decision

Credentials stay on your machine

There is no public EsSalud API. In 0.1.0, login opens a temporary Playwright browser with a clean profile, reads the auth token from the network traffic, checks it, and saves it locally with 600 permissions. The CLI only sends it to EsSalud's API. Booking and cancelling are dry runs unless you pass --confirm.

Decision

Usable, then contributable, then worth reading

I wrote the plan as three layers and did them in order. Usable meant the token in its own folder with a migration from the old path, and every string in Peruvian Spanish. Contributable meant Biome, Vitest unit tests gating every pull request, a contributing guide, and Changesets. Worth reading meant no names or paths left over from the bot, confirmed by a written PASS from the review agent instead of my own opinion. Each layer went in as its own pull requests over June 21 and 22.

Build

Agents that check the work

The repo includes four agents I wrote for it. A quality reviewer opens one issue per finding and returns PASS or FAIL. A test writer adds unit tests. A release manager publishes through Changesets and does a dry run by default. An endpoint mapper rebuilds the map of EsSalud's API from a fresh HAR capture and opens a pull request with the diff. With no official API, the endpoint mapper is the one that matters most: when EsSalud changes its backend, the fix starts with a new capture.

Build

One command, two ways to use it

Run it with no arguments for an interactive menu, or pass subcommands for one-off use. A wrapper normalizes the API's odd response format and its empty-data cases. The end-to-end test books a real appointment and cancels it in a finally block, so it never leaves an appointment booked. If the cancel fails, the test says so instead of exiting quietly. It only runs when you set an environment variable for it.

Context

What broke

The reviewer caught bugs I had missed, including a flag the cancel command never registered and a cancel prompt that offered appointments that were already annulled. Getting the Spanish consistent took three passes, because voseo kept turning up in files I thought I had fixed. On the first publish attempt, npm 11 flagged the bin path because it started with ./, and the package would have shipped without the command. The pack check I had added the day before had not caught it, because packing a tarball is not the same as installing one. I fixed the path before 0.1.0 went out.

Result

Result

Version 0.1.0 has been on npm since June 23, 2026, and the source is public under a noncommercial license. In August EsSalud moved its portal behind a bot check, so I merged a login that imports a HAR file from your own browser, automatic session renewal, and a watch command that alerts you when a new slot opens. That work is on main but not released, and 0.1.0 is still the only version on npm.

← All work