afpnews-api

AfpNews API

A TypeScript client library for the AFP Core API. Provides authentication, document search, notification management, saved filters, and social story retrieval for both Node.js and browser environments.

Installation

Node.js

npm install afpnews-api

import { ApiCore } from 'afpnews-api'
// or CommonJS
const { ApiCore } = require('afpnews-api')

Browser (UMD)

<script src="https://unpkg.com/afpnews-api/dist/bundles/apicore.min.js"></script>

Browser (ESM)

import { ApiCore } from 'https://cdn.jsdelivr.net/npm/afpnews-api/dist/bundles/apicore.min.mjs'

Prerequisites

You need an API key or client credentials (client ID + secret) to connect. For user-authenticated requests, you also need a username and password.

Quick Start

import { ApiCore } from 'afpnews-api'

// Initialize with client credentials
const afp = new ApiCore({ clientId: 'your-id', clientSecret: 'your-secret' })

// Or with an API key
const afp = new ApiCore({ apiKey: 'your-api-key' })

// Optionally override the base URL
const afp = new ApiCore({ clientId: 'your-id', clientSecret: 'your-secret', baseUrl: 'https://custom-api.afp.com' })

Authentication

// Anonymous authentication (uses API key or client credentials)
await afp.authenticate()

// Authenticate with user credentials
await afp.authenticate({ username: 'user', password: 'pass' })

// Listen for token changes
afp.on('tokenChanged', (token) => {
  console.log(token)
  // { accessToken, refreshToken, tokenExpires, authType }
})

// Token is automatically refreshed when expired

Latest Documents

Get the most recent documents:

const { count, documents } = await afp.latest({ lang: 'fr', tz: 'Europe/Paris' })

Searching Documents

Basic Search

const { count, documents } = await afp.search()

Search with Parameters

const { count, documents } = await afp.search({
  query: 'Macron',
  langs: ['fr', 'en'],
  dateFrom: '2024-01-01',
  dateTo: '2024-12-31',
  size: 20,
  sortField: 'published',
  sortOrder: 'desc',
  tz: 'Europe/Paris',
  dateGap: '+1HOUR',
  startAt: 0,
  wantedFacets: { slug: { size: 10, minDocCount: 1 }, country: { size: 5, minDocCount: 1 } },
  sort: [{ sortField: 'published', sortOrder: 'desc' }]
})

Additional Filtering Parameters

Any extra key-value pair is passed as an additional query filter:

const { documents } = await afp.search({
  query: 'climate',
  country: 'fra',
  urgency: 3,
  slug: ['politics', 'economy']
})

You can also use include/exclude syntax:

const { documents } = await afp.search({
  country: { in: ['fra', 'deu'] },
  product: { exclude: ['photo'] }
})

Specify Response Fields

Pass an array of field names to limit the returned fields:

const { documents } = await afp.search({}, ['uno', 'title', 'published'])

Paginated Search

Use searchAll() to iterate over large result sets automatically:

for await (const doc of afp.searchAll({ size: 5000, query: 'climate' })) {
  console.log(doc.uno)
}

Query Syntax

The query parameter supports a boolean query DSL:

Syntax	Example
Simple term	Macron
Field search	title:Macron
AND	Macron AND Merkel
OR	title:Macron OR title:Merkel
NOT	Macron AND NOT country:fra
Parentheses	(title:Macron OR title:Merkel) AND country:fra
Quoted phrase	title:"climate change"
Implicit AND	Macron France (space-separated terms)

Retrieving a Single Document

const document = await afp.get('uno')

More Like This

Find documents similar to a given one:

const { count, documents } = await afp.mlt('uno', 'en', 10)

Listing Facet Values

Retrieve the most used values for a specific facet:

const { count, keywords } = await afp.list('slug')

// With custom search scope and minimum document count
const { keywords } = await afp.list('country', { dateFrom: 'now-7d', langs: ['en'] }, 5)

Field Mapping

Get the API field mapping:

const mapping = await afp.mapping('en')

Filter Center

Manage saved search filters.

const fc = afp.filterCenter

// Create a filter
await fc.add('breaking-politics', { query: 'urgency:1', country: 'fra' })

// Update a filter
await fc.update('breaking-politics', { query: 'urgency:1 OR urgency:2' })

// Get a specific filter
const filter = await fc.get('breaking-politics')

// List all filters
const allFilters = await fc.all()

// Delete a filter
await fc.delete('breaking-politics')

Search with Saved Filter

const { count, documents } = await afp.searchWithFilter('my-filter', {
  startat: 0,
  size: 50
})

RSS/ATOM Feed

Retrieve an RSS/ATOM feed based on a saved filter:

const xmlContent = await afp.feed('my-filter', { size: 20 })

Notification Center

Subscribe to real-time document notifications via mail, REST, SQS, or JMS services.

const nc = afp.notificationCenter

// Register a REST service
const serviceId = await nc.registerService({
  name: 'my-webhook',
  type: 'rest',
  datas: { href: 'https://example.com/webhook' }
})

// Add a subscription
const subId = await nc.addSubscription('breaking-news', 'my-webhook', {
  query: 'urgency:1',
  langs: ['en']
})

// List services and subscriptions
const services = await nc.listServices()
const subscriptions = await nc.listSubscriptions()
const subs = await nc.subscriptionsInService('my-webhook')

// Cleanup
await nc.deleteSubscription('my-webhook', 'breaking-news')
await nc.removeSubscriptionsFromService('my-webhook', ['sub1', 'sub2'])
await nc.deleteService('my-webhook')

Social Stories

Retrieve the embeddable HTML for a social story document:

const html = afp.getStoryHtml(doc)

Search Parameters Reference

Parameter	Type	Default	Description
query	string	—	Boolean query string (see Query Syntax)
langs	string[]	—	Filter by language codes
dateFrom	string	'1980-01-01'	Start date (ISO date or relative like 'now-7d')
dateTo	string	'now'	End date
size	number	10	Number of results (max 1000 per request)
sortField	string	'published'	Field to sort by
sortOrder	'asc' | 'desc'	'desc'	Sort direction
startAt	number	—	Offset for pagination
tz	string	—	Timezone (e.g. 'Europe/Paris')
dateGap	string	—	Date gap for facet ranges (e.g. '+1HOUR', '+1DAY')
wantedFacets	WantedFacets	—	Facets configuration { facetName: { size, minDocCount }, empty?: boolean }
sort	SortEntry[]	—	Multi-field sort [{ sortField, sortOrder }]

Any additional key-value pairs are treated as field filters.

Development

# Install dependencies
npm install

# Build (clean + parser + types + ESM/CJS/bundles)
npm run build

# Development with auto-rebuild
npm run build:watch

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint
npm run lint

Author

Jules Bonnard

License

MIT - see LICENSE.md