aimharder-mcp 0.1.0

package/CONTEXT.md

@@ -0,0 +1,33 @@
+# AimHarder domain
+
+AimHarder organizes scheduled classes, workout content, personal bookings, and personal activity at a gym. These concepts remain distinct even when they refer to the same training day.
+
+## Language
+
+**Class type**:
+A category of class, such as WOD, Metcon, or Open Box.
+_Avoid_: Workout when referring to a class category.
+
+**Class session**:
+A specific scheduled class at a gym on a particular date and time.
+_Avoid_: Workout or booking when referring to the scheduled class itself.
+
+**Workout**:
+The prescribed training content, which may be shared by multiple class sessions. A workout published in a gym feed does not necessarily belong to one unique session.
+_Avoid_: Class session when referring to training instructions.
+
+**Booking**:
+The account holder's reservation for a class session. A booking does not establish attendance.
+_Avoid_: Attendance or completed workout as synonyms for a booking.
+
+**Activity entry**:
+A distinct record of the account holder's personal activity. Several entries on the same date remain separate entries, even when their content is similar. An entry does not by itself establish a booking or verified attendance.
+_Avoid_: Booking or attendance as synonyms for an activity record.
+
+**Training session**:
+A distinct occurrence of personal training. Several activity entries may describe one training session; grouping requires evidence beyond a shared date or similar content.
+_Avoid_: Treating every activity entry, active day, or booking as one verified training session.
+
+**Day with activity**:
+A gym-local calendar date with at least one personal activity entry. It does not state how many distinct training sessions occurred that day.
+_Avoid_: Session count or attendance count when describing days with activity.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rude
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# aimharder-mcp
+
+Ask about your AimHarder classes, workouts, bookings and activity from a desktop AI client. This is a local, read-only [MCP server](https://modelcontextprotocol.io/) and an independent project, neither affiliated with nor endorsed by AimHarder.
+
+**Release status:** `aimharder-mcp@0.1.0` is not on npm yet. The `npx` example below will work after publication. A [local package archive has been tested](https://github.com/rudeayelo/aimharder-mcp/blob/main/docs/validation.md).
+
+**Data limits:** Live checks used one account at one location (9NBC). Other gyms may differ. Workout and booking views can be incomplete, so an empty result may not mean there is nothing to show. [Details](docs/tools.md#coverage-and-interpretation)
+
+## Get started
+
+1. Install Node.js **24 or newer**.
+2. Supply `AIMHARDER_USERNAME` and `AIMHARDER_PASSWORD` to the server process through your client or a secrets manager. Keep them out of shared configuration. The server assumes `Europe/Madrid` unless you [configure your gym's time zone](docs/configuration.md).
+3. Add a local stdio server to your client. This generic JSON example assumes the client passes the required environment variables:
+
+   ```json
+   {
+     "mcpServers": {
+       "aimharder": {
+         "command": "npx",
+         "args": ["--yes", "aimharder-mcp@0.1.0"]
+       }
+     }
+   }
+   ```
+
+4. Ask your client an AimHarder question, such as “What is tomorrow's WOD?” The first valid tool call signs in. See the guide for your client below for its configuration format and credential options.
+
+## Desktop clients
+
+- [ChatGPT desktop](docs/clients/chatgpt-desktop.md)
+- [Claude Desktop](docs/clients/claude-desktop.md)
+- [Hermes](docs/clients/hermes.md)
+- [OpenClaw](docs/clients/openclaw.md)
+
+Hermes has been tested with a local package archive. The ChatGPT desktop STDIO form has been observed; package connections in ChatGPT, Claude Desktop and OpenClaw have not been verified. Mobile apps are outside the current setup guides.
+
+## Tools
+
+| Tool | Example question |
+| --- | --- |
+| `get_account_context` | Which gyms can I query? |
+| `get_class_sessions` | What classes are available this week? |
+| `get_published_workouts` | What is tomorrow's WOD? |
+| `get_upcoming_bookings` | When am I booked? |
+| `get_booking_history` | Which past bookings are available? |
+| `get_personal_activity` | What activity did I record this month? |
+
+Clients can combine tools for questions about workouts and bookings, or count recent **activity entries**. An activity entry does not establish attendance or one distinct training session. See [tool inputs and coverage](docs/tools.md).
+
+## Roadmap
+
+Planned capabilities, without committed dates or versions:
+
+- [ ] Create and cancel bookings.
+- [ ] Look up personal exercise RMs and show calculated loads alongside the original `%RM` prescription in future activities.
+- [ ] Record activity results.
+- [ ] Expand compatibility to more AimHarder gyms.
+- [ ] Explore compatibility with mobile apps.
+
+## Contributing
+
+Report bugs or propose changes in [GitHub Issues](https://github.com/rudeayelo/aimharder-mcp/issues). Keep credentials and private activity out of reports. See the [development guide](https://github.com/rudeayelo/aimharder-mcp/blob/main/docs/development.md) to contribute code.
+
+## License
+
+[MIT](LICENSE).

package/dist/activity-consumer-contracts.js

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import { activityCoverageSchema, activityEntrySchema } from './activity.js';
+import { calendarDates, dateSchema } from './classes.js';
+import { gymIdSchema } from './config.js';
+export const gymSchema = z.object({ id: gymIdSchema, name: z.string(), timeZone: z.string().nullable(), timeZoneStatus: z.enum(['assumed', 'user-confirmed']) });
+export const activityResponseSchema = z.object({ gym: gymSchema, startDate: dateSchema, endDate: dateSchema, entries: z.array(activityEntrySchema), coverage: activityCoverageSchema, notices: z.array(z.string()) });
+/** Reject responses that cannot establish the requested gym/date coverage. */
+export function validateActivityResponse(value, gym, startDate, endDate) {
+    const data = activityResponseSchema.parse(value);
+    const dates = [...calendarDates(startDate, endDate)];
+    if (data.gym.id !== gym.id || data.gym.timeZone !== gym.timeZone || data.gym.timeZoneStatus !== gym.timeZoneStatus
+        || data.startDate !== startDate || data.endDate !== endDate
+        || data.entries.some(entry => !dates.includes(entry.date) || entry.timeZone !== gym.timeZone)
+        || data.coverage.completedDates.some(date => !dates.includes(date))
+        || new Set(data.coverage.completedDates).size !== data.coverage.completedDates.length
+        || (data.coverage.status === 'complete' && data.coverage.completedDates.length !== dates.length))
+        throw new Error('Activity response scope or coverage could not be confirmed.');
+    return data;
+}

package/dist/activity-period-consumer.js

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import { gymSchema, validateActivityResponse } from './activity-consumer-contracts.js';
+import { dateSchema } from './classes.js';
+import { gymIdSchema } from './config.js';
+const options = { gymId: gymIdSchema.optional(), maxWindows: z.number().int().min(1).max(12).default(12) };
+const inputSchema = z.union([
+    z.object({ period: z.literal('previous-month'), ...options }).strict(),
+    z.object({ startDate: dateSchema, endDate: dateSchema, ...options }).strict()
+        .refine(query => query.startDate <= query.endDate, { message: 'startDate must be on or before endDate.' }),
+]);
+function shiftDate(date, days) {
+    const value = new Date(`${date}T12:00:00Z`);
+    value.setUTCDate(value.getUTCDate() + days);
+    return dateSchema.parse(value.toISOString().slice(0, 10));
+}
+export async function queryActivityPeriod(client, input, now = new Date()) {
+    const query = inputSchema.parse(input);
+    let gym;
+    try {
+        const result = await client.callTool({ name: 'get_account_context', arguments: query.gymId ? { gymId: query.gymId } : {} });
+        if (result.isError)
+            throw new Error();
+        gym = z.object({ selectedGym: gymSchema }).parse(result.structuredContent).selectedGym;
+        if ((query.gymId && gym.id !== query.gymId) || !gym.timeZone)
+            throw new Error();
+    }
+    catch {
+        throw new Error('The selected gym and its time zone could not be established.');
+    }
+    let startDate;
+    let endDate;
+    if ('period' in query) {
+        const parts = new Intl.DateTimeFormat('en-US', { timeZone: gym.timeZone, year: 'numeric', month: '2-digit' }).formatToParts(now);
+        const year = parts.find(part => part.type === 'year').value.padStart(4, '0');
+        const month = parts.find(part => part.type === 'month').value;
+        endDate = shiftDate(dateSchema.parse(`${year}-${month}-01`), -1);
+        startDate = `${endDate.slice(0, 7)}-01`;
+    }
+    else {
+        startDate = query.startDate;
+        endDate = query.endDate;
+    }
+    const entries = new Map();
+    const completedDates = new Set();
+    const windows = [];
+    let coverage = 'incomplete';
+    let cursor = startDate;
+    for (let index = 0; index < query.maxWindows; index++) {
+        // Bound the addition before shifting, including at the maximum supported year.
+        const remainingDays = (Date.parse(`${endDate}T12:00:00Z`) - Date.parse(`${cursor}T12:00:00Z`)) / 86_400_000;
+        const windowEnd = shiftDate(cursor, Math.min(30, remainingDays));
+        try {
+            const result = await client.callTool({ name: 'get_personal_activity', arguments: { startDate: cursor, endDate: windowEnd, gymId: gym.id } });
+            if (result.isError)
+                throw new Error();
+            const data = validateActivityResponse(result.structuredContent, gym, cursor, windowEnd);
+            const recovered = new Map(entries);
+            for (const entry of data.entries) {
+                const prior = recovered.get(entry.sourceActivityId);
+                if (prior && JSON.stringify(prior) !== JSON.stringify(entry))
+                    throw new Error();
+                recovered.set(entry.sourceActivityId, entry);
+            }
+            for (const [id, entry] of recovered)
+                entries.set(id, entry);
+            for (const date of data.coverage.completedDates)
+                completedDates.add(date);
+            windows.push({ startDate: cursor, endDate: windowEnd, status: data.coverage.status, completedDates: data.coverage.completedDates, notices: [...data.notices, ...(data.coverage.reason ? [data.coverage.reason] : [])] });
+            if (data.coverage.status !== 'complete')
+                break;
+            if (windowEnd === endDate) {
+                coverage = 'complete';
+                break;
+            }
+        }
+        catch {
+            windows.push({ startDate: cursor, endDate: windowEnd, status: 'error', completedDates: [], notices: ['Activity retrieval could not be confirmed; exact period counts are unavailable.'] });
+            break;
+        }
+        cursor = shiftDate(windowEnd, 1);
+    }
+    const observedEntries = [...entries.values()].sort((a, b) => b.date.localeCompare(a.date) || a.sourceActivityId - b.sourceActivityId);
+    const observedDays = new Set(observedEntries.map(entry => entry.date)).size;
+    return {
+        gym, startDate, endDate, coverage, completedDates: [...completedDates].sort(), windows, maxWindows: query.maxWindows,
+        basis: 'activity-entries',
+        counts: {
+            activityEntries: { observed: entries.size, exact: coverage === 'complete' ? entries.size : null },
+            daysWithActivity: { observed: observedDays, exact: coverage === 'complete' ? observedDays : null },
+            interpretation: coverage === 'complete' ? 'exact-for-available-calendar-records' : 'recovered-lower-bound',
+        },
+        entries: observedEntries,
+        notices: ['Frequency counts distinct activity entries. Days with activity are supplementary; neither measure establishes class attendance.',
+            'Coverage describes available calendar records and is not an atomic snapshot or proof of attendance.',
+            ...(coverage === 'incomplete' ? ['The period is incomplete because retrieval failed, returned incomplete coverage, or reached the configured window limit. Observed counts are recovered lower bounds; exact totals are unavailable.'] : [])],
+    };
+}

package/dist/activity.js

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { dateSchema } from './classes.js';
+import { gymIdSchema } from './config.js';
+import { AimHarderError } from './errors.js';
+import { parseWorkout, workoutSchema } from './workouts.js';
+export const activityQuerySchema = z.object({ startDate: dateSchema, endDate: dateSchema, gymId: gymIdSchema.optional() }).strict()
+    .refine(q => q.startDate <= q.endDate && (Date.parse(`${q.endDate}T00:00:00Z`) - Date.parse(`${q.startDate}T00:00:00Z`)) / 86_400_000 < 31, { message: 'Supply an inclusive interval of 1 to 31 consecutive calendar dates.' });
+// Preserve source result names. The user confirmed that time is measured in seconds.
+const resultNumber = z.number().finite().nullable().optional();
+const activityResultSchema = z.object({
+    res: resultNumber, reps: resultNumber, time: resultNumber.describe('Recorded time in seconds; unit confirmed by the user.'), rondas: resultNumber,
+    desc: z.string().max(100_000).nullable().optional().describe('Original result description for this activity and block; format is not universal across gyms.'),
+    rx: z.boolean().nullable().optional(), rxstr: z.string().max(100_000).nullable().optional(),
+});
+const resultDetailSchema = z.object({ TIPOWODs: z.array(z.unknown()), chartData: z.unknown().optional() });
+const chartRowSchema = z.object({ idAction: z.number().int().positive().safe(), desc: z.string().max(100_000).nullable().optional() });
+function resultDescription(chartData, source, activityId) {
+    if (chartData == null)
+        return {};
+    const chart = z.record(z.string(), z.unknown()).safeParse(chartData);
+    const block = z.object({ id: z.number().int().positive().safe().optional() }).safeParse(source);
+    if (!chart.success || !block.success)
+        throw new AimHarderError('INVALID_ACTIVITY_RESPONSE');
+    if (block.data.id === undefined)
+        return {};
+    const rows = chart.data[String(block.data.id)];
+    if (rows === undefined)
+        return {};
+    if (!Array.isArray(rows))
+        throw new AimHarderError('INVALID_ACTIVITY_RESPONSE');
+    const descriptions = [];
+    for (const row of rows) {
+        if (typeof row !== 'object' || row === null || row.idAction !== activityId)
+            continue;
+        const parsed = chartRowSchema.safeParse(row);
+        if (!parsed.success)
+            throw new AimHarderError('INVALID_ACTIVITY_RESPONSE');
+        descriptions.push(parsed.data.desc);
+    }
+    if (new Set(descriptions).size > 1)
+        throw new AimHarderError('INVALID_ACTIVITY_RESPONSE');
+    return descriptions.length && descriptions[0] !== undefined ? { desc: descriptions[0] } : {};
+}
+export const activityEntrySchema = workoutSchema.pick({ titles: true, blocks: true, exercises: true }).extend({
+    blocks: z.array(workoutSchema.shape.blocks.element.extend({ result: activityResultSchema.optional() })),
+    sourceActivityId: z.number().int().positive().safe(), date: dateSchema, timeZone: z.string(), startTime: z.null(), trainingSessionId: z.null(),
+});
+export const activityCoverageSchema = z.object({ status: z.enum(['complete', 'incomplete']), scope: z.literal('account-activity-calendar'), completedDates: z.array(dateSchema), reason: z.string().nullable() });
+const ratesSchema = z.object({ ids: z.array(z.number().int().positive().safe()).max(500), colors: z.array(z.string().nullable()).optional() })
+    .catchall(z.array(z.unknown()))
+    .refine(row => Object.keys(row).every(key => key === 'ids' || key === 'colors' || /^[1-9]\d*$/.test(key)));
+const calendarSchema = z.object({ workouts: z.union([z.array(z.never()), z.record(dateSchema, z.object({ rates: ratesSchema, TIPOWODs: z.record(z.string().regex(/^[1-9]\d*$/), z.unknown()) }).strict())]) }).strict();
+export function parseActivityCalendar(body, month) {
+    const parsed = calendarSchema.safeParse(body);
+    if (!parsed.success)
+        throw new AimHarderError('INVALID_ACTIVITY_RESPONSE');
+    const entries = new Map();
+    const seen = new Map();
+    for (const [date, day] of Object.entries(parsed.data.workouts)) {
+        if (!date.startsWith(`${month}-`))
+            throw new AimHarderError('INVALID_ACTIVITY_RESPONSE');
+        for (const id of day.rates.ids) {
+            if (seen.has(id) && seen.get(id) !== date)
+                throw new AimHarderError('INVALID_ACTIVITY_RESPONSE');
+            seen.set(id, date);
+        }
+        entries.set(date, [...new Set(day.rates.ids)]);
+    }
+    return entries;
+}
+const identitySchema = z.object({ userId: z.number().int().positive().safe(), boxId: z.number().int().positive().safe() });
+export function parseActivityDetail(body, sourceActivityId, date, accountId, boxId, gymId, timeZone) {
+    const identity = identitySchema.safeParse(body);
+    if (!identity.success || identity.data.userId !== accountId)
+        throw new AimHarderError('INVALID_ACTIVITY_RESPONSE');
+    // The calendar is account-wide. Verify the detail's gym before projecting it.
+    if (identity.data.boxId !== boxId)
+        return null;
+    const workout = parseWorkout(body, { id: sourceActivityId, wodClass: 'personal-activity' }, gymId, timeZone);
+    if (!workout || workout.date !== date)
+        throw new AimHarderError('INVALID_ACTIVITY_RESPONSE');
+    const details = resultDetailSchema.safeParse(body);
+    if (!details.success)
+        throw new AimHarderError('INVALID_ACTIVITY_RESPONSE');
+    const blocks = workout.blocks.map((block, index) => {
+        const source = details.data.TIPOWODs[index];
+        // Deleted blocks retain their position, but never expose recorded results.
+        if (typeof source === 'object' && source !== null && 'deleted' in source && source.deleted === true)
+            return { ...block, result: {} };
+        const result = activityResultSchema.omit({ desc: true }).safeParse(source);
+        if (!result.success)
+            throw new AimHarderError('INVALID_ACTIVITY_RESPONSE');
+        return { ...block, result: { ...result.data, ...resultDescription(details.data.chartData, source, sourceActivityId) } };
+    });
+    return activityEntrySchema.parse({ sourceActivityId, date, timeZone, startTime: null, trainingSessionId: null, titles: workout.titles, blocks, exercises: workout.exercises });
+}

package/dist/bookings.js

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+import { dateSchema, timeSchema } from './classes.js';
+import { AimHarderError } from './errors.js';
+const sourceId = z.number().int().positive().safe();
+export const upcomingBookingSchema = z.object({
+    sourceBookingId: sourceId, sessionId: z.null(),
+    date: dateSchema, dateLabel: z.string(), startTime: timeSchema, timeLabel: z.string(), timeZone: z.string(),
+    classType: z.object({ id: z.null(), name: z.string().nullable() }),
+    state: z.enum(['booked', 'waitlisted', 'unknown']), sourceState: z.number().int().safe().nullable(),
+});
+const responseSchema = z.object({
+    nextClasses: z.array(z.object({
+        id: sourceId, day: z.string(),
+        time: z.string().regex(/^(?:[01]\d|2[0-3]):[0-5]\d - (?:[01]\d|2[0-3]):[0-5]\d$/),
+        className: z.string().min(1).max(300).refine((name) => name.trim().length > 0).nullish(),
+        bookState: z.number().int().safe().nullish(),
+    })),
+    // History is returned by this operation but is not interpreted or exposed by this slice.
+    history: z.array(z.unknown()),
+}).strict();
+const months = ['Enero', 'Febrero', 'Marzo', 'Abril', 'Mayo', 'Junio', 'Julio', 'Agosto', 'Septiembre', 'Octubre', 'Noviembre', 'Diciembre'];
+const weekdays = ['Domingo', 'Lunes', 'Martes', 'Miércoles', 'Jueves', 'Viernes', 'Sábado'];
+/** Accept only the verified Spanish full-date format; never let Date.parse guess a locale. */
+function calendarDate(label) {
+    const match = /^(Domingo|Lunes|Martes|Miércoles|Jueves|Viernes|Sábado), (\d{1,2}) de ([A-Za-z]+) de (\d{4})$/.exec(label);
+    if (!match)
+        throw new AimHarderError('INVALID_BOOKING_RESPONSE');
+    const month = months.indexOf(match[3]);
+    const date = `${match[4]}-${String(month + 1).padStart(2, '0')}-${match[2].padStart(2, '0')}`;
+    if (month < 0 || !dateSchema.safeParse(date).success || weekdays[new Date(`${date}T00:00:00Z`).getUTCDay()] !== match[1]) {
+        throw new AimHarderError('INVALID_BOOKING_RESPONSE');
+    }
+    return date;
+}
+export function parseUpcomingBookings(body, timeZone) {
+    const parsed = responseSchema.safeParse(body);
+    if (!parsed.success)
+        throw new AimHarderError('INVALID_BOOKING_RESPONSE');
+    const ids = new Set();
+    return parsed.data.nextClasses.map((row) => {
+        if (ids.has(row.id))
+            throw new AimHarderError('INVALID_BOOKING_RESPONSE');
+        ids.add(row.id);
+        return {
+            sourceBookingId: row.id, sessionId: null,
+            date: calendarDate(row.day), dateLabel: row.day,
+            startTime: row.time.slice(0, 5), timeLabel: row.time, timeZone,
+            classType: { id: null, name: row.className ?? null },
+            state: row.bookState === 1 ? 'booked' : row.bookState === 0 ? 'waitlisted' : 'unknown',
+            sourceState: row.bookState ?? null,
+        };
+    });
+}
+export const historicalBookingSchema = upcomingBookingSchema.extend({
+    state: z.enum(['booked', 'waitlisted', 'late-cancelled', 'unknown']),
+    attendance: z.literal('unverified'),
+    sourceFlags: z.object({ assist: z.number().int().safe().nullable(), lateCancel: z.number().int().safe().nullable() }),
+});
+const historyResponseSchema = z.object({ nextClasses: z.array(z.unknown()), history: z.array(z.unknown()) }).strict();
+const historyRowSchema = responseSchema.shape.nextClasses.element.extend({
+    assist: z.number().int().safe().nullish(), lateCancel: z.number().int().safe().nullish(),
+});
+export function parseBookingHistory(body, timeZone) {
+    const parsed = historyResponseSchema.safeParse(body);
+    if (!parsed.success)
+        throw new AimHarderError('INVALID_BOOKING_RESPONSE');
+    const rows = new Map();
+    const conflicts = new Set();
+    let partial = false;
+    for (const raw of parsed.data.history) {
+        const entry = historyRowSchema.safeParse(raw);
+        if (!entry.success) {
+            partial = true;
+            const identity = z.object({ id: sourceId }).safeParse(raw);
+            if (identity.success)
+                conflicts.add(identity.data.id);
+            continue;
+        }
+        const row = entry.data;
+        try {
+            const base = parseUpcomingBookings({ nextClasses: [row], history: [] }, timeZone)[0];
+            const booking = {
+                ...base, state: row.lateCancel === 1 ? 'late-cancelled'
+                    : row.lateCancel != null && row.lateCancel !== 0 ? 'unknown' : base.state,
+                attendance: 'unverified', sourceFlags: { assist: row.assist ?? null, lateCancel: row.lateCancel ?? null },
+            };
+            const previous = rows.get(row.id);
+            if (previous && JSON.stringify(previous) !== JSON.stringify(booking)) {
+                conflicts.add(row.id);
+                partial = true;
+            }
+            rows.set(row.id, booking);
+        }
+        catch {
+            partial = true;
+            conflicts.add(row.id);
+        }
+    }
+    for (const id of conflicts)
+        rows.delete(id);
+    // A response in which nothing can be interpreted is an error, never an empty history.
+    if (partial && rows.size === 0)
+        throw new AimHarderError('INVALID_BOOKING_RESPONSE');
+    return { bookings: [...rows.values()].sort((a, b) => `${b.date} ${b.startTime}`.localeCompare(`${a.date} ${a.startTime}`) || a.sourceBookingId - b.sourceBookingId), partial };
+}

package/dist/classes.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { gymIdSchema } from './config.js';
+import { AimHarderError } from './errors.js';
+// Calendar arithmetic uses UTC only as a Gregorian date counter, never as the gym zone.
+export const dateSchema = z.iso.date().refine((date) => !date.startsWith('0000'));
+export const timeSchema = z.string().regex(/^(?:[01]\d|2[0-3]):[0-5]\d$/);
+export const classQuerySchema = z.object({
+    startDate: dateSchema, endDate: dateSchema, gymId: gymIdSchema.optional(),
+    startTime: timeSchema.optional(), className: z.string().min(1).max(300).optional(),
+}).strict().refine((query) => query.startDate <= query.endDate, { message: 'startDate must be on or before endDate.' });
+const sourceId = z.number().int().positive().safe();
+const count = z.number().int().nonnegative().safe();
+export const classSessionSchema = z.object({
+    sessionId: z.string(), sourceId,
+    date: dateSchema, startTime: timeSchema, timeLabel: z.string(), timeZone: z.string(),
+    classType: z.object({ id: sourceId, name: z.string() }),
+    occupancy: count.nullable(), capacity: count.nullable(),
+});
+const timeLabelSchema = z.string().regex(/^(?:[01]\d|2[0-3]):[0-5]\d - (?:[01]\d|2[0-3]):[0-5]\d$/);
+const dailySchema = z.object({
+    bookings: z.array(z.object({
+        id: sourceId, classId: sourceId,
+        className: z.string().min(1).max(300).refine((name) => name.trim().length > 0),
+        time: timeLabelSchema, ocupation: count.nullish(), limit: count.nullish(),
+    })),
+    // Only the observed complete-day envelope is accepted. New pagination/error fields
+    // need investigation instead of being stripped and misreported as complete coverage.
+    clasesDisp: z.string().optional(), day: z.string().optional(),
+    timetable: z.array(z.unknown()).optional(), seminars: z.array(z.string()).optional(),
+    resmsgs: z.array(z.never()).optional(),
+}).strict();
+export function* calendarDates(startDate, endDate) {
+    let date = startDate;
+    while (true) {
+        yield date;
+        if (date === endDate)
+            return;
+        const next = new Date(`${date}T00:00:00.000Z`);
+        next.setUTCDate(next.getUTCDate() + 1);
+        date = next.toISOString().slice(0, 10);
+    }
+}
+export function parseClassDay(body, gymId, date, timeZone) {
+    const parsed = dailySchema.safeParse(body);
+    if (!parsed.success)
+        throw new AimHarderError('INVALID_CLASS_RESPONSE');
+    const ids = new Set();
+    return parsed.data.bookings.map((row) => {
+        if (ids.has(row.id))
+            throw new AimHarderError('INVALID_CLASS_RESPONSE');
+        ids.add(row.id);
+        return {
+            sessionId: `${gymId}:${date}:${row.id}`, sourceId: row.id,
+            date, startTime: row.time.slice(0, 5), timeLabel: row.time, timeZone,
+            classType: { id: row.classId, name: row.className },
+            occupancy: row.ocupation ?? null, capacity: row.limit ?? null,
+        };
+    });
+}