Skip to main content

SDKs Overview

Official client libraries for integrating with the LosCenotes Partner API.

Available SDKs​

LosCenotes provides official SDKs for popular programming languages, making integration faster and more reliable.

LanguagePackageVersionStatus
TypeScript/JavaScript@loscenotes/partner-sdk2.1.0✅ Stable
Pythonloscenotes-partner1.8.2✅ Stable
PHPloscenotes/partner-sdk1.5.1✅ Stable
Gogithub.com/loscenotes/partner-go0.9.0🚧 Beta
Javacom.loscenotes:partner-sdk0.8.0🚧 Beta
.NETLosCenotes.PartnerSDK0.7.0🚧 Beta

Quick Start​

TypeScript/JavaScript​

npm install @loscenotes/partner-sdk
import { LosCenotesClient } from '@loscenotes/partner-sdk';

const client = new LosCenotesClient({
  apiKey: 'sk_test_your_api_key',
  environment: 'sandbox'
});

const cenotes = await client.cenotes.list();

Python​

pip install loscenotes-partner
from loscenotes import LosCenotesClient

client = LosCenotesClient(
    api_key='sk_test_your_api_key',
    environment='sandbox'
)

cenotes = client.cenotes.list()

PHP​

composer require loscenotes/partner-sdk
<?php
use LosCenotes\LosCenotesClient;

$client = new LosCenotesClient([
    'apiKey' => 'sk_test_your_api_key',
    'environment' => 'sandbox'
]);

$cenotes = $client->cenotes->getList();
?>

Common Features​

All official SDKs share these features:

✅ Type Safety​

  • Full type definitions for requests and responses
  • IDE autocompletion and error detection
  • Compile-time validation where supported

✅ Error Handling​

  • Consistent error types across all SDKs
  • Detailed error messages with context
  • Built-in retry logic for transient failures

✅ Rate Limit Management​

  • Automatic rate limit detection

  • Exponential backoff retry strategy

  • Configurable retry behavior

  • Signature verification helpers

  • Event parsing and validation

  • Type-safe event handlers

✅ Testing Support​

  • Sandbox environment support
  • Mock clients for unit testing
  • Test data generation utilities

Configuration Options​

All SDKs support consistent configuration:

const client = new LosCenotesClient({
  // Required
  apiKey: 'sk_test_your_api_key',

  // Environment
  environment: 'sandbox', // or 'production'

  // Custom base URL (optional)
  baseURL: 'https://api-sandbox.loscenotes.com',

  // Request timeout (milliseconds)
  timeout: 30000,

  // Rate limiting
  rateLimitOptions: {
    maxRetries: 3,
    baseDelay: 1000,
    maxDelay: 30000,
    backoffFactor: 2
  },

  // Debug logging
  debug: false,

  // Custom HTTP client options
  httpClient: {
    headers: {
      'User-Agent': 'MyApp/1.0.0'
    }
  }
});

API Coverage​

All SDKs provide complete coverage of the LosCenotes API:

Core Resources​

  • Cenotes - List, get, search, availability
  • Reservations - CRUD, confirm, cancel, check-in, complete
  • Guests - Profiles and preferences
  • Payments - Process, refund, status

Management​

  • Auth - Verify API keys, refresh tokens
  • System - Health checks, status

Utilities​

  • Pricing - Calculate costs, apply discounts
  • Geography - States, municipalities
  • Currencies - Exchange rates, conversions

Error Handling​

Consistent error handling across all SDKs:

// TypeScript example
try {
  const cenote = await client.cenotes.get('invalid-id');
} catch (error) {
  if (error instanceof LosCenotesError) {
    console.log('API Error:', error.code);
    console.log('Message:', error.message);
    console.log('Status:', error.status);
    console.log('Details:', error.details);
  } else {
    console.log('Network/Other Error:', error.message);
  }
}
# Python example
try:
    cenote = client.cenotes.get('invalid-id')
except LosCenotesError as e:
    print(f"API Error: {e.code}")
    print(f"Message: {e.message}")
    print(f"Status: {e.status}")
    print(f"Details: {e.details}")
except Exception as e:
    print(f"Network/Other Error: {e}")

  payload,
  signature,
);


switch (event.type) {
  case 'reservation.created':
    handleReservationCreated(event.data.object);
    break;
  case 'reservation.confirmed':
    handleReservationConfirmed(event.data.object);
    break;
}

Testing Support​

Mock Clients​

import { MockLosCenotesClient } from '@loscenotes/partner-sdk/testing';

const mockClient = new MockLosCenotesClient();

// Mock responses
mockClient.cenotes.list.mockResolvedValue({
  success: true,
  data: [{ id: 'cenote-1', name: 'Test Cenote' }]
});

// Use in tests
const result = await mockClient.cenotes.list();
expect(result.data).toHaveLength(1);

Test Data Generators​

import { generateTestReservation } from '@loscenotes/partner-sdk/testing';

const testReservation = generateTestReservation({
  cenoteId: 'test-cenote-1',
  visitors: { adults: 2 },
  status: 'confirmed'
});

Pagination Helpers​

Consistent pagination across all SDKs:

// Auto-paginate through all results
const allCenotes = [];

for await (const cenote of client.cenotes.listAll({ isActive: true })) {
  allCenotes.push(cenote);
}

// Or collect all pages
const allPages = await client.cenotes.listAllPages({ isActive: true });
const allCenotes = allPages.flatMap(page => page.data);

Caching Support​

Built-in response caching:

const client = new LosCenotesClient({
  apiKey: 'sk_test_your_api_key',
  caching: {
    enabled: true,
    ttl: 300, // 5 minutes
    storage: 'memory' // or 'redis'
  }
});

// First call hits the API
const cenotes1 = await client.cenotes.list();

// Second call returns cached result
const cenotes2 = await client.cenotes.list();

Logging and Debugging​

Built-in logging for debugging:

const client = new LosCenotesClient({
  apiKey: 'sk_test_your_api_key',
  debug: true,
  logger: {
    level: 'debug',
    format: 'json'
  }
});

// Logs all requests and responses
const cenotes = await client.cenotes.list();

Performance Optimization​

Connection Pooling​

const client = new LosCenotesClient({
  apiKey: 'sk_test_your_api_key',
  httpClient: {
    keepAlive: true,
    maxSockets: 10,
    maxFreeSockets: 5
  }
});

Request Deduplication​

// Multiple identical requests will be deduplicated
const promises = Array.from({ length: 5 }, () =>
  client.cenotes.get('same-cenote-id')
);

const results = await Promise.all(promises);
// Only one actual HTTP request is made

Environment Variables​

All SDKs support environment variable configuration:

# .env file
LOSCENOTES_API_KEY=sk_test_your_api_key
LOSCENOTES_ENVIRONMENT=sandbox
LOSCENOTES_BASE_URL=https://api-sandbox.loscenotes.com
LOSCENOTES_TIMEOUT=30000
LOSCENOTES_DEBUG=true
// Auto-configured from environment
const client = new LosCenotesClient();

Migration Guide​

Upgrading SDKs​

# Check current version
npm list @loscenotes/partner-sdk

# Upgrade to latest
npm update @loscenotes/partner-sdk

# Check for breaking changes
npm run check-compatibility

Breaking Changes​

SDKs follow semantic versioning:

  • Major versions (2.0.0): Breaking changes, migration required
  • Minor versions (2.1.0): New features, backward compatible
  • Patch versions (2.1.1): Bug fixes, backward compatible

Community and Support​

Getting Help​

Contributing​

All SDKs are open source:

Community SDKs​

Community-maintained SDKs:

LanguageMaintainerStatus
Ruby@rubydevActive
Rust@rustaceanActive
Swift@swiftdevAlpha

Release Notes​

Latest Updates​

v2.1.0 (January 2025)

  • Added support for bulk operations
  • Improved error handling with context
  • Performance optimizations

v2.0.0 (December 2024)

  • Breaking: New authentication flow
  • Added TypeScript strict mode support
  • Improved rate limiting
  • New testing utilities

Roadmap​

Q1 2025​

  • GraphQL support
  • WebSocket real-time updates
  • Advanced caching strategies
  • Mobile SDK optimizations

Q2 2025​

  • Offline mode support
  • Enhanced testing tools
  • Performance monitoring
  • Security improvements

Next Steps​

Choose your preferred SDK and get started:

  • TypeScript SDK - For Node.js and browser applications
  • Python SDK - For Python applications and data science
  • PHP SDK - For PHP web applications and frameworks