@financial-times/content-curation-client 5.1.0 → 5.3.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 = {
-	/* ... */
-};
 ```

package/dist/_tsup-dts-rollup.d.cts

@@ -1,5 +1,10 @@
+import { baseObjectOutputType } from 'zod';
+import { objectUtil } from 'zod';
 import { Options } from 'tsup';
 import { z } from 'zod';
+import { ZodLiteral } from 'zod';
+import { ZodNumber } from 'zod';
+import { ZodString } from 'zod';
 import { ZodTypeAny } from 'zod';
 
 /**
@@ -17,7 +22,7 @@ export { ApiClient }
 export { ApiClient as ApiClient_alias_1 }
 
 /**
- * Configuration options for the API client
+ * Configuration options for the API client.
  */
 declare type ApiClientConfig = {
     baseUrl: string;
@@ -34,21 +39,73 @@ export { ApiClientConfig }
 export { ApiClientConfig as ApiClientConfig_alias_1 }
 
 /**
- * API-level error thrown when { status: 'error' } is returned
+ * Base error type for all failures surfaced by the client package.
  */
 declare class ApiClientError extends Error {
-    payload: z.infer<typeof ApiErrorPayloadSchema>;
-    statusCode: number;
-    requestId?: string | undefined;
-    code: string;
+    /** The machine-readable error payload exposed by the client. */
+    payload: ApiClientErrorPayload;
+    /** The machine-readable error code. */
+    code: ApiClientErrorPayload["code"];
+    /** Additional diagnostic detail captured by the client. */
     details?: string;
+    /** The API path associated with the failing request. */
     path?: string;
+    /** Optional timestamp supplied by the upstream service. */
     timestamp?: string;
-    constructor(payload: z.infer<typeof ApiErrorPayloadSchema>, statusCode: number, requestId?: string | undefined);
+    /** Indicates whether the failure originated from transport, gateway, or service handling. */
+    origin: ApiClientErrorOrigin;
+    /** The fully qualified request URL, when available. */
+    url?: string;
+    /** The response content type, when a response was received. */
+    contentType?: string;
+    /** A truncated copy of the raw response body, when captured. */
+    bodyText?: string;
+    /** The upstream request identifier, when available. */
+    requestId?: string;
+    /** The HTTP status code reported by the service or gateway. */
+    statusCode: number;
+    /** The underlying thrown error, if there was one. */
+    cause?: unknown;
+    constructor(payload: ApiClientErrorPayload, statusCode: number, requestId?: string, metadata?: ApiClientErrorMetadata);
 }
 export { ApiClientError }
 export { ApiClientError as ApiClientError_alias_1 }
 
+/** Machine-readable codes exposed by the client error model. */
+declare type ApiClientErrorCode = ApiErrorPayload["code"] | "API_GATEWAY_ERROR" | "API_TRANSPORT_ERROR";
+export { ApiClientErrorCode }
+export { ApiClientErrorCode as ApiClientErrorCode_alias_1 }
+
+declare type ApiClientErrorMetadata = {
+    origin: ApiClientErrorOrigin;
+    url?: string;
+    contentType?: string;
+    bodyText?: string;
+    cause?: unknown;
+};
+
+/** Where the failing request broke down. */
+declare type ApiClientErrorOrigin = "transport" | "gateway" | "service";
+export { ApiClientErrorOrigin }
+export { ApiClientErrorOrigin as ApiClientErrorOrigin_alias_1 }
+
+/**
+ * Shared error payload shape used by all client-generated errors.
+ *
+ * Service-origin errors use the validated `ApiErrorPayload` returned by the API.
+ * Gateway and transport errors synthesize the same top-level fields so callers
+ * can handle them consistently.
+ */
+declare type ApiClientErrorPayload = {
+    code: ApiClientErrorCode;
+    message: string;
+    details?: string;
+    path?: string;
+    timestamp?: string;
+};
+export { ApiClientErrorPayload }
+export { ApiClientErrorPayload as ApiClientErrorPayload_alias_1 }
+
 /**
  * Strongly‐typed enum for all possible API error codes.
  */
@@ -142,6 +199,18 @@ declare const ApiErrorResponseSchema: z.ZodObject<{
 export { ApiErrorResponseSchema }
 export { ApiErrorResponseSchema as ApiErrorResponseSchema_alias_1 }
 
+/**
+ * Error raised when the request reached API Gateway but did not produce a
+ * valid service-level error envelope.
+ */
+declare class ApiGatewayError extends ApiClientError {
+    payload: ApiClientErrorPayload;
+    origin: "gateway";
+    constructor(payload: ApiClientErrorPayload, statusCode: number, requestId?: string, metadata?: Omit<ApiClientErrorMetadata, "origin">);
+}
+export { ApiGatewayError }
+export { ApiGatewayError as ApiGatewayError_alias_1 }
+
 /**
  * Union of success or error envelopes, discriminated on `status`.
  */
@@ -213,6 +282,19 @@ declare function ApiResponseSchema<T extends ZodTypeAny>(dataSchema: T): z.ZodDi
 export { ApiResponseSchema }
 export { ApiResponseSchema as ApiResponseSchema_alias_1 }
 
+/**
+ * Error raised when the root service returns a valid JSON API error envelope,
+ * or when a successful response cannot be interpreted as the expected API
+ * success envelope.
+ */
+declare class ApiServiceError extends ApiClientError {
+    payload: ApiErrorPayload;
+    origin: "service";
+    constructor(payload: ApiErrorPayload, statusCode: number, requestId?: string, metadata?: Omit<ApiClientErrorMetadata, "origin">);
+}
+export { ApiServiceError }
+export { ApiServiceError as ApiServiceError_alias_1 }
+
 /**
  * Schema for a successful API response, given some data schema T.
  */
@@ -238,11 +320,40 @@ declare function ApiSuccessResponseSchema<T extends ZodTypeAny>(dataSchema: T):
 export { ApiSuccessResponseSchema }
 export { ApiSuccessResponseSchema as ApiSuccessResponseSchema_alias_1 }
 
+/**
+ * Error raised when the request fails before any HTTP response is available.
+ */
+declare class ApiTransportError extends ApiClientError {
+    payload: ApiClientErrorPayload;
+    origin: "transport";
+    /** Whether the failure was caused by an abort, timeout, or generic network problem. */
+    transportKind: ApiTransportKind;
+    constructor(payload: ApiClientErrorPayload, statusCode: number, requestId: string | undefined, metadata: ApiTransportErrorMetadata);
+}
+export { ApiTransportError }
+export { ApiTransportError as ApiTransportError_alias_1 }
+
+declare type ApiTransportErrorMetadata = Omit<ApiClientErrorMetadata, "origin"> & {
+    transportKind: ApiTransportKind;
+};
+
+/** The transport failure mode when no HTTP response was received. */
+declare type ApiTransportKind = "abort" | "timeout" | "network";
+export { ApiTransportKind }
+export { ApiTransportKind as ApiTransportKind_alias_1 }
+
+/**
+ * Shared HTTP client for Content Curation API requests.
+ *
+ * The public sub-clients delegate to this class so request validation, fetch
+ * execution, response parsing, and error classification all happen in one place.
+ */
 export declare class BaseApiClient {
     protected config: ApiClientConfig;
     constructor(config: ApiClientConfig);
     /**
-     * Generic HTTP request to a JSON API
+     * Performs a request against the JSON API, validates the response envelope,
+     * and returns the typed `data` payload on success.
      */
     protected request<ReqSchema extends ZodTypeAny | undefined, ResponseDataSchema extends ZodTypeAny>(method: "GET" | "PUT" | "POST" | "DELETE", path: string, opts: {
         requestSchema?: ReqSchema;
@@ -250,17 +361,56 @@ export declare class BaseApiClient {
         responseDataSchema: ResponseDataSchema;
     }): Promise<z.infer<ResponseDataSchema>>;
     /**
-     * GET convenience method inferring response type from schema
+     * GET convenience method inferring response type from schema.
      */
     protected get<ResponseDataSchema extends ZodTypeAny>(path: string, responseDataSchema: ResponseDataSchema): Promise<z.infer<ResponseDataSchema>>;
     /**
-     * PUT convenience method inferring both request and response types
+     * PUT convenience method inferring both request and response types.
      */
     protected put<ReqSchema extends ZodTypeAny, ResponseDataSchema extends ZodTypeAny>(path: string, body: z.infer<ReqSchema>, requestSchema: ReqSchema, responseDataSchema: ResponseDataSchema): Promise<z.infer<ResponseDataSchema>>;
 }
 
+/**
+ * Builds a gateway-origin client error after the caller has already decided the response does not
+ * represent a validated service error envelope.
+ */
+export declare function createGatewayError(path: string, url: string, statusCode: number, options: GatewayErrorOptions): ApiGatewayError;
+
+/**
+ * Classifies a non-success HTTP response as either a validated service error or
+ * a gateway-origin failure.
+ */
+declare function createResponseError(path: string, url: string, response: Response, responseBody: ResponseBodyDiagnostics): ApiGatewayError | ApiServiceError;
+export { createResponseError }
+export { createResponseError as createResponseError_alias_1 }
+
+/**
+ * Wraps a fetch failure that happened before any response was available.
+ */
+declare function createTransportError(path: string, url: string, error: unknown): ApiTransportError;
+export { createTransportError }
+export { createTransportError as createTransportError_alias_1 }
+
+/**
+ * Builds the fallback service error used when a 2xx response cannot be interpreted as the
+ * expected Content Curation API success envelope.
+ */
+export declare function createUnexpectedServiceResponseError(path: string, url: string, options: UnexpectedServiceResponseOptions): ApiServiceError;
+
 export declare const default_alias: Options | Options[] | ((overrideOptions: Options) => Options | Options[] | Promise<Options | Options[]>);
 
+/**
+ * Builds the diagnostic detail string used when a non-success response should be treated as a
+ * gateway-origin failure rather than a validated service error.
+ */
+export declare function describeGatewayResponse(statusCode: number, responseBody: ResponseBodyDiagnostics): string;
+
+/**
+ * Builds the diagnostic detail string used when a 2xx response cannot be understood as the
+ * expected Content Curation API success envelope.
+ */
+export declare function describeUnexpectedSuccessResponse(responseBody: ResponseBodyDiagnostics): string;
+
 declare type Draft = z.infer<typeof DraftSchema>;
 export { Draft }
 export { Draft as Draft_alias_1 }
@@ -1850,6 +2000,24 @@ declare type ExperimentSliceType = z.infer<typeof ExperimentSlice.OutputSchema>;
 export { ExperimentSliceType }
 export { ExperimentSliceType as ExperimentSliceType_alias_1 }
 
+declare type GatewayErrorOptions = {
+    contentType?: string;
+    bodyText?: string;
+    details: string;
+    requestId?: string;
+    cause?: unknown;
+};
+
+/**
+ * Extracts the response content type, if one was provided.
+ */
+export declare function getResponseContentType(response: Response): string | undefined;
+
+/**
+ * Extracts the upstream request identifier, if one was provided.
+ */
+export declare function getResponseRequestId(response: Response): string | undefined;
+
 declare const HeroSlice: {
     InputSchema: z.ZodObject<{
         type: z.ZodLiteral<"Hero">;
@@ -4462,6 +4630,11 @@ declare type InteractiveSliceType = z.infer<typeof InteractiveSlice.OutputSchema
 export { InteractiveSliceType }
 export { InteractiveSliceType as InteractiveSliceType_alias_1 }
 
+/**
+ * Returns `true` when a status code should always be treated as an API Gateway failure.
+ */
+export declare function isGatewayStatusCode(statusCode: number): boolean;
+
 declare type LegacyBlock = z.infer<typeof LegacyBlockSchema>;
 export { LegacyBlock }
 export { LegacyBlock as LegacyBlock_alias_1 }
@@ -8694,6 +8867,61 @@ declare const PageStructureOutputSchema: z.ZodObject<{
 export { PageStructureOutputSchema }
 export { PageStructureOutputSchema as PageStructureOutputSchema_alias_1 }
 
+/**
+ * Attempts to validate a consumed response body as a service-level error envelope.
+ */
+export declare function parseApiErrorResponse(responseBody: ResponseBodyDiagnostics): {
+    statusCode: number;
+    requestId: string;
+    status: "error";
+    error: {
+        code: "UNAUTHORIZED" | "NOT_FOUND" | "INTERNAL_SERVER_ERROR" | "INVALID_INPUT_DATA";
+        message: string;
+        path?: string | undefined;
+        details?: string | undefined;
+        timestamp?: string | undefined;
+    };
+} | null;
+
+/**
+ * Attempts to validate a consumed response body as a success-or-error API envelope.
+ */
+export declare function parseApiResponse<ResponseDataSchema extends ZodTypeAny>(responseDataSchema: ResponseDataSchema, responseBody: ResponseBodyDiagnostics): {
+    statusCode: number;
+    requestId: string;
+    status: "error";
+    error: {
+        code: "UNAUTHORIZED" | "NOT_FOUND" | "INTERNAL_SERVER_ERROR" | "INVALID_INPUT_DATA";
+        message: string;
+        path?: string | undefined;
+        details?: string | undefined;
+        timestamp?: string | undefined;
+    };
+} | (objectUtil.addQuestionMarks<baseObjectOutputType<    {
+statusCode: ZodNumber;
+requestId: ZodString;
+} & {
+status: ZodLiteral<"success">;
+data: ResponseDataSchema;
+}>, any> extends infer T ? { [k in keyof T]: T[k]; } : never) | null;
+
+/**
+ * Validates an outbound request body when the caller supplied a schema.
+ *
+ * Requests without a body, or without a schema, pass through unchanged.
+ */
+declare function parseRequestBody<ReqSchema extends ZodTypeAny | undefined>(requestSchema: ReqSchema | undefined, body: (ReqSchema extends ZodTypeAny ? z.infer<ReqSchema> : unknown) | undefined): (ReqSchema extends ZodTypeAny ? z.infer<ReqSchema> : unknown) | undefined;
+export { parseRequestBody }
+export { parseRequestBody as parseRequestBody_alias_1 }
+
+/**
+ * Interprets a successful HTTP response as either a valid Content Curation API
+ * success envelope or a service-origin failure.
+ */
+declare function parseSuccessfulResponse<ResponseDataSchema extends ZodTypeAny>(path: string, url: string, response: Response, responseBody: ResponseBodyDiagnostics, responseDataSchema: ResponseDataSchema): z.infer<ResponseDataSchema>;
+export { parseSuccessfulResponse }
+export { parseSuccessfulResponse as parseSuccessfulResponse_alias_1 }
+
 declare type PersistPageDraftInput = z.infer<typeof PersistPageDraftInputSchema>;
 export { PersistPageDraftInput }
 export { PersistPageDraftInput as PersistPageDraftInput_alias_1 }
@@ -10363,6 +10591,30 @@ declare const ProseMirrorDocSchema: z.ZodObject<{
 export { ProseMirrorDocSchema }
 export { ProseMirrorDocSchema as ProseMirrorDocSchema_alias_1 }
 
+/**
+ * Consumes the HTTP response body and converts body-read failures into the same
+ * client error model used for normal gateway and service failures.
+ */
+declare function readApiResponseBody(path: string, url: string, response: Response): Promise<ResponseBodyDiagnostics>;
+export { readApiResponseBody }
+export { readApiResponseBody as readApiResponseBody_alias_1 }
+
+/**
+ * Reads a response body exactly once, truncates diagnostic text, and only parses JSON when the
+ * declared content type says that is appropriate.
+ */
+export declare function readResponseBody(response: Response): Promise<ResponseBodyDiagnostics>;
+
+/**
+ * Captured information from a response body after the client has consumed it exactly once.
+ */
+export declare type ResponseBodyDiagnostics = {
+    contentType?: string;
+    bodyText?: string;
+    json?: unknown;
+    jsonParseError?: Error;
+};
+
 /** Rich text editor TS type. */
 declare type RichTextEditorType = z.infer<typeof ProseMirrorDocSchema>;
 export { RichTextEditorType }
@@ -13145,4 +13397,6 @@ declare type TopperSliceType = z.infer<typeof TopperSlice.OutputSchema>;
 export { TopperSliceType }
 export { TopperSliceType as TopperSliceType_alias_1 }
 
+declare type UnexpectedServiceResponseOptions = GatewayErrorOptions;
+
 export { }