@jabybaby/bubbles

Bubbles API Wrapper

TypeScript wrapper for the Bubbles laundromat API with full type safety and authentication support.

About Bubbles

Bubbles is a Hungarian laundromat service that provides mobile app access to their washing machine network. The application allows users to find locations, check machine availability, make reservations, and manage their laundry activities.

Technical Architecture:

• Backend: Express.js server behind nginx reverse proxy
• Frontend: Expo/React Native mobile application
• API: RESTful API with JWT authentication
• Infrastructure: Hosted at api.hu.bubbles.hu

Note: This wrapper was created through reverse engineering of the mobile application's API endpoints and is not officially affiliated with Bubbles.

Features

• 🔐 Authentication - Login with username/password, JWT token management
• 🏪 Shops - Get shop listings and detailed shop information with machine availability
• 📋 Contracts - Fetch registration documents (terms, privacy policy, marketing)
• 🛡️ Type Safety - Full TypeScript support with comprehensive interfaces
• 🧪 Testing - Complete test suite with Jest
• 📦 Modular - Organized endpoint groups to avoid monolithic structure

Installation

npm install @jabybaby/bubbles

Usage

import { BubblesClient } from '@jabybaby/bubbles';

const client = new BubblesClient();

// Login (stores JWT token automatically)
await client.login({
  username: 'your-username',
  password: 'your-password'
});

// Get user info from JWT
const userInfo = client.getUserInfo();
console.log(userInfo.username, userInfo.email);

// Get all shops (public)
const shops = await client.shops.getAll();
console.log(shops.cities); // Available cities

// Get detailed shop info with machine availability (public)
const shopDetails = await client.shops.getById(45);
console.log(shopDetails.machines.washingMachines);

// Get registration documents (public)
const docs = await client.contracts.getRegistrationDocuments();
console.log(docs.documents);

// Get current user profile (authenticated)
const profile = await client.auth.whoami();
console.log(profile.firstName, profile.email, profile.balance);

// Get social contracts to accept (authenticated)
const socialContracts = await client.contracts.getSocialContractsToAccept();
console.log(socialContracts.documents);

// Get user reservations (authenticated)
const reservations = await client.reservations.getReservations();
console.log(reservations); // Array of reservation objects

API Endpoints

Authentication

• POST /auth/login - Login with credentials
• GET /auth/whoami - Get current user profile (authenticated)

Shops (Public)

• GET /shops/by-currency/HUF - Get all shops
• GET /shops/{id} - Get shop details with machines

Contracts

• GET /contracts/v2/registration - Get registration documents (public)
• GET /contracts/social/contracts-to-accept - Get social contracts to accept (authenticated)

Reservations (Authenticated)

• GET /reservations - Get user reservations

Development

# Build
npm run build

# Run tests
npm test

# Watch tests
npm run test:watch

# Coverage report
npm run test:coverage

# Lint
npm run lint

Project Structure

src/
├── bubbles-client.ts    # Main client class
├── types.ts            # TypeScript interfaces
├── endpoints/          # Endpoint groups
│   ├── auth.ts         # Authentication endpoints
│   ├── shops.ts        # Shop listings and details
│   ├── contracts.ts    # Legal documents
│   └── reservations.ts # User reservations
└── index.ts           # Main export

tests/                 # Test files
├── bubbles-client.test.ts
└── endpoints/
    ├── auth.test.ts
    ├── shops.test.ts
    ├── contracts.test.ts
    └── reservations.test.ts

Types

The wrapper includes comprehensive TypeScript types for all API responses:

• LoginResponse - Authentication response with JWT
• JWTPayload - Decoded JWT user information
• UserProfile - Complete user profile data from whoami endpoint
• Shop - Shop listing information
• ShopDetails - Detailed shop with machines
• Machine - Washing machine/dryer details
• ContractDocument - Legal document information
• Reservation - User reservation object (structure TBD)
• SocialContractsResponse - Social contracts to accept
• ReservationsResponse - Array of user reservations

Authentication

The client handles JWT tokens automatically:

• Stores token after successful login
• Includes Authorization: Bearer <token> in authenticated requests
• Provides methods to check authentication status and decode user info
• Note: The API's JWT signature appears to be invalid, but the payload decodes correctly

Expandable Types

Some types are designed to be expanded as the API structure becomes clearer:

• Reservation interface is currently empty but ready to be populated with actual reservation properties
• The wrapper structure allows easy addition of new endpoints and types

License

MIT