onvaca_connect 0.1.1

Dart SDK for the OnVaca Connect Platform — a unified interface for multiple property management system providers.

onvaca_connect

Dart SDK for the OnVaca Connect Platform — a unified interface for multiple property management system providers.

Installation

Add onvaca_connect to your pubspec.yaml:

dependencies:
  onvaca_connect: ^0.1.0

Then run:

pub get

Quick Start

import 'package:onvaca_connect/onvaca_connect.dart';

final connect = OnvacaConnect(
  apiKey: 'your-api-key',
  baseUrl: 'https://connect.onvaca.com',
);

// List properties
final properties = await connect.properties.list();
print('Found ${properties.total} properties');

// Create a booking
final booking = await connect.bookings.create({
  'property': '100',
  'daterange': {'start': '2026-06-01', 'end': '2026-06-07'},
  'adults': 2,
  'source_name': 'MyApp',
});
print('Booking created: ${booking.providerRef}');

// Always close the client when done
connect.close();

Resources

The SDK provides resource-based access to multiple entity types through the following methods:

Resource	Methods	Description
properties	list(), get(id)	Property listings and metadata
bookings	list(), get(id), create(data), cancel(id), confirm(id), quote(data)	Booking management and quotes
payments	list(), get(id), create(data), refund(id)	Payment tracking and refunds
messages	list(), get(id), create(data)	Guest communication
rates	list(), get(id)	Room rate information
setups	create(input)	Provider integration setup

Configuration

All configuration parameters are optional except apiKey and baseUrl:

final connect = OnvacaConnect(
  // Required
  apiKey: 'your-api-key',
  baseUrl: 'https://connect.onvaca.com',
  
  // Optional with defaults
  basePath: '/api/v1',           // API version path
  timeout: Duration(seconds: 15), // Request timeout
  retries: 3,                     // Automatic retry count
);

Error Handling

The SDK uses sealed exception classes for precise error handling. Use pattern matching to handle specific errors:

try {
  final booking = await connect.bookings.create({
    'property': '100',
    'daterange': {'start': '2026-06-01', 'end': '2026-06-07'},
    'adults': 2,
  });
} on OnvacaConnectException catch (e) {
  switch (e) {
    case AuthenticationException():
      print('API key is invalid: ${e.message}');
    case EntityNotFoundException(:final entityId):
      print('Entity not found: $entityId');
    case OperationNotSupportedException(:final slug):
      print('Operation not supported: $slug');
    case RateLimitException(:final retryAfter):
      print('Rate limited. Retry after: $retryAfter');
    case ProviderUnavailableException():
      print('PMS provider is temporarily unavailable');
    case UnknownApiException(:final statusCode, :final message):
      print('Unexpected error ($statusCode): $message');
  }
}

All exceptions have a statusCode and optional providerMessage from the upstream API.

Pagination

List operations return paginated results. Use EntityListOptions to control pagination:

final properties = await connect.properties.list(
  options: const EntityListOptions(
    page: 1,      // Page number (1-indexed)
    perPage: 20,  // Items per page
  ),
);

print('Total: ${properties.total}');
print('Current page: ${properties.page}');
print('Has next page: ${properties.hasNextPage}');

// Fetch next page
if (properties.hasNextPage) {
  final nextPage = await connect.properties.list(
    options: EntityListOptions(
      page: properties.page + 1,
      perPage: properties.perPage,
    ),
  );
}

License

MIT