@hermanl02/hostex-api

TypeScript client library for Hostex API v3 - Property management, reservations, and channel integrations.

Features

• Type-safe - Full TypeScript support with types generated from OpenAPI specification
• Complete API coverage - All Hostex API v3 endpoints
• Automatic retry - Configurable retry logic with exponential backoff
• Error handling - Detailed error types and validation
• Easy to use - Clean, intuitive API

Installation

npm install @hermanl02/hostex-api

Quick Start

import { HostexApiClient } from '@hermanl02/hostex-api';

// Initialize the client
const client = new HostexApiClient({
  accessToken: 'your-hostex-access-token',
});

// Query properties
const properties = await client.getProperties({ limit: 10 });
console.log(properties);

// Query reservations
const reservations = await client.getReservations({
  start_check_in_date: '2025-01-01',
  end_check_in_date: '2025-01-31',
});
console.log(reservations);

Configuration

const client = new HostexApiClient({
  // Required: Your Hostex access token
  accessToken: 'your-access-token',

  // Optional: API base URL (default: https://api.hostex.io/v3)
  baseUrl: 'https://api.hostex.io/v3',

  // Optional: Request timeout in milliseconds (default: 30000)
  timeout: 30000,

  // Optional: Retry configuration
  retry: {
    maxAttempts: 3,
    initialDelay: 1000,
    maxDelay: 10000,
    backoffMultiplier: 2,
  },
});

API Reference

Properties

// Get properties with pagination
const properties = await client.getProperties({
  offset: 0,
  limit: 20,
  id: 123, // Optional: filter by property ID
});

// Get all properties (handles pagination automatically)
const allProperties = await client.getAllProperties();

Room Types

// Get room types with pagination
const roomTypes = await client.getRoomTypes({
  offset: 0,
  limit: 20,
});

// Get all room types
const allRoomTypes = await client.getAllRoomTypes();

Reservations

// Query reservations
const reservations = await client.getReservations({
  property_id: 123,
  status: 'accepted',
  start_check_in_date: '2025-01-01',
  end_check_in_date: '2025-01-31',
  offset: 0,
  limit: 20,
});

// Create a reservation (direct booking)
await client.createReservation({
  property_id: '123',
  custom_channel_id: 456,
  check_in_date: '2025-01-15',
  check_out_date: '2025-01-20',
  guest_name: 'John Doe',
  email: '[email protected]',
  currency: 'USD',
  rate_amount: 500,
  commission_amount: 50,
  received_amount: 500,
  income_method_id: 1,
});

// Cancel a reservation
await client.cancelReservation('reservation-code');

// Update lock code
await client.updateLockCode({
  stay_code: 'stay-code',
  lock_code: '1234',
});

// Move to reservation box
await client.moveToBox({ stay_code: 'stay-code' });

// Allocate to property
await client.allocateToProperty({
  stay_code: 'stay-code',
  property_id: 123,
});

// Custom fields
const customFields = await client.getCustomFields('stay-code');
await client.updateCustomFields({
  stay_code: 'stay-code',
  custom_fields: {
    online_checkin_url: 'https://...',
    special_note: 'VIP guest',
  },
});

// Get custom channels and income methods
const customChannels = await client.getCustomChannels();
const incomeMethods = await client.getIncomeMethods();

Availability

// Query availability
const availability = await client.getAvailabilities({
  property_ids: [123, 456],
  start_date: '2025-01-01',
  end_date: '2025-01-31',
});

// Update availability
await client.updateAvailabilities({
  property_ids: [123, 456],
  start_date: '2025-01-15',
  end_date: '2025-01-20',
  available: false,
});

// Or update specific dates
await client.updateAvailabilities({
  property_ids: [123],
  dates: ['2025-01-15', '2025-01-16'],
  available: false,
});

Listing Calendar

// Query listing calendars
const calendars = await client.getListingCalendars({
  start_date: '2025-01-01',
  end_date: '2025-01-31',
  listings: [
    { channel_type: 'airbnb', listing_id: '12345' },
    { channel_type: 'booking.com', listing_id: '67890-1' },
  ],
});

// Update listing inventories
await client.updateListingInventories({
  channel_type: 'airbnb',
  listing_id: '12345',
  inventories: [
    { start_date: '2025-01-15', end_date: '2025-01-20', inventory: 5 },
  ],
});

// Update listing prices
await client.updateListingPrices({
  channel_type: 'airbnb',
  listing_id: '12345',
  prices: [
    { start_date: '2025-01-15', end_date: '2025-01-20', price: 150 },
  ],
});

// Update listing restrictions
await client.updateListingRestrictions({
  channel_type: 'booking.com',
  listing_id: '67890-1',
  restrictions: [
    {
      start_date: '2025-01-15',
      end_date: '2025-01-20',
      min_stay_on_arrival: 3,
      closed_on_arrival: false,
    },
  ],
});

Messages

// Query conversations
const conversations = await client.getConversations({
  offset: 0,
  limit: 20,
});

// Get conversation details
const details = await client.getConversationDetails('conversation-id');

// Send a message
await client.sendMessage({
  conversation_id: 'conversation-id',
  message: 'Hello! How can I help you?',
});

// Send an image
await client.sendMessage({
  conversation_id: 'conversation-id',
  jpeg_base64: 'base64-encoded-image...',
});

Reviews

// Query reviews
const reviews = await client.getReviews({
  property_id: 123,
  review_status: 'reviewed',
  start_check_out_date: '2025-01-01',
  end_check_out_date: '2025-01-31',
});

// Create a review
await client.createReview({
  reservation_code: 'reservation-code',
  host_review_score: 5,
  host_review_content: 'Great guest!',
});

// Reply to guest review
await client.createReview({
  reservation_code: 'reservation-code',
  host_reply_content: 'Thank you for your review!',
});

Webhooks

// Get all webhooks
const webhooks = await client.getWebhooks();

// Create a webhook
await client.createWebhook({
  url: 'https://your-server.com/webhook',
});

// Delete a webhook
await client.deleteWebhook({ id: '123' });

OAuth

// Obtain token with authorization code
const tokenData = await client.obtainToken({
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  grant_type: 'authorization_code',
  code: 'authorization-code',
});

// Refresh token
const newTokenData = await client.obtainToken({
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  grant_type: 'refresh_token',
  refresh_token: 'your-refresh-token',
});

// Revoke token
await client.revokeToken({
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  token: 'token-to-revoke',
});

Error Handling

import { HostexApiClient, HostexApiError } from '@hermanl02/hostex-api';

try {
  const properties = await client.getProperties();
} catch (error) {
  if (error instanceof HostexApiError) {
    console.error('Hostex API Error:', {
      message: error.message,
      errorCode: error.errorCode,
      statusCode: error.statusCode,
      requestId: error.requestId,
    });

    // Check error type
    if (error.isAuthError()) {
      console.error('Authentication failed');
    } else if (error.isRateLimitError()) {
      console.error('Rate limit exceeded');
    } else if (error.isNetworkError()) {
      console.error('Network error');
    }
  } else {
    console.error('Unknown error:', error);
  }
}

TypeScript Support

All API methods and data structures are fully typed:

import type {
  Property,
  Reservation,
  RoomType,
  ReservationStatus,
  ChannelType,
  // ... and many more
} from '@hermanl02/hostex-api';

Supported Channels

The package supports all Hostex channels:

• Airbnb
• Booking.com
• Agoda
• Expedia
• VRBO
• Trip.com
• Booking Site
• Houfy
• And more...

API Documentation

For detailed API documentation, visit the Hostex API Documentation.

License

ISC

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.