Clubworx

A package for fetching your own data from Clubworx. This package is in no way officially affiliated with Clubworx.

Install

npm install clubworx

Usage

import clubworx from 'clubworx';

// Creates a session with your login details, ideally from ENV
const session = await clubworx.login('[email protected]', 'secret');

// Get array of all your reports (just ID and name)
const reports = await session.allReports();
// Returns: [{ id: 123, name: "My Report" }, ...]

// Get the complete data for a specific report (array of row objects)
const report = await session.reportById(reports[0].id);
// Returns: [{ "First Name": "John", "Last Name": "Doe", ... }, ...]

// Optional pagination parameters (default: page=1, count=100)
const reportPage2 = await session.reportById(reports[0].id, { page: 2, count: 50 });

// Get members with optional pagination and search
const members = await session.members();
// Returns: [{ id: 12345, name: "Jane Doe", firstName: "Jane", lastName: "Doe", ... }, ...]

// With pagination and search
const searchResults = await session.members({ page: 1, count: 50, search: 'Smith' });

// Get a single member by ID
const member = await session.memberById(members[0].id);
// Returns: { id: 12345, name: "Jane Doe", firstName: "Jane", lastName: "Doe", ... }

// Add a note to a member
const note = await session.addMemberNote(members[0].id, 'Subject', 'Note body text');
// Returns: { id: 964591, subject: "Subject", body: "Note body text", created_at: "...", ... }

// With optional tags
const taggedNote = await session.addMemberNote(members[0].id, 'Follow-up', 'Call next week', ['urgent', 'callback']);

// Iterate over every member (pages automatically)
for await (const m of session.allMembers()) {
  console.log(m.name);
}

// Download a member's profile photo as a Buffer
const photo = await session.downloadImage(member.imageUrl);

// Financials summary from the dashboard
const financials = await session.financials();

console.log({ reports, report, members, member, note });

Classes and check-ins

// Classes/events on a day (Date or 'YYYY-MM-DD')
const classes = await session.classesOn(new Date());
// Returns: [{ id, name, startsAt, endsAt, instructor, location, capacity, bookedCount, attendedCount, raw }, ...]

// Check a member in to a class, and undo it
await session.checkInToClass(classes[0].id, member.id);
await session.undoCheckIn(classes[0].id, member.id);

Status: the class/attendance endpoints have not yet been confirmed against the Clubworx web app. Until the CLASS_ENDPOINTS block at the top of index.js is filled in (see DISCOVERY.md), these methods throw "<name>: Clubworx endpoint not yet discovered".

Errors

Non-2xx responses and unparseable bodies throw an Error with statusCode and body properties. An expired login throws SessionExpiredError (see below). Cookies are refreshed from every response, so long-lived sessions keep a valid CSRF token — persist session.toJSON() again after mutating calls if you store sessions externally.

For CommonJS, use const clubworx = require('clubworx') and wrap in an async function.

Serverless Usage

For serverless environments, you can serialize and restore sessions to avoid re-authenticating on every invocation:

const { login, Session, SessionExpiredError } = require('clubworx');

// First invocation - login and save session
const session = await login('[email protected]', 'secret');
const sessionData = session.toJSON();
// Store sessionData in your preferred storage (Redis, DynamoDB, S3, etc.)
await saveToStorage('session-key', JSON.stringify(sessionData));

// Subsequent invocations - restore session from storage
try {
  const storedData = JSON.parse(await getFromStorage('session-key'));
  const session = Session.fromJSON(storedData);
  const reports = await session.allReports();
} catch (error) {
  if (error instanceof SessionExpiredError) {
    // Session expired - login again and update storage
    const session = await login('[email protected]', 'secret');
    await saveToStorage('session-key', JSON.stringify(session.toJSON()));
    const reports = await session.allReports();
  } else {
    throw error;
  }
}