Map reservations

StayBind reduces every reservation, from any source, to one CanonicalReservation. For a custom OTA, a small mapReservation function does that translation. You have two options: send the default shape and it works as-is, or send your own shape and StayBind configures a mapper for it.

The default shape

Out of the box, the mapper reads these fields from each raw reservation:

Writing a custom mapper

If your payload differs, the mapper is a single pure function: raw payload in, canonical reservation out. This is the only per-partner code, everything else (HTTP, retries, signature checks, ingestion) is shared.

type MapReservation = (raw: unknown) => CanonicalReservation;

const mapReservation: MapReservation = (raw) => {
  const r = raw as MyOtaReservation;
  return {
    provider: "partner",
    externalChannel: "my-ota",
    providerResId: r.event_id,        // unique per delivery
    providerBookingId: r.booking_ref, // stable across revisions
    providerRoomTypeId: r.room_code,
    status: r.cancelled ? "cancelled" : r.amended ? "modified" : "new",
    dateRange: { checkIn: r.arrival, checkOut: r.departure },
    guest: {
      name: r.customer.full_name,
      email: r.customer.email,
      phone: r.customer.mobile,
      adults: r.pax.adults ?? 1,
      children: r.pax.children ?? 0,
    },
    total: { amount: r.total_paise, currency: "INR" },
    raw, // keep the original for the audit trail
  };
};

The full set of canonical fields (including the optional ackRef, ratePlanId, and bookedAt) is documented in the canonical model.

Registering the adapter

On the StayBind server, your OTA is registered as a PartnerChannelAdapter with your mapper (and, recommended, a signature verifier):

new PartnerChannelAdapter({
  mapReservation,
  // verify the inbound webhook against the connection's webhookSecret
  verifySignature: (event, secret) => event.signature === secret,
});

This is platform-side wiring; as the OTA you provide the payload shape (or confirm you'll send the default), and the StayBind team or a self-hosting operator registers it.

Credentials

A connection stores only a pointer (secretRef); the actual secrets live in StayBind's secret store, never in the database. Your connection needs three values:

In the default deployment these are read from an environment variable named CHANNEL_SECRET_<REF> holding a JSON object:

{ "baseUrl": "https://api.my-ota.com", "apiKey": "…", "webhookSecret": "…" }

The secret store is an interface, so a production deployment can swap the env backend for a vault (KMS, Doppler, Vault) without changing any call site. The sync engine only ever sees the resolved credentials.

Putting it together

Next: Sync availability out.