aletheia-safety

Node.js SDK for the ALETHEIA Safety Database API — chemical safety data for 1,800+ compounds, 950+ materials, and 520+ consumer products.

Install

npm install aletheia-safety

Quick Start

import { Aletheia } from 'aletheia-safety';

// Free tier (500 requests/day per IP)
const client = new Aletheia();

// Or with an API key for higher limits
const client = new Aletheia({ apiKey: 'aletheia_live_…' });

Usage

Look up compounds

// By HQ ID
const glyphosate = await client.compound('hq-c-org-000001');
console.log(glyphosate.name); // "Glyphosate"

// By CAS number
const bpa = await client.compoundByCas('80-05-7');

// With safety context
const risk = await client.compound('hq-c-org-000001', { context: 'human_adult' });

// Batch lookup (up to 20)
const results = await client.batch(['hq-c-org-000001', 'hq-c-org-000005']);

Search

// Full-text search across all entity types
const results = await client.search('sodium');

// Filter by type
const compounds = await client.search('sodium', { type: 'compound', limit: 10 });

// Filter by risk level and context
const highRisk = await client.filter({ risk: 'high', context: 'food_contact' });

// Filter by regulatory agency
const epa = await client.filter({ agency: 'EPA', yearMin: 2020 });

Compare compounds

// Side-by-side comparison (2-5 compounds)
const comparison = await client.compare(
  ['hq-c-org-000001', 'hq-c-org-000005'],
  { context: 'human_adult' }
);

Explore relationships

// Direct relationships
const rels = await client.relationships('hq-c-org-000001');

// Multi-hop graph traversal
const graph = await client.graph('hq-c-org-000001', { depth: 2 });
console.log(`${graph.nodes.length} nodes, ${graph.edges.length} edges`);

Regulatory data

const reg = await client.regulatory('hq-c-org-000001');
const agencies = await client.regulatoryAgencies();
const iarc = await client.regulatoryByAgency('IARC');

Exposure sources

const sources = await client.foundIn('hq-c-org-000001');
const categories = await client.foundInCategories();
const food = await client.foundInByCategory('Food');

Products & Materials

const products = await client.products({ limit: 50 });
const product = await client.product('hq-p-hom-000001');

const materials = await client.materials({ limit: 50 });
const material = await client.material('hq-m-str-000001');

Fragrance ingredients

const fragrances = await client.fragrance({ limit: 50 });
const classes = await client.fragranceClasses();
const results = await client.fragranceSearch('lavender');

Embeddable badge

const url = client.badgeUrl('hq-c-org-000001');
// Use in HTML: <img src="${url}" alt="Safety badge"/>

Key management

const status = await client.keyStatus();
console.log(`Tier: ${status.tier}, Used: ${status.usage.today}`);

// Rotate a compromised key (client auto-updates)
const result = await client.keyRotate();
console.log(`New key: ${result.key}`);

// Usage history
const usage = await client.keyUsage({ days: 14 });
usage.usage.forEach(d => console.log(`${d.date}: ${d.requests} requests`));

Watchlist (Developer+)

// Add compounds to your watchlist
await client.watchlistAdd(['hq-c-org-000001', 'hq-c-org-000033']);

// List watched compounds with enrichment
const watched = await client.watchlist();

// Remove a compound
await client.watchlistRemove('hq-c-org-000033');

Changelog (Developer+)

// Recent regulatory/data changes
const changes = await client.changelog({ limit: 20 });

// Filter by date and compound
const recent = await client.changelog({ since: '2026-03-01', compoundId: 'hq-c-org-000001' });

Raw data access (Developer+)

const raw = await client.compoundRaw('hq-c-org-000001');
const rawProduct = await client.productRaw('hq-p-hom-000001');

Tiers

| Tier | Requests/Day | Price | |------|-------------|-------| | Public | 500/IP | Free | | Developer | 10,000 | $29/mo | | Pro | 100,000 | $99/mo | | Enterprise | Unlimited | Contact |

Get an API key at aletheia.holisticquality.io/pricing.

Error Handling

import { Aletheia, AletheiaError, RateLimitError } from 'aletheia-safety';

const client = new Aletheia();

try {
  const compound = await client.compound('invalid-id');
} catch (e) {
  if (e instanceof RateLimitError) {
    console.log('Rate limit exceeded — wait or upgrade');
  } else if (e instanceof AletheiaError) {
    console.log(`API error ${e.status}: ${e.message}`);
  }
}

Requirements

• Node.js 18+ (uses native fetch)

License

MIT