Regweb API JavaScript SDK

A modern TypeScript/JavaScript SDK for the Regweb member management API with full OAuth2 support and comprehensive type safety.

Features

• OAuth2 Authentication - Automatic token management with refresh
• Full TypeScript Support - Complete type definitions with IntelliSense
• Modern HTTP Client - Built on Axios with intelligent error handling
• Auto Token Refresh - Seamless token renewal and session management
• Multiple Build Formats - ESM and CommonJS builds with source maps
• Comprehensive Testing - Jest test suite with coverage reporting
• Advanced Error Handling - Detailed error responses with proper typing
• Modern Tooling - ESLint, Rollup, and TypeScript 5.9+
• Interactive Demo - Built-in terminal demo for testing
• Session Persistence - Token storage and restoration utilities

Requirements

• Bun: 1.0.0 or higher (recommended - fast, modern JavaScript runtime)
• TypeScript: 5.0.0 or higher (for TypeScript projects)
• Modern JavaScript Environment: ES2020+ support

Why Bun? Bun is significantly faster than Node.js for package management, testing, and running JavaScript/TypeScript. It provides native TypeScript support, built-in testing, and excellent performance.

Performance Comparison:

• Package installation: ~3-5x faster than npm
• Test execution: ~2-3x faster than Jest
• TypeScript compilation: Native support, no additional tooling needed
• Startup time: ~10x faster than Node.js

Installation

# Using Bun (recommended - fastest)
bun add regweb-api-js

# Using npm
npm install regweb-api-js

# Using yarn
yarn add regweb-api-js

# Using pnpm
pnpm add regweb-api-js

Quick Start

TypeScript/ES Modules

import { RegwebApi, RegwebApiError } from 'regweb-api-js';

// Initialize the API client
const api = new RegwebApi({
  baseUrl: 'https://your-regweb-instance.com',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  timeout: 30000, // optional, defaults to 30 seconds
});

// Authenticate with comprehensive error handling
try {
  const authResponse = await api.login('username', 'password');
  console.log('Logged in successfully!', {
    tokenType: authResponse.token_type,
    expiresIn: authResponse.expires_in,
    scope: authResponse.scope
  });
} catch (error) {
  if (error instanceof RegwebApiError) {
    console.error('Login failed:', {
      message: error.message,
      status: error.status,
      errorCode: error.data.error,
      description: error.data.error_description
    });
  } else {
    console.error('Unexpected error:', error);
  }
}

// Get current user with member data
const user = await api.getUser(true);
console.log('Current user:', user);

CommonJS

const { RegwebApi, RegwebApiError } = require('regweb-api-js');

// Same usage as above
const api = new RegwebApi({
  baseUrl: 'https://your-regweb-instance.com',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

Examples

Interactive Demo

Run the comprehensive interactive demo to test the API with your credentials:

# Run the interactive demo (recommended for first-time setup)
bun run demo

# Alternative with npm (slower)
npm run demo

The demo provides:

• Interactive prompts for API configuration and credentials
• Secure password input (hidden from terminal)
• Complete API testing including:
  • OAuth2 authentication flow
  • User data retrieval with member expansion
  • Member information display and updates
  • Optional select values and member types
  • Password recovery functionality
  • Session management demonstration

Example Files

| File | Description | Usage | |------|-------------|-------| | examples/interactive-demo.mjs | Comprehensive interactive terminal demo | bun run demo | | examples/basic-usage.mjs | Basic API operations and error handling | bun examples/basic-usage.mjs | | examples/session-management.ts | Advanced session persistence and token management | bun examples/session-management.ts |

See examples/README.md for detailed documentation of each example.

Migrating from Node.js to Bun

If you're currently using Node.js, migrating to Bun is straightforward:

# Install Bun (if not already installed)
curl -fsSL https://bun.sh/install | bash

# Remove node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Install dependencies with Bun
bun install

# Run tests with Bun (much faster)
bun test

# Build with Bun
bun run build

Benefits of switching:

• Faster package installation and dependency resolution
• Native TypeScript support without additional configuration
• Built-in test runner that's faster than Jest
• Better performance for development workflows
• Single binary with no external dependencies

API Reference

Authentication

login(username: string, password: string): Promise<AuthResponse>

Authenticate with username and password.

const authResponse = await api.login('[email protected]', 'password');
console.log('Access token:', authResponse.access_token);

refreshToken(): Promise<AuthResponse>

Refresh the access token using the stored refresh token.

const newTokens = await api.refreshToken();

isLoggedIn(): boolean

Check if the user is currently authenticated.

if (api.isLoggedIn()) {
  console.log('User is authenticated');
}

logout(): void

Clear all authentication tokens.

api.logout();

User Management

getUser(expandMember?: boolean): Promise<User>

Get current user data with optional member expansion.

// Get user with member data
const user = await api.getUser(true);

// Get user without member data
const userOnly = await api.getUser(false);

Member Management

getMember(id: number): Promise<Member>

Get member data by ID.

const member = await api.getMember(123);
console.log('Member:', member.firstname, member.lastname);

updateMember(id: number, memberData: Partial<Member>): Promise<UpdateResult>

Update member data. Only provided fields will be updated.

const result = await api.updateMember(123, {
  firstname: 'John',
  lastname: 'Doe',
  email: '[email protected]',
  optional_textfield1: 'Custom value',
});

if (result.success) {
  console.log('Member updated successfully');
} else {
  console.error('Update failed:', result.errors);
}

createMemberUpdate(updates: Partial<Member>): Partial<Member>

Helper method to create a member update object with only allowed fields.

const memberUpdate = api.createMemberUpdate({
  firstname: 'John',
  id: 123, // This will be filtered out
  membertype: { id: 1, name: 'Regular' }, // This will be filtered out
});
// Result: { firstname: 'John' }

Optional Select Values

getOptionalSelectValues(id: number): Promise<OptionalSelectValues>

Get available options for optional select fields (1-4).

const selectOptions = await api.getOptionalSelectValues(1);
console.log('Options:', selectOptions.values);

Member Types

getMemberType(id: number): Promise<MemberType>

Get member type information.

const memberType = await api.getMemberType(1);
console.log('Member type:', memberType.name, 'Contingent:', memberType.contingent);

Password Recovery

lostPassword(identification: string): Promise<LostPasswordResponse>

Request a password reset email.

const result = await api.lostPassword('[email protected]');
if (result.success) {
  console.log('Password reset email sent');
}

Session Management

getTokenInfo(): { accessToken: string | null; refreshToken: string | null; expiresAt: Date | null }

Get current token information for session persistence.

const tokenInfo = api.getTokenInfo();
console.log('Token info:', {
  hasAccessToken: !!tokenInfo.accessToken,
  hasRefreshToken: !!tokenInfo.refreshToken,
  expiresAt: tokenInfo.expiresAt,
  isExpired: tokenInfo.expiresAt ? new Date() > tokenInfo.expiresAt : true
});

// Store tokens for later restoration
if (tokenInfo.accessToken && tokenInfo.refreshToken && tokenInfo.expiresAt) {
  localStorage.setItem('regweb_tokens', JSON.stringify({
    accessToken: tokenInfo.accessToken,
    refreshToken: tokenInfo.refreshToken,
    expiresAt: tokenInfo.expiresAt.toISOString()
  }));
}

restoreSession(accessToken: string, refreshToken: string, expiresAt: Date): void

Restore a previous authentication session from stored tokens.

// Restore from stored tokens
const storedTokens = localStorage.getItem('regweb_tokens');
if (storedTokens) {
  const { accessToken, refreshToken, expiresAt } = JSON.parse(storedTokens);
  api.restoreSession(
    accessToken,
    refreshToken,
    new Date(expiresAt)
  );

  // Check if session is still valid
  if (api.isLoggedIn()) {
    console.log('Session restored successfully');
  } else {
    console.log('Session expired, please login again');
  }
}

Error Handling

The SDK provides comprehensive error handling through the RegwebApiError class with detailed error information:

import { RegwebApiError } from 'regweb-api-js';

try {
  await api.login('invalid', 'credentials');
} catch (error) {
  if (error instanceof RegwebApiError) {
    console.error('API Error Details:', {
      message: error.message,
      status: error.status,
      statusText: error.statusText,
      errorCode: error.data.error,
      description: error.data.error_description
    });

    // Handle specific error conditions
    if (error.data.member_active_check_failed) {
      console.error('Member account is not active');
      // Redirect to account activation flow
    }

    if (error.data.unique_email_check_failed) {
      console.error('Email address is already in use');
      // Show email conflict resolution options
    }

    // Handle different HTTP status codes
    switch (error.status) {
      case 401:
        console.error('Authentication failed - check credentials');
        break;
      case 403:
        console.error('Access forbidden - insufficient permissions');
        break;
      case 404:
        console.error('Resource not found');
        break;
      case 429:
        console.error('Rate limit exceeded - please wait before retrying');
        break;
      case 500:
        console.error('Server error - please try again later');
        break;
      default:
        console.error(`Unexpected error: ${error.status} ${error.statusText}`);
    }
  } else {
    // Handle network errors, timeouts, etc.
    console.error('Network or unexpected error:', error.message);
  }
}

Common Error Scenarios

| Error Code | Description | Typical Cause | Resolution | |------------|-------------|---------------|------------| | invalid_grant | Authentication failed | Wrong username/password | Verify credentials | | invalid_client | Client authentication failed | Wrong client ID/secret | Check API credentials | | member_active_check_failed | Member account inactive | Account disabled | Contact administrator | | unique_email_check_failed | Email already exists | Duplicate email in update | Use different email |

TypeScript Support

The SDK is built with TypeScript 5.9+ and provides comprehensive type definitions with full IntelliSense support:

import {
  RegwebApi,
  Member,
  User,
  UpdateResult,
  RegwebApiConfig,
  AuthResponse,
  MemberType,
  OptionalSelectValues,
  RegwebApiError
} from 'regweb-api-js';

// Configuration is fully typed
const config: RegwebApiConfig = {
  baseUrl: 'https://api.example.com',
  clientId: 'client-id',
  clientSecret: 'client-secret',
  timeout: 30000 // optional
};

const api = new RegwebApi(config);

// All methods return properly typed responses
const authResponse: AuthResponse = await api.login('user', 'pass');
const user: User = await api.getUser(true); // expandMember parameter is typed
const member: Member = await api.getMember(123);
const memberType: MemberType = await api.getMemberType(1);
const selectValues: OptionalSelectValues = await api.getOptionalSelectValues(1);

// Update operations are type-safe
const updateData: Partial<Member> = {
  firstname: 'John',
  lastname: 'Doe',
  email: '[email protected]',
  optional_textfield1: 'Custom value'
};

const result: UpdateResult = await api.updateMember(123, updateData);

// Helper methods maintain type safety
const filteredUpdate = api.createMemberUpdate({
  firstname: 'John',
  id: 123, // This will be filtered out automatically
  membertype: { id: 1, name: 'Regular' } // This will be filtered out too
});
// Result type: { firstname: string }

Type Definitions

All interfaces are exported for use in your application:

// Import specific types as needed
import type {
  Member,
  User,
  MemberType,
  AuthResponse,
  UpdateResult,
  ApiError
} from 'regweb-api-js';

Data Models

User Object

interface User {
  username: string;
  firstname: string;
  lastname: string;
  is_member: boolean;
  email: string;
  member?: Member;
}

Member Object

interface Member {
  id: number;
  active?: boolean;
  firstname: string;
  lastname: string;
  address1?: string;
  address2?: string;
  postalcode?: string;
  phone1?: string;
  phone2?: string;
  mobile?: string;
  email: string;
  password?: string;

  // Optional text fields (1-6)
  optional_textfield1?: string;
  optional_textfield2?: string;
  optional_textfield3?: string;
  optional_textfield4?: string;
  optional_textfield5?: string;
  optional_textfield6?: string;

  // Optional select fields (1-4) with labels
  optional_select1?: number;
  optional_select1_label?: string;
  optional_select2?: number;
  optional_select2_label?: string;
  optional_select3?: number;
  optional_select3_label?: string;
  optional_select4?: number;
  optional_select4_label?: string;

  // Optional date fields (1-2)
  optional_date1?: string; // ISO date string
  optional_date2?: string; // ISO date string

  // Optional checkbox fields (1-4)
  optional_checkbox1?: boolean;
  optional_checkbox2?: boolean;
  optional_checkbox3?: boolean;
  optional_checkbox4?: boolean;

  membertype?: MemberType;
}

Additional Data Models

interface MemberType {
  id: number;
  name: string;
  contingent?: number;
}

interface OptionalSelectValues {
  id: number;
  label: string;
  values: OptionalSelectValue[];
}

interface OptionalSelectValue {
  id: number;
  label: string;
}

interface UpdateResult {
  success: boolean;
  errors?: Record<string, string[]>;
}

interface AuthResponse {
  access_token: string;
  refresh_token: string;
  expires_in: number;
  token_type: string;
  scope: string;
}

Development

Prerequisites

• Bun: 1.0.0 or higher (recommended)
• TypeScript: 5.9.0 or higher

Note: While the SDK works with Node.js 18+, we strongly recommend using Bun for development due to its superior performance, built-in TypeScript support, and faster package management.

Setup

# Clone the repository
git clone https://github.com/regweb/regweb-api-js.git
cd regweb-api-js

# Install dependencies with Bun (recommended - much faster)
bun install

# Run type checking
bun run type-check

# Alternative with npm (slower)
# npm install && npm run type-check

Build System

The project uses Rollup for building multiple output formats:

# Build the library (ESM + CommonJS + TypeScript declarations)
bun run build

# Development build with watch mode
bun run dev

# Alternative with npm (slower)
# npm run build && npm run dev

Build outputs:

• dist/index.esm.js - ES Module build with source maps
• dist/index.js - CommonJS build with source maps
• dist/index.d.ts - TypeScript declarations
• dist/index.d.ts.map - Declaration source maps

Testing

# Run all tests with Bun (recommended - much faster)
bun test

# Run tests in watch mode
bun test --watch

# Run tests with coverage
bun test --coverage

# Alternative with Jest/npm (slower)
# npm run test:jest

Test configuration:

• Primary: Bun's built-in test runner (fast, native TypeScript support)
• Alternative: Jest with ts-jest (for compatibility)
• Environment: Bun runtime with ESM support
• Coverage: Automatic collection from src/ directory
• Setup: Custom test setup in tests/setup.ts

Code Quality

# Lint code (ESLint with TypeScript support)
bun run lint

# Fix linting issues automatically
bun run lint:fix

# Type checking without emitting files
bun run type-check

# Alternative with npm (slower)
# npm run lint && npm run lint:fix && npm run type-check

Linting configuration:

• ESLint: 9.33+ with TypeScript ESLint plugin
• Rules: Strict TypeScript rules with custom overrides
• Formatting: 4-space indentation, consistent style

Publishing

# Prepare for publishing (runs build automatically)
bun run prepublishOnly

# Publish to npm (requires authentication)
bun run npm publish

# Alternative with npm
# npm run prepublishOnly && npm publish

Architecture

Core Components

• RegwebApi - Main API client class with all public methods
• AuthManager - OAuth2 token management and automatic refresh
• HttpClient - Axios-based HTTP client with error handling
• RegwebApiError - Custom error class for API-specific errors

Design Principles

• Type Safety: Full TypeScript coverage with strict typing
• Error Handling: Comprehensive error types and handling strategies
• Session Management: Automatic token refresh and session persistence
• Modern Standards: ES2020+ features, ESM/CommonJS dual builds
• Developer Experience: IntelliSense support, detailed documentation

Runtime Support

The SDK supports modern JavaScript runtimes and browsers:

• Bun: 1.0.0+ (recommended - fastest performance)
• Node.js: 18.0.0+ (legacy support)
• Browsers: Chrome 80+, Firefox 72+, Safari 13.1+, Edge 80+
• Module Systems: ESM, CommonJS, UMD (via bundlers)

Performance Note: Bun provides significantly better performance for package installation, testing, and runtime execution compared to Node.js.

License

MIT License - see LICENSE file for details.

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with proper TypeScript types
4. Add tests for new functionality
5. Run the full test suite (bun test)
6. Lint your code (bun run lint:fix)
7. Commit your changes (git commit -m 'Add amazing feature')
8. Push to the branch (git push origin feature/amazing-feature)
9. Submit a pull request

Development Guidelines

• Maintain 100% TypeScript coverage
• Add tests for all new features
• Follow existing code style and patterns
• Update documentation for API changes
• Ensure all CI checks pass

Support

• Issues: GitHub Issues
• Documentation: This README and inline code documentation
• Examples: See examples/ directory
• Discussions: GitHub Discussions

Changelog

See GitHub Releases for version history and changes.