@financial-times/content-curation-client 0.1.0

package/README.md

@@ -0,0 +1,169 @@
+# Content Curation API Client
+
+A 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
+
+## Installation
+
+```bash
+npm install @financial-times/content-curation-client
+```
+
+## Usage
+
+### Initialize the client
+
+```typescript
+import { ApiClient } from "@financial-times/content-curation-client";
+
+const client = new ApiClient({
+	baseUrl: "https://content-curation.eu-west-1.edtech-test.ftweb.tech/api",
+	apiToken: "your-api-token",
+});
+```
+
+### 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);
+```
+
+### 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);
+```
+
+### Update homepage structure
+
+```typescript
+import { HomepageDataApi } from "@financial-times/content-curation-client";
+
+// Create or update homepage structure
+const homepageStructure: Omit<HomepageDataApi, "type"> = {
+	properties: {
+		pageId: "58de2dc7-980b-4d51-8e45-9798f0c6b6bf",
+		homepageListId: "123e4567-e89b-12d3-a456-426614174000",
+		title: "My Updated Homepage",
+	},
+	children: [
+		{
+			type: "HomepageSlice",
+			properties: {
+				heading: {
+					text: "Featured Section",
+				},
+			},
+		},
+		{
+			type: "FlourishGraphic",
+			properties: {
+				heading: {
+					text: "Interactive Chart",
+				},
+				flourishId: "visualisation-123",
+				displayBehaviour: "standalone",
+			},
+		},
+	],
+};
+
+const result = await client.homepage.upsertStructure(pageId, homepageStructure);
+```
+
+### Update page structure
+
+```typescript
+import { PageStructureInput } from "@financial-times/content-curation-client";
+
+// Create or update page structure
+const pageStructure: Omit<PageStructureInput, "type"> = {
+	properties: {
+		pageId: "123e4567-e89b-12d3-a456-426614174999",
+		title: "My Updated Page",
+	},
+	children: [
+		{
+			type: "HomepageSlice",
+			properties: {
+				heading: {
+					text: "Featured Section",
+				},
+			},
+		},
+	],
+};
+
+const result = await client.page.upsertStructure(pageId, pageStructure);
+```
+
+### Error handling
+
+```typescript
+import { ApiError } from "@financial-times/content-curation-client";
+
+try {
+	const homepageStructure = await client.homepage.getStructure("invalid-id");
+} catch (error) {
+	if (error instanceof ApiError) {
+		console.error(`API Error (${error.status}): ${error.message}`);
+
+		if (error.errors) {
+			console.error("Validation errors:", error.errors);
+		}
+	} else {
+		console.error("Unknown error:", error);
+	}
+}
+```
+
+## Advanced usage
+
+### Custom fetch implementation
+
+You can provide your own fetch implementation, which is useful for caching, testing, and adding other custom behavior:
+
+```typescript
+import { ApiClient } from "@financial-times/content-curation-client";
+
+const client = new ApiClient({
+	baseUrl: "https://your-api-url.com/api",
+	apiToken: "your-api-token",
+	fetch: customFetchFunction,
+});
+```
+
+## Types
+
+```typescript
+import {
+	HomepageDataApi,
+	HomepageStructureApiResponse,
+	HomepageSliceApiResponse,
+	PageStructureInput,
+	PageStructureOutput,
+} from "@financial-times/content-curation-client";
+
+// Use types in your code
+const myPageStructureResponse: PageStructureOutput = {
+	/* ... */
+};
+```