@biocomputingup/api-clients

A robust TypeScript library providing schema-validated API clients for querying and verifying biological resource cross-references (Xrefs).

This library contains dedicated clients for three major biological and chemical databases:

1. Cellosaurus — Cell line database client.
2. ChEBI (Chemical Entities of Biological Interest) — Chemical structures and annotation database client.
3. PubChem — Chemical substances and compounds database client.

All responses are validated at runtime using Zod schemas to ensure high type-safety and reliability.

Installation

Install the package and its peer dependency zod using your preferred package manager:

npm install @biocomputingup/api-clients zod
# or
yarn add @biocomputingup/api-clients zod
# or
pnpm add @biocomputingup/api-clients zod

Import Options

The library is built to support both CommonJS and ESM. You can import all clients from the main entrypoint or import specific clients separately via subpath exports to minimize bundle sizes.

Standard Import

import { 
  CellosaurusClient, 
  ChebiClient, 
  PubChemClient,
  EntryNotFoundException,
  UnknownHttpException
} from "@biocomputingup/api-clients";

Subpath Imports

// Import only the Cellosaurus client
import { CellosaurusClient } from "@biocomputingup/api-clients/clients/cellosaurus";

// Import only the ChEBI client
import { ChebiClient } from "@biocomputingup/api-clients/clients/chebi";

// Import only the PubChem client
import { PubChemClient } from "@biocomputingup/api-clients/clients/pubchem";

Clients Guide

1. Cellosaurus Client

The CellosaurusClient allows you to fetch detailed records from the Cellosaurus database.

Configuration Options

interface CellusaurusClientOptions {
  baseAPIUrl: string; // Defaults to "https://api.cellosaurus.org"
}

API Methods

• getCellosaurusEntry(id: string): Promise<CellosaurusResponseType>
  Fetches the full entry details for a cell line by its accession ID (e.g., CVCL_0030).
• getCellosaurusEntryName(id: string): Promise<string | null>
  A helper method that fetches the entry and retrieves the longest synonym name associated with the cell line. Returns null if not found or on failure.

Example Usage

import { CellosaurusClient, EntryNotFoundException } from "@biocomputingup/api-clients";

const client = new CellosaurusClient();

try {
  // Fetch full HeLa cell line data
  const entry: CellosaurusResponseType = await client.getCellosaurusEntry("CVCL_0030");
  console.log("Cell line list:", entry.Cellosaurus["cell-line-list"]);

  // Get the longest synonym name
  const name = await client.getCellosaurusEntryName("CVCL_0030");
  console.log("Cell line name:", name); // "Henrietta Lacks cells"
} catch (error) {
  if (error instanceof EntryNotFoundException) {
    console.error("Entry not found in Cellosaurus");
  } else {
    console.error("An unexpected error occurred:", error);
  }
}

2. ChEBI Client

The ChebiClient queries chemical entities of biological interest from the EBI ChEBI database backend.

Configuration Options

interface ChEBIClientOptions {
  baseUrl: string; // E.g., "https://www.ebi.ac.uk/chebi/backend/api/"
}

API Methods

• getCompound(chebiId: string): Promise<CompoundType>
  Fetches details of a compound by its ChEBI ID (e.g., CHEBI:27732).

Example Usage

import { ChebiClient } from "@biocomputingup/api-clients";

const client = new ChebiClient({
  baseUrl: "https://www.ebi.ac.uk/chebi/backend/api/",
}, console); // Optional second argument: Logger interface (defaults to console)

try {
  const compound = await client.getCompound("CHEBI:27732");
  console.log("Compound Name:", compound.name); // "caffeine"
  console.log("Definition:", compound.definition);
  console.log("Star Rating:", compound.stars);
} catch (error) {
  console.error("Failed to query ChEBI:", error);
}

3. PubChem Client

The PubChemClient interacts with the PubChem PUG REST API.

Configuration Options

interface PubChemClientOptions {
  baseAPIUrl: string; // Defaults to "https://pubchem.ncbi.nlm.nih.gov/rest/pug"
}

API Methods

• getCompound(id: string, props?: PubChemCompoundKey[]): Promise<PubChemCompoundType>
  Fetches specified properties for a compound by its CID (e.g., 2244).
  • props defaults to ["Title", "SMILES", "InChI", "InChIKey"].
  • Note: In the current version, this method returns the compound properties matching index 1 in the API response table.
• getSubstance(id: string): Promise<void>
  Queries substance data by SID (e.g., 528403372) and writes the raw response to /tmp/pubchem-sid.json.

Example Usage

import { PubChemClient } from "@biocomputingup/api-clients";

const client = new PubChemClient();

try {
  // Fetch properties for Aspirin (CID: 2244)
  const compound = await client.getCompound("2244");
  console.log("CID:", compound.CID);
  console.log("Title:", compound.Title); // "Aspirin"
  console.log("SMILES:", compound.SMILES);
} catch (error) {
  console.error("Error querying PubChem:", error);
}

Error Handling

Standard exceptions are thrown across all clients to simplify error handling logic.

EntryNotFoundException

Thrown when the requested identifier is not found on the remote database (equivalent to an HTTP 404).

• Properties:
  • message: Description containing client name, identifier, and operation.

UnknownHttpException

Thrown when a non-ok HTTP status (other than 404) is returned.

• Properties:
  • message: Status code, URL requested, and response body payload.

import { EntryNotFoundException, UnknownHttpException } from "@biocomputingup/api-clients";

// In your catch blocks:
if (error instanceof EntryNotFoundException) {
  // Handle 404 cases
} else if (error instanceof UnknownHttpException) {
  // Handle other API issues
}

Development & Building

The project uses vite-plus for linting, testing, formatting, and packing.

1. Install Dependencies

vp install

2. Run Unit Tests

vp test

3. Build & Pack Library

Compile and pack the library into ESM/CJS bundles under the dist/ directory:

vp pack

4. Code Quality

Run checks to verify formatting, types, and lints:

vp check