apacuana-sdk-core 0.10.0 → 0.12.0

package/src/api/certs.js

@@ -1,27 +1,21 @@
+/**
+ * @typedef {import('../types/users').UserData} UserData
+ * @typedef {import('../types/certs').GenerateCertResponse} GenerateCertResponse
+ * @typedef {import('../types/certs').GetCertStatusResponse} GetCertStatusResponse
+ * @typedef {import('../types/certs').EncryptedCSRObject} EncryptedCSRObject
+ * @typedef {import('../types/certs').GetCertTypesResponse} GetCertTypesResponse
+ * @typedef {import('../types/certs').GetRequirementsResponse} GetRequirementsResponse
+ * @typedef {import('../types/certs').CertificateRequestParams} CertificateRequestParams
+ * @typedef {import('../types/certs').RequestCertificateResponse} RequestCertificateResponse
+ */
+
 import { getConfig } from "../config/index";
 import { httpRequest } from "../utils/httpClient";
 import helpers from "../utils/helpers";
 import { ApacuanaAPIError } from "../errors";
+import ApacuanaSuccess from "../success";
 import { INTEGRATION_TYPE } from "../utils/constant";
 
-/**
- * @typedef {object} GenerateCertResponse
- * @property {string} cert - El certificado generado en formato string.
- * @property {string} certifiedid - El ID del certificado generado.
- * @property {boolean} success - Indica si la operación fue exitosa.
- */
-
-/**
- * @typedef {object} GetCertStatusResponse
- * @property {string} status - El estado actual del certificado del usuario.
- * @property {boolean} success - Indica si la operación fue exitosa.
- */
-
-/**
- * @typedef {object} EncryptedCSRObject
- * @property {string} csr - The encrypted Certificate Signing Request.
- */
-
 /**
  * @param {EncryptedCSRObject} encryptedCSR
  */
@@ -41,7 +35,7 @@ const generateCertOnBoarding = async (encryptedCSR) => {
       );
     }
 
-    return { cert, certifiedid, success: true };
+    return new ApacuanaSuccess({ cert, certifiedid });
   } catch (error) {
     // The captured error is re-thrown, which will already be of type ApacuanaAPIError or a native Error.
     if (error instanceof ApacuanaAPIError) {
@@ -94,24 +88,9 @@ export const getCertStatus = (isCertificateInDevice = false) => {
     config.userData,
     isCertificateInDevice
   );
-  return {
-    status,
-    success: true,
-  };
+  return new ApacuanaSuccess({ status });
 };
 
-/**
- * @typedef {object} CertType
- * @property {string} id - The ID of the certificate type.
- * @property {string} name - The name of the certificate type.
- */
-
-/**
- * @typedef {object} GetCertTypesResponse
- * @property {Array<CertType>} types - A list of available certificate types.
- * @property {boolean} success - Indicates if the operation was successful.
- */
-
 const getCertTypesOnBoarding = async () => {
   try {
     const response = await httpRequest(
@@ -120,7 +99,7 @@ const getCertTypesOnBoarding = async () => {
       "GET"
     );
 
-    return { ...response, success: true };
+    return new ApacuanaSuccess(response);
   } catch (error) {
     if (error instanceof ApacuanaAPIError) {
       throw error;
@@ -159,18 +138,6 @@ export const getCertTypes = async () => {
   );
 };
 
-/**
- * @typedef {object} Requirement
- * @property {string} id - The ID of the requirement.
- * @property {string} description - The description of the requirement.
- */
-
-/**
- * @typedef {object} GetRequirementsResponse
- * @property {Array<Requirement>} requirements - A list of requirements for the user type.
- * @property {boolean} success - Indicates if the operation was successful.
- */
-
 const getRequerimentsByTypeUserOnBoarding = async (type) => {
   try {
     const response = await httpRequest(
@@ -179,7 +146,7 @@ const getRequerimentsByTypeUserOnBoarding = async (type) => {
       "GET"
     );
 
-    return { ...response, success: true };
+    return new ApacuanaSuccess(response);
   } catch (error) {
     if (error instanceof ApacuanaAPIError) {
       throw error;
@@ -226,3 +193,61 @@ export const getRequerimentsByTypeUser = async (params) => {
     "UNSUPPORTED_INTEGRATION_TYPE"
   );
 };
+
+const requestCertificateOnBoarding = async (params) => {
+  try {
+    const response = await httpRequest(
+      "services/api/customer/request-certificate",
+      params,
+      "POST"
+    );
+
+    return new ApacuanaSuccess(response);
+  } catch (error) {
+    if (error instanceof ApacuanaAPIError) {
+      throw error;
+    }
+    throw new Error(`Failed to request certificate: ${error.message}`);
+  }
+};
+
+const requestCertificateOnPremise = async () => {
+  throw new ApacuanaAPIError(
+    "Requesting a certificate is not supported for integration type: ONPREMISE",
+    501,
+    "NOT_IMPLEMENTED"
+  );
+};
+
+/**
+ * Requests a certificate for the user.
+ * @param {CertificateRequestParams} params - The parameters for the certificate request.
+ * @returns {Promise<RequestCertificateResponse>} Object with a confirmation message and a success indicator.
+ * @throws {ApacuanaAPIError} If the API response is invalid or the integration type is not supported.
+ * @throws {Error} If the request fails for another reason or the params are invalid.
+ */
+export const requestCertificate = async (params) => {
+  if (
+    !params ||
+    typeof params.type !== "number" ||
+    !Array.isArray(params.documents)
+  ) {
+    throw new Error(
+      'The "params" object with a numeric "type" property and a "documents" array is required.'
+    );
+  }
+
+  const { integrationType } = getConfig();
+  if (integrationType === INTEGRATION_TYPE.ONBOARDING) {
+    return requestCertificateOnBoarding(params);
+  }
+  if (integrationType === INTEGRATION_TYPE.ONPREMISE) {
+    return requestCertificateOnPremise();
+  }
+
+  throw new ApacuanaAPIError(
+    `Unsupported integration type: ${integrationType}`,
+    400,
+    "UNSUPPORTED_INTEGRATION_TYPE"
+  );
+};

package/src/api/faceLiveness.js

@@ -0,0 +1,146 @@
+/**
+ * @typedef {import('../types/faceLiveness').CreateFaceLivenessSessionResponse} CreateFaceLivenessSessionResponse
+ */
+
+import { getConfig } from "../config/index";
+import { httpRequest } from "../utils/httpClient";
+import { ApacuanaAPIError } from "../errors";
+import ApacuanaSuccess from "../success";
+import { INTEGRATION_TYPE } from "../utils/constant";
+
+/**
+ * Creates a new Face Liveness session.
+ * @returns {Promise<CreateFaceLivenessSessionResponse>} Object with the session ID and a success indicator.
+ * @throws {ApacuanaAPIError} If the API response is invalid or the integration type is not supported.
+ * @throws {Error} If the request fails for another reason.
+ */
+const createFaceLivenessSessionOnBoarding = async () => {
+  try {
+    const response = await httpRequest(
+      "services/api/faceliveness/create",
+      {},
+      "POST"
+    );
+    if (!response.sessionid) {
+      throw new ApacuanaAPIError(
+        "The API response does not contain the session ID.",
+        response.status,
+        "INVALID_API_RESPONSE"
+      );
+    }
+
+    return new ApacuanaSuccess({
+      sessionId: response.sessionid,
+    });
+  } catch (error) {
+    if (error instanceof ApacuanaAPIError) {
+      throw error;
+    }
+    throw new ApacuanaAPIError(
+      `Failed to create Face Liveness session: ${error.message}`
+    );
+  }
+};
+
+const createFaceLivenessSessionOnPremise = async () => {
+  throw new ApacuanaAPIError(
+    "Creating a Face Liveness session is not supported for integration type: ONPREMISE",
+    501,
+    "NOT_IMPLEMENTED"
+  );
+};
+
+const validateFaceLivenessOnBoarding = async (sessionId) => {
+  try {
+    const response = await httpRequest(
+      "services/api/faceliveness/validate",
+      { sessionid: sessionId },
+      "POST"
+    );
+    return new ApacuanaSuccess({ status: "verified", ...response });
+  } catch (error) {
+    if (error instanceof ApacuanaAPIError) {
+      let status;
+      switch (error.statusCode) {
+        case 402:
+          status = "waitingForScan";
+          break;
+        case 403:
+          status = "rejected";
+          break;
+        case 406:
+          status = "processing";
+          break;
+        case 408:
+          status = "expired";
+          break;
+        default:
+          throw error;
+      }
+      return new ApacuanaSuccess({ status });
+    }
+    throw error;
+  }
+};
+
+const validateFaceLivenessOnPremise = async () => {
+  throw new ApacuanaAPIError(
+    "Validating a Face Liveness session is not supported for integration type: ONPREMISE",
+    501,
+    "NOT_IMPLEMENTED"
+  );
+};
+
+/**
+ * Creates a new Face Liveness session.
+ * @returns {Promise<CreateFaceLivenessSessionResponse>} Object with the session ID and a success indicator.
+ * @throws {ApacuanaAPIError} If the API response is invalid or the integration type is not supported.
+ * @throws {Error} If the request fails for another reason.
+ */
+export const createFaceLivenessSession = async () => {
+  const { integrationType } = getConfig();
+
+  if (integrationType === INTEGRATION_TYPE.ONBOARDING) {
+    return createFaceLivenessSessionOnBoarding();
+  }
+  if (integrationType === INTEGRATION_TYPE.ONPREMISE) {
+    return createFaceLivenessSessionOnPremise();
+  }
+
+  throw new ApacuanaAPIError(
+    `Unsupported integration type: ${integrationType}`,
+    400,
+    "UNSUPPORTED_INTEGRATION_TYPE"
+  );
+};
+
+/**
+ * Validates a Face Liveness session and returns its status.
+ * @param {{sessionId: string}} params - Object containing the session ID.
+ * @returns {Promise<ApacuanaSuccess>} Object with the validation status.
+ * @throws {ApacuanaAPIError} If the API response is invalid or the integration type is not supported.
+ */
+export const validateFaceLiveness = async ({ sessionId }) => {
+  if (!sessionId) {
+    throw new ApacuanaAPIError(
+      "sessionId is a required parameter.",
+      400,
+      "INVALID_PARAMETER"
+    );
+  }
+
+  const { integrationType } = getConfig();
+
+  if (integrationType === INTEGRATION_TYPE.ONBOARDING) {
+    return validateFaceLivenessOnBoarding(sessionId);
+  }
+  if (integrationType === INTEGRATION_TYPE.ONPREMISE) {
+    return validateFaceLivenessOnPremise();
+  }
+
+  throw new ApacuanaAPIError(
+    `Unsupported integration type: ${integrationType}`,
+    400,
+    "UNSUPPORTED_INTEGRATION_TYPE"
+  );
+};

package/src/api/revocations.js

@@ -1,95 +1,109 @@
 import { httpRequest } from "../utils/httpClient";
-import { ApacuanaAPIError } from "../errors/index";
 import { getConfig } from "../config";
 import { INTEGRATION_TYPE } from "../utils/constant";
+import { ApacuanaAPIError } from "../errors";
+import ApacuanaSuccess from "../success";
 
-/**
- * @typedef {object} RequestRevocationResponse
- * @property {string} revocationStatus - El estado de la solicitud de revocación (e.g., "pending").
- * @property {string|number} requestId - El ID de la solicitud de revocación.
- */
-
-/**
- * Simula la solicitud de revocación de un certificado.
- * @param {string} reasonCode - Código o descripción del motivo de la revocación.
- * @returns {Promise<RequestRevocationResponse>} Objeto con el estado de la solicitud de revocación.
- */
-/**
- * @typedef {object} RevocationResponse
- * @property {boolean} success - Indicates if the revocation request was successful.
- * @property {string} [message] - A message providing details about the outcome.
- */
-
-/**
- * @typedef {object} RevocationReason
- * @property {string} code - The code for the revocation reason.
- * @property {string} description - The description of the revocation reason.
- */
-
-/**
- * @typedef {object} RevocationReasonsResponse
- * @property {boolean} success - Indicates if the request was successful.
- * @property {RevocationReason[]} reasons - A list of revocation reasons.
- */
-
-/**
- * Requests the revocation of a certificate.
- * @param {number} reasonCode - Código o descripción del motivo de la revocación.
- * @returns {Promise<RevocationResponse>} An object indicating the success of the request.
- * @throws {ApacuanaAPIError} If the revocation request fails.
- */
-export const requestRevocation = async (reasonCode) => {
-  if (!reasonCode) {
-    throw new Error("Código de motivo es requerido para requestRevocation.");
-  }
+/** @typedef {import("../types/revocations").RequestRevocationResponse} RequestRevocationResponse */
+/** @typedef {import("../types/revocations").GetRevocationReasonsResponse} GetRevocationReasonsResponse */
 
+const requestRevocationOnBoarding = async (params) => {
   try {
     const response = await httpRequest(
       "services/api/onboardingclient/requestcert",
-      { reason: reasonCode },
+      params,
       "POST"
     );
-
-    return response;
+    return new ApacuanaSuccess(response);
   } catch (error) {
-    throw new Error(`Fallo en la solicitud de revocación: ${error.message}`);
+    if (error instanceof ApacuanaAPIError) {
+      throw error;
+    }
+    throw new Error(`Failed to request revocation: ${error.message}`);
   }
 };
 
+const requestRevocationOnPremise = async () => {
+  throw new ApacuanaAPIError(
+    "Requesting revocation is not supported for integration type: ONPREMISE",
+    501,
+    "NOT_IMPLEMENTED"
+  );
+};
+
 /**
- * Retrieves the available reasons for certificate revocation.
- * @returns {Promise<RevocationReasonsResponse>} An object containing the list of revocation reasons.
- * @throws {ApacuanaAPIError} If fetching the reasons fails.
+ * Solicita la revocación de un certificado.
+ * @param {object} params - Parámetros para la solicitud.
+ * @param {number} params.reasonCode - El código de la razón de la revocación.
+ * @returns {Promise<RequestRevocationResponse>} Una promesa que resuelve con la confirmación de la solicitud.
+ * @throws {Error} Si los parámetros son inválidos.
  */
-export const getRevocationReasons = async () => {
+export const requestRevocation = async (params) => {
+  if (!params || typeof params.reasonCode !== "number") {
+    throw new Error(
+      'The "params" object with a numeric "reasonCode" property is required.'
+    );
+  }
+
   const { integrationType } = getConfig();
 
+  if (integrationType === INTEGRATION_TYPE.ONBOARDING) {
+    return requestRevocationOnBoarding(params);
+  }
   if (integrationType === INTEGRATION_TYPE.ONPREMISE) {
-    throw new ApacuanaAPIError(
-      `Get revocation reasons is not supported for integration type: ${integrationType}`,
-      501,
-      "NOT_IMPLEMENTED"
-    );
+    return requestRevocationOnPremise(params);
   }
+  throw new ApacuanaAPIError(
+    `Unsupported integration type: ${integrationType}`,
+    400,
+    "UNSUPPORTED_INTEGRATION_TYPE"
+  );
+};
 
+const getRevocationReasonsOnBoarding = async () => {
   try {
     const response = await httpRequest(
-      "GET",
       "config/api/revocation/reasonsonboarding",
-      {}
+      {},
+      "GET"
     );
-
-    if (!response.records) {
+    if (!response || !response.records) {
       throw new ApacuanaAPIError("Failed to fetch revocation reasons.");
     }
-
-    return response.records;
+    return new ApacuanaSuccess({ reasons: response.records });
   } catch (error) {
     if (error instanceof ApacuanaAPIError) {
       throw error;
     }
-    throw new Error(
-      "Failed to get revocation reasons. Please try again later."
-    );
+    throw new Error(`Failed to get revocation reasons: ${error.message}`);
+  }
+};
+
+const getRevocationReasonsOnPremise = async () => {
+  throw new ApacuanaAPIError(
+    "Getting revocation reasons is not supported for integration type: ONPREMISE",
+    501,
+    "NOT_IMPLEMENTED"
+  );
+};
+
+/**
+ * Obtiene la lista de razones de revocación de certificados.
+ * @returns {Promise<GetRevocationReasonsResponse>} Una promesa que resuelve con la lista de razones de revocación.
+ * @throws {ApacuanaAPIError} Si la llamada a la API falla o el tipo de integración no es soportado.
+ */
+export const getRevocationReasons = async () => {
+  const { integrationType } = getConfig();
+
+  if (integrationType === INTEGRATION_TYPE.ONBOARDING) {
+    return getRevocationReasonsOnBoarding();
+  }
+  if (integrationType === INTEGRATION_TYPE.ONPREMISE) {
+    return getRevocationReasonsOnPremise();
   }
+  throw new ApacuanaAPIError(
+    `Unsupported integration type: ${integrationType}`,
+    400,
+    "UNSUPPORTED_INTEGRATION_TYPE"
+  );
 };

package/src/api/signatures.js

@@ -2,72 +2,20 @@
 import { getConfig } from "../config/index";
 import { httpRequest } from "../utils/httpClient";
 import { ApacuanaAPIError } from "../errors";
+import ApacuanaSuccess from "../success";
 import helpers from "../utils/helpers";
 import { INTEGRATION_TYPE } from "../utils/constant";
 
-// =================================================================
-// Type Definitions
-// =================================================================
-
-/**
- * Define la estructura de un objeto Firmante.
- * @typedef {object} Signer
- * @property {string} name - Nombre completo del firmante.
- * @property {string} email - Correo electrónico del firmante.
- * @property {string} document - Documento de identidad del firmante.
- */
-
-/**
- * Define la estructura de datos para añadir un firmante.
- * @typedef {object} SignerData
- * @property {string} docId - Identificador único del documento.
- */
-
-/**
- * Define la estructura de la respuesta al añadir un firmante.
- * @typedef {object} AddSignerResponse
- * @property {string} signer - Identificador de confirmación del firmante añadido.
- * @property {boolean} success - Indica si la operación fue exitosa.
- */
-
-/**
- * Define la estructura de datos para obtener el digest de un documento.
- * @typedef {object} GetDigestData
- * @property {string} cert - Certificado del firmante en formato base64.
- * @property {string} signatureId - Identificador único del proceso de firma.
- */
-
-/**
- * Define la estructura de la respuesta al obtener el digest.
- * @typedef {object} GetDigestResponse
- * @property {string} digest - El digest del documento que se va a firmar.
- * @property {boolean} success - Indica si la operación fue exitosa.
- */
-
-/**
- * Define la estructura de los parámetros para obtener documentos.
- * @typedef {object} GetDocsParams
- * @property {number} page - Número de página para la paginación.
- * @property {number} size - Cantidad de registros por página.
- * @property {string} [status] - (Opcional) Estado para filtrar los documentos.
- */
-
-/**
- * Define la estructura de la respuesta al obtener documentos.
- * @typedef {object} GetDocsResponse
- * @property {number} totalRecords - El número total de registros encontrados.
- * @property {Array<object>} records - Un arreglo con los registros de los documentos.
- * @property {boolean} success - Indica si la operación fue exitosa.
- */
-
-/**
- * @typedef {object} SignDocumentData
- * @property {object} signature - Objeto con información de la firma.
- * @property {string} signature.id - ID de la firma.
- * @property {Array<object>} signature.positions - Posiciones de la firma.
- * @property {string} cert - Certificado en base64.
- * @property {string} signedDigest - Digest firmado.
- */
+/** @typedef {import("../types/signatures").Signer} Signer */
+/** @typedef {import("../types/signatures").SignerData} SignerData */
+/** @typedef {import("../types/signatures").AddSignerResponse} AddSignerResponse */
+/** @typedef {import("../types/signatures").GetDigestData} GetDigestData */
+/** @typedef {import("../types/signatures").GetDigestResponse} GetDigestResponse */
+/** @typedef {import("../types/signatures").GetDocsParams} GetDocsParams */
+/** @typedef {import("../types/signatures").GetDocsResponse} GetDocsResponse */
+/** @typedef {import("../types/signatures").SignDocumentData} SignDocumentData */
+/** @typedef {import("../types/signatures").SignaturePosition} SignaturePosition */
+/** @typedef {import("../types/signatures").OnboardingSignerData} OnboardingSignerData */
 
 // =================================================================
 // Internal Functions
@@ -95,7 +43,7 @@ const signDocumentOnBoarding = async (signData) => {
       signBody,
       "PUT"
     );
-    return response;
+    return new ApacuanaSuccess(response);
   } catch (error) {
     if (error instanceof ApacuanaAPIError) {
       throw error;
@@ -132,7 +80,7 @@ const getDigestToSignOnBoarding = async (signData) => {
       );
     }
 
-    return { digest, success: true };
+    return new ApacuanaSuccess({ digest });
   } catch (error) {
     if (error.name === "ApacuanaAPIError") {
       throw error;
@@ -155,7 +103,9 @@ const addSignerOnBoarding = async (signerData) => {
   helpers.validateOnBoardingSignerData(signerData);
   try {
     await httpRequest("services/api/documents/signing", signerData, "POST");
-    return { signer: signerData.typedoc + signerData.doc, success: true };
+    return new ApacuanaSuccess({
+      signer: signerData.typedoc + signerData.doc,
+    });
   } catch (error) {
     if (error instanceof ApacuanaAPIError) {
       throw error;
@@ -203,11 +153,10 @@ const getDocsOnBoarding = async (data) => {
 
     const apiUrl = `services/api/documents/listcustomer?${params.toString()}`;
     const response = await httpRequest(apiUrl, {}, "GET");
-    return {
+    return new ApacuanaSuccess({
       totalRecords: response.numofrecords,
       records: response.records,
-      success: true,
-    };
+    });
   } catch (error) {
     if (error.name === "ApacuanaAPIError") {
       throw error;
@@ -225,7 +174,7 @@ const uploadSignatureVariantOnBoarding = async ({ file }) => {
       { file },
       "POST"
     );
-    return { ...response, success: true };
+    return new ApacuanaSuccess(response);
   } catch (error) {
     if (error instanceof ApacuanaAPIError) {
       throw error;
@@ -252,7 +201,7 @@ const getSignatureVariantOnBoarding = async () => {
       {},
       "GET"
     );
-    return { ...response, success: true };
+    return new ApacuanaSuccess(response);
   } catch (error) {
     if (error instanceof ApacuanaAPIError) {
       throw error;
@@ -278,7 +227,7 @@ const deleteSignatureVariantOnBoarding = async () => {
       {},
       "DELETE"
     );
-    return { ...response, success: true };
+    return new ApacuanaSuccess(response);
   } catch (error) {
     if (error instanceof ApacuanaAPIError) {
       throw error;
@@ -358,31 +307,6 @@ export const getDigest = async (signData) => {
  * @returns {Promise<AddSignerResponse>} Una promesa que resuelve a un objeto con el resultado de la operación.
  * @throws {ApacuanaAPIError} Si los datos del firmante son inválidos, la llamada a la API falla, o el tipo de integración no es soportado.
  */
-/**
- * @typedef {object} SignaturePosition
- * @property {number} page - The page number for the signature.
- * @property {number} x - The x-coordinate for the signature's position (from 0 to 1).
- * @property {number} y - The y-coordinate for the signature's position (from 0 to 1).
- */
-
-/**
- * @typedef {object} OnboardingSignerData
- * @property {string} name - The name of the document.
- * @property {string} reference - An external reference for the document.
- * @property {string} typedoc - The type of document of the signer (e.g., "V", "E", "J").
- * @property {string} doc - The document number of the signer.
- * @property {SignaturePosition[]} signature - An array of signature positions.
- */
-
-/**
- * Adds a new signer to the signature process.
- * This function acts as a dispatcher, delegating to the appropriate implementation
- * based on the configured integration type.
- *
- * @param {OnboardingSignerData | object} signerData - The signer's data. The structure depends on the integration type.
- * @returns {Promise<object>} The result from the API.
- * @throws {ApacuanaAPIError} If signerData is invalid or if the integration type is not supported.
- */
 export const addSigner = async (signerData) => {
   if (
     !signerData ||