chekin-npm-sdk

v1.0.4

Published

6 months ago

Official SDK for the Chekin API, providing easy access to property management, reservation handling, and guest check-in functionality.

Downloads

0High
0Medium
0Low

raulmorillo_chekin

chekin api sdk hotel property reservation guest typescript

Chekin NPM SDK

Official SDK for the Chekin API, providing easy access to property management, reservation handling, and guest check-in functionality.

🚀 Features

Authentication: Secure API key-based authentication
Property Management: Create and manage properties/housings
Reservation Management: Handle reservations and bookings
Guest Management: Dynamic guest forms and check-in process
TypeScript Support: Full TypeScript definitions included
Browser & Node.js: Works in both environments
CDN Ready: Available via unpkg for browser use

📦 Installation

NPM/Yarn

npm install chekin-npm-sdk
# or
yarn add chekin-npm-sdk

CDN (Browser)

<script src="https://unpkg.com/chekin-npm-sdk/dist/sdk.bundle.js"></script>

🔧 Quick Start

Node.js/TypeScript

import { ChekinSDK } from 'chekin-npm-sdk';

async function main() {
  // Initialize SDK
  const sdk = new ChekinSDK('YOUR_API_KEY_HERE');
  
  // Generate authentication token
  const token = await sdk.generateToken();
  console.log('Token generated:', token);
  
  // Now you can use properties, reservations, and guests services
  const property = await sdk.properties.createProperty(
    'Hotel Demo',
    'HOT',
    {
      external_id: 'ext-' + Date.now(),
      commercial_name: 'Hotel Demo Commercial',
      vatin: 'ES12345678',
      rooms_quantity: 10,
      location: { country: 'ES', city: 'Madrid' }
    }
  );
  
  console.log('Property created:', property);
}

main().catch(console.error);

Browser

<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/chekin-npm-sdk/dist/sdk.bundle.js"></script>
</head>
<body>
<script>
  async function initDemo() {
    // Initialize SDK
    const sdk = new window.ChekinNpmSDK.ChekinSDK('YOUR_API_KEY_HERE');
    
    // Generate token
    const token = await sdk.generateToken();
    console.log('SDK ready!', token);
    
    // Use the SDK services...
  }
  
  initDemo().catch(console.error);
</script>
</body>
</html>

📚 API Reference

Core SDK

`new ChekinSDK(apiKey: string)`

Creates a new SDK instance with the provided API key.

`generateToken(): Promise<string>`

Generates and stores an authentication token. Must be called before using any other methods.

After calling generateToken(), the following services become available:

sdk.properties - Property management
sdk.reservations - Reservation management
sdk.guests - Guest management

Properties Service

`sdk.properties.createProperty(name, type, options?)`

Creates a new property.

Parameters:

name (string) - Property name (required)
type (PropertyType) - Property type: "HOT", "APT", "HST", "B&B" (required)
options (object) - Additional options:
- external_id (string) - External identifier
- commercial_name (string) - Commercial name
- vatin (string) - VAT identification number
- rooms_quantity (number) - Number of rooms
- location (object) - Location details
  - country (string) - ISO country code
  - city (string) - City name

Example:

const property = await sdk.properties.createProperty(
  'Hotel Sunshine',
  'HOT',
  {
    external_id: 'hotel-001',
    commercial_name: 'Hotel Sunshine Resort',
    vatin: 'ES12345678',
    rooms_quantity: 50,
    location: { country: 'ES', city: 'Barcelona' }
  }
);

Reservations Service

`sdk.reservations.createReservation(housingId, guests, checkIn, checkOut, options?)`

Creates a new reservation.

Parameters:

housingId (string) - Property ID (required)
guests (number) - Number of guests (required)
checkIn (string) - Check-in date in YYYY-MM-DD format (required)
checkOut (string) - Check-out date in YYYY-MM-DD format (required)
options (object) - Additional options:
- source_name (string) - Booking source
- default_leader_full_name (string) - Lead guest name
- default_invite_email (string) - Guest email
- booking_reference (string) - External booking reference

Example:

const reservation = await sdk.reservations.createReservation(
  property.id,
  2,
  '2025-12-01',
  '2025-12-07',
  {
    source_name: 'Booking.com',
    default_leader_full_name: 'John Doe',
    default_invite_email: '[email protected]'
  }
);

Guests Service

`sdk.guests.getGuestSchema(payload)`

Retrieves the dynamic guest form schema based on property and reservation details.

Parameters:

payload (object) - Request payload:
- reservation_id (string) - Reservation ID (required)
- Additional fields as needed for dynamic form generation

Example:

const schema = await sdk.guests.getGuestSchema({
  reservation_id: reservation.id
});

// Use schema.default to render dynamic form
schema.default.forEach(field => {
  console.log(field.name, field.type, field.label);
});

`sdk.guests.createGuest(payload)`

Creates a guest with the provided form data.

Parameters:

payload (object) - Guest data:
- reservation_id (string) - Reservation ID (required)
- Additional fields from the dynamic form

Example:

const guest = await sdk.guests.createGuest({
  reservation_id: reservation.id,
  full_name: 'John Doe',
  email: '[email protected]',
  phone: '+1234567890',
  // ... other fields from dynamic form
});

`sdk.guests.updateGuest(id, updates)`

Updates an existing guest.

Parameters:

id (string) - Guest ID (required)
updates (object) - Any subset of fields from createGuest

Only the fields provided in updates are validated and updated.

Example:

const updatedGuest = await sdk.guests.updateGuest(guest.id, {
  phone: '+9876543210',
  email: '[email protected]'
});

`sdk.guests.createPoliceAccount(name, username, password, country, options?)`

Creates a new police account associated with a property manager or accommodation.

Parameters:

name (string) - Account name (required)
username (string) - Username (required)
password (string) - Password (required)
country (string, ISO 3166-1 alpha-2) - Country code (required)
options (object) - Optional settings:
- email (string) - Email address
- station_code (string) - Police station code
- is_active (boolean, default true) - Account status

Example:

const policeAccount = await sdk.guests.createPoliceAccount(
  'Madrid Police Station',
  'madrid_police',
  'securePassword123',
  'ES',
  {
    email: '[email protected]',
    station_code: 'MAD001',
    is_active: true
  }
);

`sdk.guests.createStatsAccount(name, contactEmail, country, options?)`

Creates a new statistical account (for example, to report tourist data to a national statistics agency).

Parameters:

name (string) - Account name (required)
contactEmail (string) - Contact email (required)
country (string, ISO 3166-1 alpha-2) - Country code (required)
options (object) - Optional settings:
- region (string) - Region name
- municipality (string) - Municipality name
- is_active (boolean) - Account status

Example:

const statsAccount = await sdk.guests.createStatsAccount(
  'Madrid Tourism Statistics',
  '[email protected]',
  'ES',
  {
    region: 'Community of Madrid',
    municipality: 'Madrid',
    is_active: true
  }
);

`sdk.guests.forcePoliceReportSending(reservationId, options?)`

Forces the sending of a police report for a specific reservation.

Parameters:

reservationId (string) - Reservation ID (required)
options (object) - Optional settings:
- force (boolean, default true) - Force sending flag
- comment (string) - Reason for manual resend
- policeAccountId (string) - Specify a police account for this operation

Returns: An object containing:

status (string) - Operation status
sent_at (string, ISO date) - Timestamp when sent
police_reference (string) - Police reference number

Example:

const reportResult = await sdk.guests.forcePoliceReportSending(
  reservation.id,
  {
    force: true,
    comment: 'Manual resend requested by property manager',
    policeAccountId: policeAccount.id
  }
);

console.log('Report status:', reportResult.status);
console.log('Sent at:', reportResult.sent_at);
console.log('Police reference:', reportResult.police_reference);

🌍 Browser Support

The SDK works in all modern browsers and includes:

ES5+ compatibility
Promise-based API
TypeScript definitions
Global window.ChekinNpmSDK object when loaded via CDN

🔒 Authentication

The SDK uses API key authentication. Contact Chekin to obtain your API credentials:

Test Environment: api-ng.chekintest.xyz
Production Environment: Contact support for details

🔥 Interactive Demo

Check out the included demo.html file for a complete working example that demonstrates:

SDK initialization and authentication
Property creation with form validation
Reservation management
Dynamic guest forms with real-time schema updates
Complete error handling and logging

🛠️ Development

This SDK is built with:

TypeScript for type safety
Rollup for bundling
Native Fetch API for HTTP requests
Modular architecture for easy maintenance

Build from source:

git clone <repository>
cd chekin-npm-sdk
npm install
npm run build

📝 Error Handling

The SDK throws descriptive errors for:

Authentication failures
Validation errors
API errors
Network issues

try {
  const property = await sdk.properties.createProperty(/* ... */);
} catch (error) {
  console.error('Property creation failed:', error.message);
}

📄 License

MIT © Chekin

🤝 Support

For technical support and API access, please contact Chekin support.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Chekin NPM SDK

🚀 Features

📦 Installation

NPM/Yarn

CDN (Browser)

🔧 Quick Start

Node.js/TypeScript

Browser

📚 API Reference

Core SDK

new ChekinSDK(apiKey: string)

generateToken(): Promise<string>

Properties Service

sdk.properties.createProperty(name, type, options?)

Reservations Service

sdk.reservations.createReservation(housingId, guests, checkIn, checkOut, options?)

Guests Service

sdk.guests.getGuestSchema(payload)

sdk.guests.createGuest(payload)

sdk.guests.updateGuest(id, updates)

sdk.guests.createPoliceAccount(name, username, password, country, options?)

sdk.guests.createStatsAccount(name, contactEmail, country, options?)

sdk.guests.forcePoliceReportSending(reservationId, options?)

🌍 Browser Support

🔒 Authentication

🔥 Interactive Demo

🛠️ Development

Build from source:

📝 Error Handling

📄 License

🤝 Support

`new ChekinSDK(apiKey: string)`

`generateToken(): Promise<string>`

`sdk.properties.createProperty(name, type, options?)`

`sdk.reservations.createReservation(housingId, guests, checkIn, checkOut, options?)`

`sdk.guests.getGuestSchema(payload)`

`sdk.guests.createGuest(payload)`

`sdk.guests.updateGuest(id, updates)`

`sdk.guests.createPoliceAccount(name, username, password, country, options?)`

`sdk.guests.createStatsAccount(name, contactEmail, country, options?)`

`sdk.guests.forcePoliceReportSending(reservationId, options?)`