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

package/dist/index.js

@@ -1,3 +1,195 @@
+// src/errors.ts
+var ApiClientError = class extends Error {
+  /** The machine-readable error payload exposed by the client. */
+  payload;
+  /** The machine-readable error code. */
+  code;
+  /** Additional diagnostic detail captured by the client. */
+  details;
+  /** The API path associated with the failing request. */
+  path;
+  /** Optional timestamp supplied by the upstream service. */
+  timestamp;
+  /** Indicates whether the failure originated from transport, gateway, or service handling. */
+  origin;
+  /** The fully qualified request URL, when available. */
+  url;
+  /** The response content type, when a response was received. */
+  contentType;
+  /** A truncated copy of the raw response body, when captured. */
+  bodyText;
+  /** The upstream request identifier, when available. */
+  requestId;
+  /** The HTTP status code reported by the service or gateway. */
+  statusCode;
+  /** The underlying thrown error, if there was one. */
+  cause;
+  constructor(payload, statusCode, requestId, metadata = { origin: "service" }) {
+    super(payload.message);
+    this.name = new.target.name;
+    this.payload = payload;
+    this.statusCode = statusCode;
+    this.requestId = requestId;
+    this.code = payload.code;
+    this.details = payload.details;
+    this.path = payload.path;
+    this.timestamp = payload.timestamp;
+    this.origin = metadata.origin;
+    this.url = metadata.url;
+    this.contentType = metadata.contentType;
+    this.bodyText = metadata.bodyText;
+    this.cause = metadata.cause;
+  }
+};
+var ApiTransportError = class extends ApiClientError {
+  payload;
+  origin;
+  /** Whether the failure was caused by an abort, timeout, or generic network problem. */
+  transportKind;
+  constructor(payload, statusCode, requestId, metadata) {
+    super(payload, statusCode, requestId, {
+      ...metadata,
+      origin: "transport"
+    });
+    this.payload = payload;
+    this.origin = "transport";
+    this.transportKind = metadata.transportKind;
+  }
+};
+var ApiGatewayError = class extends ApiClientError {
+  payload;
+  origin;
+  constructor(payload, statusCode, requestId, metadata = {}) {
+    super(payload, statusCode, requestId, {
+      ...metadata,
+      origin: "gateway"
+    });
+    this.payload = payload;
+    this.origin = "gateway";
+  }
+};
+var ApiServiceError = class extends ApiClientError {
+  payload;
+  origin;
+  constructor(payload, statusCode, requestId, metadata = {}) {
+    super(payload, statusCode, requestId, {
+      ...metadata,
+      origin: "service"
+    });
+    this.payload = payload;
+    this.origin = "service";
+  }
+};
+
+// src/internal/error-factories.ts
+function createTransportError(path, url, error) {
+  const transportKind = classifyTransportFailure(error);
+  const message = describeTransportFailure(transportKind);
+  const causeDetails = getErrorDiagnosticMessage(error);
+  const details = causeDetails ? `${message} Cause: ${causeDetails}` : message;
+  return new ApiTransportError(
+    {
+      code: "API_TRANSPORT_ERROR",
+      message,
+      details,
+      path
+    },
+    0,
+    void 0,
+    {
+      transportKind,
+      url,
+      cause: error
+    }
+  );
+}
+function createGatewayError(path, url, statusCode, options) {
+  return new ApiGatewayError(
+    {
+      code: "API_GATEWAY_ERROR",
+      message: `The API gateway responded with status ${statusCode}.`,
+      details: options.details,
+      path
+    },
+    statusCode,
+    options.requestId,
+    {
+      url,
+      contentType: options.contentType,
+      bodyText: options.bodyText,
+      cause: options.cause
+    }
+  );
+}
+function createUnexpectedServiceResponseError(path, url, options) {
+  return new ApiServiceError(
+    {
+      code: "INTERNAL_SERVER_ERROR",
+      message: "Unexpected API response format",
+      details: options.details,
+      path
+    },
+    500,
+    options.requestId,
+    {
+      url,
+      contentType: options.contentType,
+      bodyText: options.bodyText,
+      cause: options.cause
+    }
+  );
+}
+function classifyTransportFailure(error) {
+  const errorName = readStringProperty(error, "name");
+  if (errorName === "AbortError") {
+    return "abort";
+  }
+  if (errorName === "TimeoutError") {
+    return "timeout";
+  }
+  if (errorName === "FetchError" && readStringProperty(error, "type") === "request-timeout") {
+    return "timeout";
+  }
+  return "network";
+}
+function describeTransportFailure(transportKind) {
+  if (transportKind === "abort") {
+    return "The request was aborted before a response was received.";
+  }
+  if (transportKind === "timeout") {
+    return "The request timed out before a response was received.";
+  }
+  return "The request failed before a response was received.";
+}
+function getErrorDiagnosticMessage(error) {
+  const diagnosticParts = [
+    readCauseCode(error),
+    readStringProperty(error, "name"),
+    readStringProperty(error, "message")
+  ].filter(
+    (value, index, values) => Boolean(value) && values.indexOf(value) === index
+  );
+  return diagnosticParts.length > 0 ? diagnosticParts.join(": ") : void 0;
+}
+function readCauseCode(error) {
+  if (typeof error !== "object" || error === null) {
+    return void 0;
+  }
+  const directCode = readStringProperty(error, "code");
+  if (directCode) {
+    return directCode;
+  }
+  const cause = error.cause;
+  return readStringProperty(cause, "code");
+}
+function readStringProperty(error, property) {
+  if (typeof error !== "object" || error === null) {
+    return void 0;
+  }
+  const value = error[property];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+
 // src/schemas/response.ts
 import { z } from "zod";
 var ApiErrorCode = z.enum([
@@ -33,24 +225,242 @@ function ApiResponseSchema(dataSchema) {
   return z.discriminatedUnion("status", [successSchema, errorSchema]);
 }
 
-// src/base.ts
-var ApiClientError = class extends Error {
-  constructor(payload, statusCode, requestId) {
-    super(payload.message);
-    this.payload = payload;
-    this.statusCode = statusCode;
-    this.requestId = requestId;
-    this.name = "ApiError";
-    this.code = payload.code;
-    this.details = payload.details;
-    this.path = payload.path;
-    this.timestamp = payload.timestamp;
+// src/internal/response-handling.ts
+var GATEWAY_STATUS_CODES = /* @__PURE__ */ new Set([499, 502, 503]);
+var MAX_DIAGNOSTIC_BODY_LENGTH = 2e3;
+function isGatewayStatusCode(statusCode) {
+  return GATEWAY_STATUS_CODES.has(statusCode);
+}
+function getResponseContentType(response) {
+  return response.headers?.get("content-type") ?? void 0;
+}
+function getResponseRequestId(response) {
+  return response.headers?.get("x-request-id") ?? response.headers?.get("request-id") ?? void 0;
+}
+async function readResponseBody(response) {
+  const contentType = getResponseContentType(response);
+  let rawBody = "";
+  try {
+    rawBody = await response.text();
+  } catch (error) {
+    await discardResponseBody(response);
+    throw error;
   }
-  code;
-  details;
-  path;
-  timestamp;
-};
+  const bodyText = truncateBody(rawBody);
+  if (!isJsonContentType(contentType) || rawBody.length === 0) {
+    return {
+      contentType,
+      bodyText
+    };
+  }
+  try {
+    return {
+      contentType,
+      bodyText,
+      json: JSON.parse(rawBody)
+    };
+  } catch (error) {
+    return {
+      contentType,
+      bodyText,
+      jsonParseError: toError(error)
+    };
+  }
+}
+function parseApiResponse(responseDataSchema, responseBody) {
+  if (responseBody.json === void 0) {
+    return null;
+  }
+  const parsedResponse = ApiResponseSchema(responseDataSchema).safeParse(responseBody.json);
+  return parsedResponse.success ? parsedResponse.data : null;
+}
+function parseApiErrorResponse(responseBody) {
+  if (responseBody.json === void 0) {
+    return null;
+  }
+  const parsedError = ApiErrorResponseSchema.safeParse(responseBody.json);
+  return parsedError.success ? parsedError.data : null;
+}
+function describeUnexpectedSuccessResponse(responseBody) {
+  if (responseBody.jsonParseError) {
+    return buildDiagnosticDetails(
+      "The service reported a JSON response but the body could not be parsed as JSON.",
+      responseBody
+    );
+  }
+  if (!responseBody.contentType || !isJsonContentType(responseBody.contentType)) {
+    return buildDiagnosticDetails(
+      "The service returned a success status without a JSON response body.",
+      responseBody
+    );
+  }
+  return buildDiagnosticDetails(
+    "The service returned JSON, but it did not match the expected Content Curation API envelope.",
+    responseBody
+  );
+}
+function describeGatewayResponse(statusCode, responseBody) {
+  if (responseBody.jsonParseError) {
+    return buildDiagnosticDetails(
+      `The non-success response with status ${statusCode} declared a JSON content type, but its body could not be parsed as JSON.`,
+      responseBody
+    );
+  }
+  if (!responseBody.contentType || !isJsonContentType(responseBody.contentType)) {
+    return buildDiagnosticDetails(
+      `The non-success response with status ${statusCode} was not a valid service JSON error envelope.`,
+      responseBody
+    );
+  }
+  return buildDiagnosticDetails(
+    `The non-success response with status ${statusCode} returned JSON, but it did not match the service error envelope.`,
+    responseBody
+  );
+}
+async function discardResponseBody(response) {
+  const body = response.body;
+  if (!body) {
+    return;
+  }
+  if (typeof body.cancel === "function") {
+    try {
+      await body.cancel();
+      return;
+    } catch {
+    }
+  }
+  if (typeof body.resume === "function" && typeof body.on === "function") {
+    await new Promise((resolve) => {
+      const stream = body;
+      const finish = () => resolve();
+      stream.on("end", finish);
+      stream.on("error", finish);
+      stream.resume();
+    });
+  }
+}
+function buildDiagnosticDetails(message, responseBody) {
+  const detailParts = [message];
+  if (responseBody.contentType) {
+    detailParts.push(`Content-Type: ${responseBody.contentType}.`);
+  }
+  if (responseBody.jsonParseError) {
+    detailParts.push(`JSON parse error: ${responseBody.jsonParseError.message}.`);
+  }
+  if (responseBody.bodyText) {
+    detailParts.push("The raw response body is available in bodyText.");
+  }
+  return detailParts.join(" ");
+}
+function isJsonContentType(contentType) {
+  if (!contentType) {
+    return false;
+  }
+  const mimeType = contentType.split(";")[0]?.trim().toLowerCase();
+  if (!mimeType) {
+    return false;
+  }
+  return mimeType === "application/json" || mimeType.endsWith("+json");
+}
+function truncateBody(bodyText) {
+  if (bodyText.length === 0) {
+    return void 0;
+  }
+  if (bodyText.length <= MAX_DIAGNOSTIC_BODY_LENGTH) {
+    return bodyText;
+  }
+  return `${bodyText.slice(0, MAX_DIAGNOSTIC_BODY_LENGTH - 3)}...`;
+}
+function toError(error) {
+  if (error instanceof Error) {
+    return error;
+  }
+  const message = typeof error === "string" && error.length > 0 ? error : "Unknown error";
+  return new Error(message);
+}
+
+// src/internal/request-lifecycle.ts
+function parseRequestBody(requestSchema, body) {
+  if (!requestSchema || body === void 0) {
+    return body;
+  }
+  return requestSchema.parse(body);
+}
+async function readApiResponseBody(path, url, response) {
+  try {
+    return await readResponseBody(response);
+  } catch (error) {
+    if (response.ok) {
+      throw createUnexpectedServiceResponseError(path, url, {
+        contentType: getResponseContentType(response),
+        cause: error,
+        details: "Failed to read the response body before the API response could be validated.",
+        requestId: getResponseRequestId(response)
+      });
+    }
+    throw createGatewayError(path, url, response.status, {
+      contentType: getResponseContentType(response),
+      cause: error,
+      details: "Failed to read the non-success response body, so the response could not be validated as a service error.",
+      requestId: getResponseRequestId(response)
+    });
+  }
+}
+function parseSuccessfulResponse(path, url, response, responseBody, responseDataSchema) {
+  const parsedResponse = parseApiResponse(responseDataSchema, responseBody);
+  if (!parsedResponse) {
+    throw createUnexpectedServiceResponseError(path, url, {
+      contentType: responseBody.contentType,
+      bodyText: responseBody.bodyText,
+      details: describeUnexpectedSuccessResponse(responseBody),
+      requestId: getResponseRequestId(response)
+    });
+  }
+  if ("error" in parsedResponse) {
+    throw new ApiServiceError(
+      parsedResponse.error,
+      parsedResponse.statusCode,
+      parsedResponse.requestId,
+      {
+        url,
+        contentType: responseBody.contentType,
+        bodyText: responseBody.bodyText
+      }
+    );
+  }
+  return parsedResponse.data;
+}
+function createResponseError(path, url, response, responseBody) {
+  if (isGatewayStatusCode(response.status)) {
+    return createGatewayError(path, url, response.status, {
+      contentType: responseBody.contentType,
+      bodyText: responseBody.bodyText,
+      details: describeGatewayResponse(response.status, responseBody),
+      requestId: getResponseRequestId(response)
+    });
+  }
+  const parsedServiceError = parseApiErrorResponse(responseBody);
+  if (parsedServiceError) {
+    return new ApiServiceError(
+      parsedServiceError.error,
+      parsedServiceError.statusCode,
+      parsedServiceError.requestId,
+      {
+        url,
+        contentType: responseBody.contentType,
+        bodyText: responseBody.bodyText
+      }
+    );
+  }
+  return createGatewayError(path, url, response.status, {
+    contentType: responseBody.contentType,
+    bodyText: responseBody.bodyText,
+    details: describeGatewayResponse(response.status, responseBody),
+    requestId: getResponseRequestId(response)
+  });
+}
+
+// src/base.ts
 var BaseApiClient = class {
   config;
   constructor(config) {
@@ -58,55 +468,60 @@ var BaseApiClient = class {
       ...config,
       fetch: config.fetch || fetch
     };
-    this.config.baseUrl = this.config.baseUrl.replace(/\/+$/, "");
+    this.config.baseUrl = trimTrailingSlashes(this.config.baseUrl);
   }
   /**
-   * 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.
    */
   async request(method, path, opts) {
-    let bodyPayload = opts.body;
-    if (opts.requestSchema && opts.body !== void 0) {
-      bodyPayload = opts.requestSchema.parse(opts.body);
-    }
-    const url = new URL(this.config.baseUrl + path);
-    const response = await this.config.fetch(url.toString(), {
-      method,
-      headers: {
-        "Content-Type": "application/json",
-        ...this.config.apiKey ? { "x-api-key": this.config.apiKey } : { Authorization: `Bearer ${this.config.apiToken}` }
-      },
-      body: bodyPayload ? JSON.stringify(bodyPayload) : void 0
-    });
-    const json = await response.json();
-    const parsedJson = ApiResponseSchema(opts.responseDataSchema).parse(json);
-    if ("error" in parsedJson) {
-      throw new ApiClientError(parsedJson.error, parsedJson.statusCode, parsedJson.requestId);
-    } else if (!("data" in parsedJson)) {
-      throw new ApiClientError(
-        {
-          code: "INTERNAL_SERVER_ERROR",
-          message: "Unexpected API response format",
-          details: 'Response did not contain expected "data" field'
+    const bodyPayload = parseRequestBody(opts.requestSchema, opts.body);
+    const urlString = new URL(this.config.baseUrl + path).toString();
+    let response;
+    try {
+      response = await this.config.fetch(urlString, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          ...this.config.apiKey ? { "x-api-key": this.config.apiKey } : { Authorization: `Bearer ${this.config.apiToken}` }
         },
-        500,
-        parsedJson.requestId
+        body: bodyPayload === void 0 ? void 0 : JSON.stringify(bodyPayload)
+      });
+    } catch (error) {
+      throw createTransportError(path, urlString, error);
+    }
+    const responseBody = await readApiResponseBody(path, urlString, response);
+    if (response.ok) {
+      return parseSuccessfulResponse(
+        path,
+        urlString,
+        response,
+        responseBody,
+        opts.responseDataSchema
       );
     }
-    return parsedJson.data;
+    throw createResponseError(path, urlString, response, responseBody);
   }
   /**
-   * GET convenience method inferring response type from schema
+   * GET convenience method inferring response type from schema.
    */
   get(path, responseDataSchema) {
     return this.request("GET", path, { responseDataSchema });
   }
   /**
-   * PUT convenience method inferring both request and response types
+   * PUT convenience method inferring both request and response types.
    */
   put(path, body, requestSchema, responseDataSchema) {
     return this.request("PUT", path, { body, requestSchema, responseDataSchema });
   }
 };
+function trimTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) {
+    end -= 1;
+  }
+  return end === value.length ? value : value.slice(0, end);
+}
 
 // src/schemas/ftpink/page/index.ts
 import { z as z3 } from "zod";
@@ -249,7 +664,7 @@ var BasePagePropertiesSchema = z3.object({
   title: z3.string(),
   pageId: z3.string().uuid(),
   publicationId: z3.string(),
-  conceptId: z3.string().optional(),
+  conceptId: z3.string().uuid().optional(),
   metaDescription: z3.string().optional(),
   pageTheme: z3.string().optional(),
   sponsorText: z3.string().optional(),
@@ -417,7 +832,7 @@ var PageClient = class extends BaseApiClient {
     try {
       return await this.get(`/v1/page/${pageId}/draft`, PageDraftSchema);
     } catch (error) {
-      if (error instanceof ApiClientError && error.code === "NOT_FOUND") {
+      if (error instanceof ApiServiceError && error.code === "NOT_FOUND") {
         return null;
       }
       throw error;
@@ -455,8 +870,11 @@ export {
   ApiErrorCode,
   ApiErrorPayloadSchema,
   ApiErrorResponseSchema,
+  ApiGatewayError,
   ApiResponseSchema,
+  ApiServiceError,
   ApiSuccessResponseSchema,
+  ApiTransportError,
   DraftContributorInputSchema,
   DraftContributorSchema,
   DraftSchema,