@financial-times/content-curation-client 5.1.0 → 5.3.0

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

@@ -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 { }