{"id":25570,"library":"faros-js-client","title":"Faros API Client","description":"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.","status":"active","version":"0.8.9","language":"javascript","source_language":"en","source_url":"https://github.com/faros-ai/faros-js-client","tags":["javascript","api-client","typescript","faros"],"install":[{"cmd":"npm install faros-js-client","lang":"bash","label":"npm"},{"cmd":"yarn add faros-js-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add faros-js-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for GraphQL queries and mutations","package":"graphql","optional":true}],"imports":[{"note":"Named export, not default. Available since v0.1.","wrong":"import FarosClient from 'faros-js-client'","symbol":"FarosClient","correct":"import { FarosClient } from 'faros-js-client'"},{"note":"TypeScript/ESM only – no CommonJS export. Use import syntax.","wrong":"const { QueryBuilder } = require('faros-js-client')","symbol":"QueryBuilder","correct":"import { QueryBuilder } from 'faros-js-client'"},{"note":"Type import required for TypeScript. Not available as runtime value.","wrong":"import { FarosClientConfig } from 'faros-js-client'","symbol":"FarosClientConfig","correct":"import type { FarosClientConfig } from 'faros-js-client'"}],"quickstart":{"code":"import { FarosClient, QueryBuilder } from 'faros-js-client';\n\nconst faros = new FarosClient({\n  url: 'https://prod.api.faros.ai',\n  apiKey: process.env.FAROS_API_KEY ?? '',\n});\n\nconst query = `{\n  tms {\n    tasks(first: 10) {\n      nodes {\n        uid\n      }\n    }\n  }\n}`;\n\nasync function run() {\n  const data = await faros.gql('default', query);\n  console.log(JSON.stringify(data, null, 2));\n\n  const qb = new QueryBuilder('example-origin');\n  const mutations = [\n    qb.upsert({\n      compute_Application: {\n        name: 'my-app',\n        platform: 'kubernetes',\n      },\n    }),\n  ];\n  await faros.sendMutations('default', mutations);\n}\nrun().catch(console.error);","lang":"typescript","description":"Initializes FarosClient, executes a GraphQL query, and upserts a model using QueryBuilder."},"warnings":[{"fix":"Update Node.js and npm to meet minimum versions.","message":"Node.js >=22 and npm >=11.10.0 required as of v0.8.0.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Pass apiKey explicitly in constructor options, use process.env.FAROS_API_KEY.","message":"API key must be provided via apiKey option; environment variable is not auto-read.","severity":"gotcha","affected_versions":">=0.1"},{"fix":"Always provide an origin string to new QueryBuilder('my-origin').","message":"QueryBuilder constructor without origin is deprecated.","severity":"deprecated","affected_versions":">=0.5.0"},{"fix":"Wrap single mutation in an array: faros.sendMutations('default', [mutation]).","message":"sendMutations now expects an array of mutation strings (v0.4.0 changed from single mutation).","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Use conflict override to manage constraints: qb.upsert({...}, { constraint: '...' }).","message":"QueryBuilder.upsert automatically adds origin to mutations – do not override origin field manually.","severity":"gotcha","affected_versions":">=0.2"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use import { FarosClient } from 'faros-js-client' (with curly braces).","cause":"Importing FarosClient as default export instead of named export.","error":"TypeError: faros_js_client_1.FarosClient is not a constructor"},{"fix":"Install package with npm i faros-js-client and use import statements; this package does not support require().","cause":"Missing or incorrect package installation, or using CommonJS require() with ESM-only package.","error":"Module not found: Error: Can't resolve 'faros-js-client'"},{"fix":"Pass apiKey to FarosClient constructor: new FarosClient({ url: '...', apiKey: '...' }).","cause":"FarosClient instantiated without apiKey option.","error":"Missing required parameter: apiKey"},{"fix":"Ensure QueryBuilder is created with an origin string and that upsert uses model references correctly.","cause":"Mutation missing origin reference or QueryBuilder not properly constructed.","error":"GraphQL error: Variable '$origin' of type 'String!' must be defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}