Content Curation API Client

TypeScript client library for interacting with the Content Curation API.

Features

• Zod-validated request and response types
• Promise-based clients for page endpoints
• Typed transport, gateway, and service error handling
• Support for custom fetch implementations

Installation

npm install @financial-times/content-curation-client

API access

If you do not already have one, you can request an API Gateway key by completing the API Key Request Form.

Usage

Initialize the client

import { ApiClient } from "@financial-times/content-curation-client";

const client = new ApiClient({
	baseUrl: "https://api-t.ft.com/content-curation",
	apiKey: "your-api-key",
});

Get page structure

const pageId = "123e4567-e89b-12d3-a456-426614174999";
const page = await client.page.getStructure(pageId);

console.log(page.properties.title);

List pages by category

const pages = await client.page.listPages({ pageCategory: "topic" });

console.log(JSON.stringify(pages, null, 2));

• Pass pageCategory (e.g. "topic") to return only pages with an exact match.
• Pass { pageCategory: "page" } to return pages explicitly categorised as page and legacy pages with no category set (treated as the default).
• To return all published pages regardless of category omit the options object, omit pageCategory, or pass an empty string.

Update page structure

import { PageStructureInput } from "@financial-times/content-curation-client";

const pageId = "123e4567-e89b-12d3-a456-426614174999";

const pageStructure: Omit<PageStructureInput, "type"> = {
	properties: {
		pageId,
		title: "My Updated Page",
		publicationId: "page-publication-id",
	},
	children: [],
};

const page = await client.page.upsertStructure(pageId, pageStructure);

Error handling

Client methods throw ApiClientError for any client-generated failure. You can narrow that base class into transport, gateway, and service errors when you need more specific handling.

import {
	ApiClientError,
	ApiGatewayError,
	ApiServiceError,
	ApiTransportError,
} from "@financial-times/content-curation-client";

try {
	await client.page.getStructure("123e4567-e89b-12d3-a456-426614174999");
} catch (error) {
	if (error instanceof ApiTransportError) {
		console.error(error.transportKind, error.message, error.cause);
	} else if (error instanceof ApiGatewayError) {
		console.error(error.statusCode, error.contentType, error.bodyText);
	} else if (error instanceof ApiServiceError) {
		console.error(error.code, error.message, error.details);
	} else if (error instanceof ApiClientError) {
		console.error(error.origin, error.message);
	} else {
		throw error;
	}
}

Error metadata

All ApiClientError instances expose:

• origin: "transport" | "gateway" | "service"
• statusCode: 0 for transport failures, otherwise the HTTP status code
• requestId: the upstream request identifier when available
• url: the request URL when available
• contentType: the response content-type when a response was received
• bodyText: truncated raw response text when the client captured it
• cause: the original thrown error for wrapped failures

ApiTransportError also exposes transportKind, and ApiServiceError is the subtype whose payload is guaranteed to match the server-side ApiErrorPayload schema.

Advanced usage

Custom fetch implementation

You can provide your own fetch implementation for testing or integration with your own runtime concerns:

import { ApiClient } from "@financial-times/content-curation-client";

const client = new ApiClient({
	baseUrl: "https://api-t.ft.com/content-curation",
	apiKey: "your-api-key",
	fetch: customFetchFunction,
});

Useful exported types

import type {
	ApiErrorPayload,
	PageDraft,
	PageStructureInput,
	PageStructureOutput,
} from "@financial-times/content-curation-client";