Diffbot TypeScript Library

TypeScript client library for Diffbot APIs. This is a port of the diffbot-python public library API.

Installation

pnpm add diffbot-typescript

Requires Node.js 18+ (native fetch).

Usage

In TypeScript, all API functions are async. Use await or for await where the Python SDK used sync iteration.

Create a client once, then pass it to the API functions you need. Import only the functions you use so bundlers can tree-shake unused code.

Authentication

import{DiffbotClient,extract,resolveToken}from"diffbot-typescript";constdb=newDiffbotClient({token: resolveToken()});constdata=awaitextract(db,"https://www.example.com");awaitdb.close();

Token resolution order:

1. Explicit argument to resolveToken(token)
2. DIFFBOT_API_TOKEN environment variable
3. DIFFBOT_API_TOKEN=... line in ~/.diffbot/credentials

Extract structured content

import{DiffbotClient,extract}from"diffbot-typescript";constdb=newDiffbotClient({token: "YOUR_TOKEN"});constdata=awaitextract(db,"https://www.example.com");

Ask Diffbot LLM

import{ask}from"diffbot-typescript";forawait(constchunkofask(db,[{role: "user",content: "What's the capital of France?"}])){process.stdout.write(chunk);}

Crawl a site

import{crawl}from"diffbot-typescript";forawait(consteventofcrawl(db,"https://www.example.com",{hops: 1})){console.log(event);}

Query the Knowledge Graph

import{dql}from"diffbot-typescript";constresults=awaitdql(db,'type:Organization name:"Diffbot"');

Web Search

import{webSearch}from"diffbot-typescript";constresults=awaitwebSearch(db,"diffbot knowledge graph");for(constrofresults.search_resultsasArray<Record<string,unknown>>){console.log(r.score,r.title,r.pageUrl);}

Entities (NLP)

import{entities}from"diffbot-typescript";constresult=awaitentities(db,"Apple CEO Tim Cook announced record quarterly earnings.");

Automatic cleanup with await using

DiffbotClient supports explicit resource management for automatic cleanup:

import{DiffbotClient,extract}from"diffbot-typescript";await using db=newDiffbotClient({token: "YOUR_TOKEN"});constdata=awaitextract(db,"https://www.example.com");

Python ↔ TypeScript API mapping

Python	TypeScript
resolve_token()	resolveToken()
crawl_list_jobs()	crawlListJobs()
crawl_get_job()	crawlGetJob()
crawl_delete_job()	crawlDeleteJob()
dql_parallel()	dqlParallel()
dql_fetch_ontology()	dqlFetchOntology()
dql_refresh_ontology()	dqlRefreshOntology()
web_search()	webSearch()

Development

pnpm install
pnpm test
pnpm build

Live integration tests (requires DIFFBOT_API_TOKEN):

pnpm test:live

License

MIT