Registry / devops / faros-js-client

faros-js-client

library0.8.9jsnpmunverified

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.

devops http-networking serialization data

npm install faros-js-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FAROS-JS-CLIENT

faros-js-client

devopsjavascriptv0.8.9

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

FarosClient

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

✗ import FarosClient from 'faros-js-client'

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

QueryBuilder

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

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

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

FarosClientConfig

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

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

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

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);

Debug

Known issues

breakingNode.js >=22 and npm >=11.10.0 required as of v0.8.0.

fix

Update Node.js and npm to meet minimum versions.

affects: >=0.8.0

gotchaAPI 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.

affects: >=0.1

deprecatedQueryBuilder constructor without origin is deprecated.

fix

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

affects: >=0.5.0

breakingsendMutations 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]).

affects: >=0.4.0

gotchaQueryBuilder.upsert automatically adds origin to mutations – do not override origin field manually.

fix

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

affects: >=0.2

Errors

Common errors & fixes

TypeError: faros_js_client_1.FarosClient is not a constructor

Importing FarosClient as default export instead of named export.

fix

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

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

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().

Missing required parameter: apiKey

FarosClient instantiated without apiKey option.

fix

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

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

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.

Upgrade

Version history

0.8.9latest on npm

Audit

Dependencies

graphqloptionalPeer dependency for GraphQL queries and mutations

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/faros-ai/faros-js-client ↗

packagehttps://www.npmjs.com/package/faros-js-client ↗

homepagehttps://www.faros.ai ↗