# @financial-times/n-lists-client

Latest version **11.0.0** (published 2025-10-03) · 0 weekly downloads

## Install

```sh
npm install @financial-times/n-lists-client
pnpm add @financial-times/n-lists-client
yarn add @financial-times/n-lists-client
bun add @financial-times/n-lists-client
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 11.0.0 |
| Published | 2025-10-03 |
| First published | 2018-02-28 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | 20.x \|\| 22.x |
| Dependencies | 5 |
| Unpacked size | 8.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | the-ft, rowanmanning, chee, alexwilson, aendra, emmalewis, notlee, seraph2000, hamza.samih, robertboulton, robgodfrey |

## Links

- npm: https://www.npmjs.com/package/@financial-times/n-lists-client
- Repository: git@github.com:Financial-Times/n-lists-client
- Homepage: https://github.com/Financial-Times/n-lists-client
- npm.io page: https://npm.io/package/@financial-times/n-lists-client

## Dependencies (5)

- [node-fetch](https://npm.io/package/node-fetch.md) ^2.6.1
- [@financial-times/user-agent](https://npm.io/package/@financial-times/user-agent.md) ^1.0.4
- [@financial-times/n-es-client](https://npm.io/package/@financial-times/n-es-client.md) ^6.0.1
- [@dotcom-reliability-kit/errors](https://npm.io/package/@dotcom-reliability-kit/errors.md) ^4.1.0
- [@dotcom-reliability-kit/fetch-error-handler](https://npm.io/package/@dotcom-reliability-kit/fetch-error-handler.md) ^1.1.0

## Recent versions

- 11.0.0 (latest) — 2025-10-03
- 8.0.1-alpha.0 (prerelease) — 2024-03-05
- 10.0.0 — 2025-09-25
- 9.0.0 — 2024-11-28
- 8.0.1 — 2024-11-26
- 8.0.0 — 2023-08-08
- 7.0.0 — 2023-07-13
- 6.0.0 — 2023-06-14
- 5.1.0 — 2022-08-02
- 5.0.0 — 2022-04-08
- 4.1.0 — 2021-08-12
- 4.0.0 — 2021-03-22
- 3.0.0 — 2021-03-22
- 1.0.2 — 2018-08-30
- 1.0.1 — 2018-08-21
- … 2 more at https://npm.io/package/@financial-times/n-lists-client/versions

## README

# n-lists-client

[![CircleCI](https://img.shields.io/circleci/project/github/Financial-Times/n-lists-client/main.svg)](https://circleci.com/gh/Financial-Times/n-lists-client) ![Coveralls Coverage](https://img.shields.io/coveralls/github/Financial-Times/n-lists-client/main.svg) [![NPM version](https://img.shields.io/npm/v/@financial-times/n-lists-client.svg)](https://www.npmjs.com/package/@financial-times/n-lists-client)

A very thin wrapper around the [Content API][1] and [n-es-client][2] to search and retrieve content from lists in a simple, DRY manner.

```js
const lists = require('@financial-times/n-lists-client');

lists.get('bc81b5bc-1995-11e5-a130-2e7db721f996').then((data) => { … });
```

## Installation

```sh
# install from NPM
$ npm i -S @financial-times/n-lists-client

# add Content API key
export API_KEY=123

# add Elasticsearch read AWS access key
export ES_AWS_ACCESS_KEY=456

# add Elasticsearch read AWS secret access key
export ES_AWS_SECRET_ACCESS_KEY=789
```

## Usage

All methods return a promise. If a request errors then it will be rejected with an appropriate HTTP error.

All methods have an optional `options` argument that accepts a hash of option properties. Current options are:

- `fields` - an array of fields to fetch from Elasticsearch.

All methods have an optional final `timeout` argument that defaults to 3 seconds.

### `.get(listID[, options][, timeout])`

Get a list by list ID (which must be a valid UUID.)

#### Example

```js
lists.get("bc81b5bc-1995-11e5-a130-2e7db721f996", {
  fields: ["id", "title"],
});
```

### `.for(listType, conceptID[, options][, timeout])`

Get a curated list for a concept. Must be a known list type.

```js
lists.for("TopStories", "c91b1fad-1097-468b-be82-9a8ff717d54c", {
  fields: ["id", "title"],
});
```

[1]: https://developer.ft.com/
[2]: https://github.com/Financial-Times/n-es-client

---
_Source: https://npm.io/package/@financial-times/n-lists-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._