Faros API Client

0.8.9 verified Fri May 01 auth: no javascript

JavaScript/TypeScript client for the Faros API, an engineering intelligence platform that ingests data from DevOps tools. Current stable version is 0.8.9, released with active development and weekly releases. It provides a GraphQL client with query builder for constructing mutations, handles authentication via API keys, supports pagination (keyset, offset), batching, retries, and OIDC. Key differentiators include first-class TypeScript support, built-in GraphQL query builder that manages origin fields and conflict resolution on upserts, and a focus on data ingestion for engineering analytics. Requires Node.js >=22 and npm >=11.10.0.

Common errors

error TypeError: faros_js_client_1.FarosClient is not a constructor ↓

cause Importing FarosClient as default export instead of named export.

fix

Use import { FarosClient } from 'faros-js-client' (with curly braces).

error Module not found: Error: Can't resolve 'faros-js-client' ↓

cause Missing or incorrect package installation, or using CommonJS require() with ESM-only package.

fix

Install package with npm i faros-js-client and use import statements; this package does not support require().

error Missing required parameter: apiKey ↓

cause FarosClient instantiated without apiKey option.

fix

Pass apiKey to FarosClient constructor: new FarosClient({ url: '...', apiKey: '...' }).

error GraphQL error: Variable '$origin' of type 'String!' must be defined ↓

cause Mutation missing origin reference or QueryBuilder not properly constructed.

fix

Ensure QueryBuilder is created with an origin string and that upsert uses model references correctly.

Warnings

breaking Node.js >=22 and npm >=11.10.0 required as of v0.8.0. ↓

fix Update Node.js and npm to meet minimum versions.

gotcha API key must be provided via apiKey option; environment variable is not auto-read. ↓

fix Pass apiKey explicitly in constructor options, use process.env.FAROS_API_KEY.

deprecated QueryBuilder constructor without origin is deprecated. ↓

fix Always provide an origin string to new QueryBuilder('my-origin').

breaking sendMutations now expects an array of mutation strings (v0.4.0 changed from single mutation). ↓

fix Wrap single mutation in an array: faros.sendMutations('default', [mutation]).

gotcha QueryBuilder.upsert automatically adds origin to mutations – do not override origin field manually. ↓

fix Use conflict override to manage constraints: qb.upsert({...}, { constraint: '...' }).

Install

npm install faros-js-client

yarn add faros-js-client

pnpm add faros-js-client

Imports

FarosClient

wrong

import FarosClient from 'faros-js-client'

correct

import { FarosClient } from 'faros-js-client'

Named export, not default. Available since v0.1.

QueryBuilder

wrong

const { QueryBuilder } = require('faros-js-client')

correct

import { QueryBuilder } from 'faros-js-client'

TypeScript/ESM only – no CommonJS export. Use import syntax.

FarosClientConfig

wrong

import { FarosClientConfig } from 'faros-js-client'

correct

import type { FarosClientConfig } from 'faros-js-client'

Type import required for TypeScript. Not available as runtime value.

Quickstart

Initializes FarosClient, executes a GraphQL query, and upserts a model using QueryBuilder.

import { FarosClient, QueryBuilder } from 'faros-js-client';

const faros = new FarosClient({
  url: 'https://prod.api.faros.ai',
  apiKey: process.env.FAROS_API_KEY ?? '',
});

const query = `{
  tms {
    tasks(first: 10) {
      nodes {
        uid
      }
    }
  }
}`;

async function run() {
  const data = await faros.gql('default', query);
  console.log(JSON.stringify(data, null, 2));

  const qb = new QueryBuilder('example-origin');
  const mutations = [
    qb.upsert({
      compute_Application: {
        name: 'my-app',
        platform: 'kubernetes',
      },
    }),
  ];
  await faros.sendMutations('default', mutations);
}
run().catch(console.error);