@getcircuit/engine-client

@getcircuit/engine-client

Package for consuming the Circuit Engine API via JavaScript. Failed requests are automatically retried up to 3 times, via p-retry.

Using

Initializing

First we need to initialize the client with some important information such as:

• the base url for the Circuit Engine API
• a method to return the user's token, if using a private API method.
• some environment variables.

import { createEngineClient } from '@getcircuit/engine-client'

const baseUrl = process.env.FIREBASE_EMULATOR
  ? `http://localhost:3333/rest`
  : process.env.FIREBASE_ENV !== 'production'
  ? `https://staging-api.getcircuit.com/rest`
  : `https://api.getcircuit.com/rest`

// Required
const engineClient = createEngineClient({
  baseUrl,
  // Optional. Only used for private APIs.
  getToken: () => '',
  env: {
    FEATURE_ENVIRONMENT: 'testing_environment_flag',
  },
  // Optional error handler. Useful to log errors to better debug issues.
  onError(error) {
    trackError(error)
  },
})

Dealing with errors

The onError method can receive any kind of errors and exceptions. However, engine-client differentiates between two types of errors:

• UnknownError
• EngineResponseError

export type UnknownError = Error & {
  origin: 'unknown'
  status?: number
  response?: EngineResponse
  request?: EngineRequest
}

export type EngineResponseError = Error & {
  origin: 'engine'
  status: number
  response: EngineResponseWithError<ErrorDetail>
  request: EngineRequest
}

EngineResponseErrors are dispatched whenever a API request was received and answered by the server, but something went wrong. In other words, if the status of the response is not in the 200-299 status code range. EngineResponseError are thrown to facilitate error handling via catch blocks or .catch() method. A helper utility handleEngineError is provided for running a piece of code in case if what's been thrown is an EngineResponseError.

import {
  createEngineClient,
  handleEngineError,
} from '@getcircuit/engine-client'

import type { CreateMemberErrorDetail } from '@getcircuit/engine-client'

const EngineClient = createEngineClient(/* ... */)

EngineClient.createMember(/* { ... } */)
  .catch(
    handleEngineError<CreateMemberErrorDetail>((error) => {
      // `error` is an instance of EngineResponseError<CreateMemberErrorDetail>
      // Has error.status, error.response, error.request, etc.
    }),
  )
  .catch((err) => {
    // Other errors are handled here.
  })

However, generic errors and exceptions can also happen, be it due to a malformed response, a client misconfiguration, etc. These can be caught via a usual catch block or .catch() method, but without using the handleEngineError mentioned above. While is difficult to provide relevant data to help debug generic errors, engine-client will add the response, request and status code to the error object.

To facilitate the usage with typescript, a handleUnknownError method is also provided to properly type the error object with the extra response, request, and status properties:

import {
  createEngineClient,
  handleEngineError,
  handleUnknownError,
} from '@getcircuit/engine-client'

const EngineClient = createEngineClient(/* ... */)

EngineClient.createMember(/* { ... } */)
  .catch(
    handleEngineError((error) => {
      // `error` is a EngineResponseError
      // Has error.status, error.response, error.request, etc.
    }),
  )
  .catch(
    handleUnknownError((error) => {
      // `error` is unknown
      // but may have error.status, error.response, error.request, etc.
    }),
  )

Methods

After initializing the client, we're ready to use the methods to our hearts desires.

engineClient.importQueries()
engineClient.createUser()
engineClient.createMember()
engineClient.activateUser()
engineClient.optimizePlan()
engineClient.updateStripeSubscription()
engineClient.searchAddress()
engineClient.geocodeStop()

Contributing

How it works

The createEngineClient method grabs all the exported methods of src/methods/index.ts, all of which receive a context value as their first argument, and binds them to the client's context. Think this as instantiating a new object of a certain class. However, we don' deal with the this reference, as things can get very messy with them. Instead, we create a new object for the context and then create a copy of each method bound to that object.

Simplified example:

function CreateUser(context, { email }) {
  return context.request('/createUser', { json: { email } })
}

const Methods = {
  CreateUser,
}

function createEngineClient() {
  const context = {
    request: () => {},
  }

  return {
    // this binds the first argument to the object referenced by `context`
    CreateUser: CreateUser.bind(undefined, context),
  }
}

// ...

const client = createEngineClient()

client.createUser('[e-mail]')