Compose a high level API

[davesag]

The low level API is problematic to say the least.

1. potentially unstable due to being based on unofficial documentation, and trial and error,

2. there's many endpoints that return overlapping or irrelevant, or even inaccurate data.

   For example

   • the car's id is a number that's longer than javascript's number object allows.
     The API itself recognises this and returns an idS field which is a string version of the `id.

   • It uses metric for temperature and imperial for distance (presumably because my GUI is set to Metric) but it would be nicer if distance was also reported in metric if the user's GUI settings are metric.

3. the API does not prevent you from issuing commands to the car before it's been woken up

4. the API does not prevent you from doing things like trying to open a sunroof on a car without a sunroof.

A better solution would be to spec out a preferred high-level API, say called 'simple-node-tesla' that uses this.

const Tesla = async (username, password) => {
  const token = password
    ? await api.oauth.({ username, password, clientId, clientSecret })
    : username

  return {
    loggedIn: Boolean(token),
    vehicles: () => {
      const { response: cars } = await api.vehicles.vehicles({ token })

      return cars.map(car => ({
        ...car,
        siblings: cars.filter(({ idS }) => idS !== car.idS),
        // then a handy set of functions
        // wrapped up with logic preventing commands when car is not awake,
        // and that manages things like refreshing tokens, and throttling api limits.
        // and which manages a cache of the state of the car
        wake: async () => api.vehicles.wake({ id: car.idS, token }),
        beep: async () => api.vehicles.beepHorn({ id: car.idS, token }),
        flash: async () => api.vehicles.flashLights({ id: car.idS, token }),
        serviceHistory: async () => api.vehicles. serviceHistory({ id: car.idS, token }),
       // etc
      }))
    }
  }
}

Then used like

const Tesla = require('simple-node-tesla')

const client = Tesla(username, password) // or token if you already have an access token
const[myCar] = await client.vehicles()
await myCar.wake()
const location = await myCar.location()
const serviceHistory = await myCar.serviceHistory()
await myCar.beep()
await myCar.flash()