@financial-times/content-curation-client 5.2.0 → 5.4.0

package/README.md

@@ -1,13 +1,13 @@
 # Content Curation API Client
 
-A TypeScript client library for interacting with the Content Curation API.
+TypeScript client library for interacting with the Content Curation API.
 
 ## Features
 
-- Fully typed API using Zod schemas for validation
-- Simple promise-based API for fetching and updating homepage and page structures
-- Comprehensive error handling
-- TypeScript-friendly with exported types
+- Zod-validated request and response types
+- Promise-based clients for homepage and page endpoints
+- Typed transport, gateway, and service error handling
+- Support for custom `fetch` implementations
 
 ## Installation
 
@@ -15,11 +15,12 @@ A TypeScript client library for interacting with the Content Curation API.
 npm install @financial-times/content-curation-client
 ```
 
-## Usage
+## API access
 
-### API Key
+If you do not already have one, you can request an API Gateway key by completing the
+[API Key Request Form](https://apigateway.in.ft.com/key-form).
 
-If you don’t already have one, you can request an API Gateway key by completing the [API Key Request Form](https://apigateway.in.ft.com/key-form).
+## Usage
 
 ### Initialize the client
 
@@ -35,38 +36,34 @@ const client = new ApiClient({
 ### Get homepage structure
 
 ```typescript
-// Fetch a homepage structure by pageId
 const pageId = "123e4567-e89b-12d3-a456-426614174000";
 const homepage = await client.homepage.getStructure(pageId);
 
-// Fetch available homepage structures by homepageListId
-const homepageListId = "123e4567-e89b-12d3-a456-426614174000";
-const structures = await client.homepage.getStructuresByHomepageListId(homepageListId);
-
-console.log(homepage.data.properties.title);
+console.log(homepage.properties.title);
 ```
 
 ### Get page structure
 
 ```typescript
-// Fetch a page structure by pageId
 const pageId = "123e4567-e89b-12d3-a456-426614174999";
 const page = await client.page.getStructure(pageId);
 
-console.log(page.data.properties.title);
+console.log(page.properties.title);
 ```
 
 ### Update homepage structure
 
 ```typescript
-import { HomepageDataApi } from "@financial-times/content-curation-client";
+import { HomepageStructureInput } from "@financial-times/content-curation-client";
 
-// Create or update homepage structure
-const homepageStructure: Omit<HomepageDataApi, "type"> = {
+const pageId = "58de2dc7-980b-4d51-8e45-9798f0c6b6bf";
+
+const homepageStructure: Omit<HomepageStructureInput, "type"> = {
 	properties: {
-		pageId: "58de2dc7-980b-4d51-8e45-9798f0c6b6bf",
+		pageId,
 		homepageListId: "123e4567-e89b-12d3-a456-426614174000",
 		title: "My Updated Homepage",
+		publicationId: "homepage-publication-id",
 	},
 	children: [
 		{
@@ -77,20 +74,10 @@ const homepageStructure: Omit<HomepageDataApi, "type"> = {
 				},
 			},
 		},
-		{
-			type: "FlourishGraphic",
-			properties: {
-				heading: {
-					text: "Interactive Chart",
-				},
-				flourishId: "visualisation-123",
-				displayBehaviour: "standalone",
-			},
-		},
 	],
 };
 
-const result = await client.homepage.upsertStructure(pageId, homepageStructure);
+const homepage = await client.homepage.upsertStructure(pageId, homepageStructure);
 ```
 
 ### Update page structure
@@ -98,11 +85,13 @@ const result = await client.homepage.upsertStructure(pageId, homepageStructure);
 ```typescript
 import { PageStructureInput } from "@financial-times/content-curation-client";
 
-// Create or update page structure
+const pageId = "123e4567-e89b-12d3-a456-426614174999";
+
 const pageStructure: Omit<PageStructureInput, "type"> = {
 	properties: {
-		pageId: "123e4567-e89b-12d3-a456-426614174999",
+		pageId,
 		title: "My Updated Page",
+		publicationId: "page-publication-id",
 	},
 	children: [
 		{
@@ -116,58 +105,80 @@ const pageStructure: Omit<PageStructureInput, "type"> = {
 	],
 };
 
-const result = await client.page.upsertStructure(pageId, pageStructure);
+const page = await client.page.upsertStructure(pageId, pageStructure);
 ```
 
-### Error handling
+## 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.
 
 ```typescript
-import { ApiError } from "@financial-times/content-curation-client";
+import {
+	ApiClientError,
+	ApiGatewayError,
+	ApiServiceError,
+	ApiTransportError,
+} from "@financial-times/content-curation-client";
 
 try {
-	const homepageStructure = await client.homepage.getStructure("invalid-id");
+	await client.page.getStructure("123e4567-e89b-12d3-a456-426614174999");
 } catch (error) {
-	if (error instanceof ApiError) {
-		console.error(`API Error (${error.status}): ${error.message}`);
-
-		if (error.errors) {
-			console.error("Validation errors:", error.errors);
-		}
+	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 {
-		console.error("Unknown error:", error);
+		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, which is useful for caching, testing, and adding other custom behavior:
+You can provide your own `fetch` implementation for testing or integration with your own
+runtime concerns:
 
 ```typescript
 import { ApiClient } from "@financial-times/content-curation-client";
 
 const client = new ApiClient({
-	baseUrl: "https://your-api-url.com/api",
+	baseUrl: "https://api-t.ft.com/content-curation",
 	apiKey: "your-api-key",
 	fetch: customFetchFunction,
 });
 ```
 
-## Types
+## Useful exported types
 
 ```typescript
-import {
-	HomepageDataApi,
-	HomepageStructureApiResponse,
-	HomepageSliceApiResponse,
+import type {
+	ApiErrorPayload,
+	HomepageStructureInput,
+	HomepageStructureOutput,
+	PageDraft,
 	PageStructureInput,
 	PageStructureOutput,
 } from "@financial-times/content-curation-client";
-
-// Use types in your code
-const myPageStructureResponse: PageStructureOutput = {
-	/* ... */
-};
 ```