smartcar

Smartcar Node SDK

The official Smartcar Node SDK.

Overview

The Smartcar API lets you read vehicle data (location, odometer) and send commands to vehicles (lock, unlock) using HTTP requests.

To make requests to a vehicle from a web or mobile application, the end user must connect their vehicle using Smartcar Connect. This flow follows the OAuth spec and will return a code which can be used to obtain an access token from Smartcar.

The Smartcar Node SDK provides methods to:

1. Generate the link to redirect to Connect.
2. Make a request to Smartcar with the code obtained from Connect to obtain an access and refresh token
3. Make requests to the Smartcar API to read vehicle data and send commands to vehicles using the access token obtained in step 2.

Before integrating with Smartcar's SDK, you'll need to register an application in the Smartcar Developer portal. If you do not have access to the dashboard, please request access.

Flow

• Create a new AuthClient object with your clientId, clientSecret, redirectUri.
• Redirect the user to Smartcar Connect using getAuthUrl with required scope or with one of our frontend SDKs.
• The user will login, and then accept or deny your scope's permissions.
• Handle the get request to redirectUri.
  • If the user accepted your permissions, req.query.code will contain an authorization code.
    • Use exchangeCode with this code to obtain an access object containing an access token (lasting 2 hours) and a refresh token (lasting 60 days).
      • Save this access object.
    • If the user denied your permissions, req.query.error will be set to "access_denied".
    • If you passed a state parameter to getAuthUrl, req.query.state will contain the state value.
• Get the user's vehicles with getVehicles.
• Create a new Vehicle object using a vehicleId from the previous response, and the access_token.
• Make requests to the Smartcar API.
• Use exchangeRefreshToken on your saved refreshToken to retrieve a new token when your accessToken expires.

Installation

npm install smartcar --save

Example

'use strict';

const smartcar = require('smartcar');
const express = require('express');

const app = express();

const port = 4000;

const client = new smartcar.AuthClient({
  clientId: '<Smartcar Client Id>', // fallback to SMARTCAR_CLIENT_ID ENV variable
  clientSecret: '<Smartcar Client Secret>', // fallback to SMARTCAR_CLIENT_SECRET ENV variable
  redirectUri: '<Your callback URI>', // fallback to SMARTCAR_REDIRECT_URI ENV variable
  mode: 'test', // launch Smartcar Connect in test mode
});

// Redirect to Smartcar Connect
app.get('/login', function(req, res) {
  const link = client.getAuthUrl(['read_vehicle_info']);

  // redirect to the link
  res.redirect(link);
});

// Handle Smartcar callback with auth code
app.get('/callback', async function(req, res, next) {
  let access;

  if (req.query.error) {
    // the user denied your requested permissions
    return next(new Error(req.query.error));
  }

  // exchange auth code for access token
  const tokens = await client.exchangeCode(req.query.code);
  // get the user's vehicles
  const vehicles = await smartcar.getVehicles(tokens.accessToken);
  // instantiate first vehicle in vehicle list
  const vehicle = new smartcar.Vehicle(
    vehicles.vehicles[0],
    tokens.accessToken
  );
  // get identifying information about a vehicle
  const attributes = await vehicle.attributes();
  console.log(attributes);
  // {
  //   "id": "36ab27d0-fd9d-4455-823a-ce30af709ffc",
  //   "make": "TESLA",
  //   "model": "Model S",
  //   "year": 2014
  //   "meta": {
  //     "requestId": "ada7207c-3c0a-4027-a47f-6215ce6f7b93"
  //   }
  // }
});

app.listen(port, () => console.log(`Listening on port ${port}`));

SDK Reference

For detailed documentation on parameters and available methods, please refer to the SDK Reference.

Contributing

To contribute, please:

1. Open an issue for the feature (or bug) you would like to resolve.
2. Resolve the issue and add tests in your feature branch.
3. Open a PR from your feature branch into develop that tags the issue.

To test:

npm run test

Note: In order to run tests locally the following environment variables would have to be set :

• E2E_SMARTCAR_CLIENT_ID - Client ID to be used.
• E2E_SMARTCAR_CLIENT_SECRET - Client secret to be used.
• E2E_SMARTCAR_AMT - AMT from dashboard for webhooks tests.
• E2E_SMARTCAR_WEBHOOK_ID - Webhook ID use in the webhook tests success case.

Your application needs to have https://example.com/auth set as a valid redirect URI

Supported Node.js Versions

Smartcar aims to support the SDK on all Node.js versions that have a status of "Maintenance" or "Active LTS" as defined in the Node.js Release schedule.

In accordance with the Semantic Versioning specification, the addition of support for new Node.js versions would result in a MINOR version bump and the removal of support for Node.js versions would result in a MAJOR version bump.