apacuana-sdk-core 0.10.0 → 0.11.0

package/src/index.js

@@ -7,6 +7,7 @@ import {
   getCertStatus,
   getCertTypes,
   getRequerimentsByTypeUser,
+  requestCertificate,
 } from "./api/certs";
 import {
   addSigner,
@@ -17,6 +18,10 @@ import {
   signDocument,
   uploadSignatureVariant,
 } from "./api/signatures";
+import {
+  createFaceLivenessSession,
+  validateFaceLiveness,
+} from "./api/faceLiveness";
 
 const apacuana = {
   /**
@@ -68,6 +73,9 @@ const apacuana = {
   deleteSignatureVariant,
   getCertTypes,
   getRequerimentsByTypeUser,
+  createFaceLivenessSession,
+  validateFaceLiveness,
+  requestCertificate,
 };
 
 export default apacuana;

package/src/success/index.js

@@ -0,0 +1,8 @@
+export default class ApacuanaSuccess {
+  constructor(data, statusCode = 200) {
+    this.success = true;
+    this.statusCode = statusCode;
+    this.name = "ApacuanaSuccess";
+    this.data = data;
+  }
+}

package/src/types/certs.js

@@ -0,0 +1,56 @@
+/**
+ * @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.
+ */
+
+/**
+ * @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.
+ */
+
+/**
+ * @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.
+ */
+
+/**
+ * @typedef {object} CertificateRequestParams
+ * @property {number} type - The user type to get requirements for.
+ * @property {string} [observation] - An optional observation for the certificate request.
+ * @property {Array<{id: string, file: string}>} documents - The documents required for the certificate.
+ */
+
+/**
+ * @typedef {object} RequestCertificateResponse
+ * @property {string} message - A message confirming the request.
+ * @property {boolean} success - Indicates if the operation was successful.
+ */
+
+export {};

package/src/types/faceLiveness.js

@@ -0,0 +1,7 @@
+/**
+ * @typedef {object} CreateFaceLivenessSessionResponse
+ * @property {string} sessionId - The session ID for the face liveness check.
+ * @property {boolean} success - Indicates if the operation was successful.
+ */
+
+export {};

package/src/types/revocations.js

@@ -0,0 +1,25 @@
+/**
+ * @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.
+ */
+
+/**
+ * @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.
+ */
+
+export {};

package/src/types/signatures.js

@@ -0,0 +1,77 @@
+/**
+ * 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 {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.
+ */
+
+export {};

package/src/types/users.js

@@ -0,0 +1,73 @@
+/**
+ * @typedef {object} UserData
+ * @property {string} email - Correo electrónico. No puede contener espacios y tiene un máximo de 128 caracteres.
+ * @property {number} typeuser - Tipo de usuario. Debe ser un ID valido.
+ * @property {string} name - Nombre de la persona.
+ * @property {string} lastname - Apellido de la persona.
+ * @property {'V' | 'P' | 'E'} kinddoc - Tipo de documento de identidad. Puede ser 'V' (Venezolano), 'P' (Pasaporte) o 'E' (Extranjero).
+ * @property {number} doc - Número de documento de identidad. Debe ser un número entero.
+ * @property {string} birthdate - Fecha de nacimiento. Debe ser una fecha válida en formato ISO y no puede ser una fecha futura.
+ * @property {'J' | 'G' | 'V' | 'P' | 'E'} kindrif - Tipo de RIF (Registro de Información Fiscal). Puede ser 'J', 'G', 'V', 'P' o 'E'.
+ * @property {'M' | 'F' | 'Sin especificar'} gender - Género. Puede ser 'M' (Masculino), 'F' (Femenino) o 'Sin especificar'.
+ * @property {number} rif - Número de RIF. Debe ser un número entero.
+ * @property {number} phone - Número de teléfono. Debe ser un número entero.
+ * @property {string} kindphone - Código de área del teléfono. Ej. 0424.
+ * @property {string} state - Nombre del estado.
+ * @property {string} municipality - Nombre del municipio.
+ * @property {string} parish - Nombre de la parroquia.
+ * @property {string} postalcode - Código postal.
+ * @property {string} address - Dirección.
+ * @property {string} fiscaladdress - Dirección fiscal.
+ * @property {string} fiscalkindphone - Código de área del teléfono fiscal. Ej. 0424.
+ * @property {number} fiscalphone - Número de teléfono fiscal. Debe ser un número entero.
+ * @property {string} occupation - Ocupacion de la persona.
+ * @property {string} degree - Título universitario.
+ * @property {string} university - Universidad.
+ * @property {string} graduationyear - Año de graduación.
+ * @property {string} collegiatenumber - Número de colegiado.
+ * @property {string} collegiateyear - Año de colegiatura.
+ * @property {string} companyname - Nombre de la empresa.
+ * @property {'J' | 'G' | 'V' | 'P' | 'E'} companykindrif - Tipo de RIF de la empresa. Puede ser 'J', 'G', 'V', 'P' o 'E'.
+ * @property {string} companyrif - Número de RIF de la empresa.
+ * @property {string} companystate - Estado de la empresa.
+ * @property {string} companymunicipality - Municipio de la empresa.
+ * @property {string} companyparish - Parroquia de la empresa.
+ * @property {string} companyaddress - Dirección de la empresa.
+ * @property {string} companykindphone - Código de área del teléfono de la empresa. Ej. 0212.
+ * @property {string} companyphone - Número de teléfono de la empresa.
+ * @property {string} companypostalcode - Código postal de la empresa.
+ * @property {string} companywebpage - Página web de la empresa.
+ * @property {string} companycommercialregister - Registro comercial de la empresa.
+ * @property {string} companyregisterdate - Fecha de registro de la empresa en formato ISO.
+ * @property {string} companyregisternumber - Número de registro de la empresa.
+ * @property {string} companyconstitutiondate - Fecha de constitución de la empresa en formato ISO.
+ * @property {string} companypublishdate - Fecha de publicación del decreto de constitución. Debe ser una fecha válida en formato ISO y no puede ser una fecha futura.
+ * @property {string} companyconstitutiondecree - Decreto de constitución de la empresa. Máximo 32 caracteres.
+ * @property {string} companynumberdecree - Número de decreto de la empresa. Máximo 16 caracteres.
+ * @property {string} positionprivate - Cargo empleado empresa privada.
+ * @property {string} departmentprivate - Departamento empleado empresa privada.
+ * @property {string} authorizedprivate - Autorizado de por empleado empresa privada.
+ * @property {string} functionsprivate - Funciones empleado empresa privada.
+ * @property {string} publishprivate - Fecha de publicación de la gaceta de la empresa privada.
+ * @property {string} issuedateprivate - Fecha de registro de la empresa privada. Debe ser una fecha válida en formato ISO.
+ * @property {string} kindphoneprivate - Código de área del teléfono de la empresa privada. ej. 0424.
+ * @property {number} phoneprivate - Número de teléfono privado. Debe ser un número entero.
+ * @property {string} positionpublic - Cargo empleado empresa publica.
+ * @property {string} departmentpublic - Departamento empleado empresa publica.
+ * @property {string} authorizedpublic - Autorizado empleado empresa publica.
+ * @property {string} functionspublic - Funciones de empleado empresa publica.
+ * @property {string} publishpublic - Fecha de publicación de la gaceta de la empresa pública.
+ * @property {string} issuedatepublic - Fecha de registro de la empresa pública. Debe ser una fecha válida en formato ISO.
+ * @property {string} kindphonepublic - Código de área del teléfono de la empresa publica. ej 0424.
+ * @property {number} phonepublic - Número de teléfono público. Debe ser un número entero.
+ * @property {string} companyid - ID de la empresa. Debe ser un UUID para la creacion de empleados.
+ */
+
+/**
+ * @typedef {object} GetCustomerResponse
+ * @property {string} token - El token de sesión del usuario.
+ * @property {UserData} userData - Los datos del usuario obtenidos.
+ * @property {boolean} success - Indica si la operación fue exitosa.
+ */
+
+export {};

package/tests/api/certs.test.js

@@ -2,11 +2,13 @@ import { getConfig } from "../../src/config/index";
 import { httpRequest } from "../../src/utils/httpClient";
 import helpers from "../../src/utils/helpers";
 import { ApacuanaAPIError } from "../../src/errors";
+import ApacuanaSuccess from "../../src/success";
 import {
   generateCert,
   getCertStatus,
   getCertTypes,
   getRequerimentsByTypeUser,
+  requestCertificate,
 } from "../../src/api/certs";
 import { INTEGRATION_TYPE } from "../../src/utils/constant";
 
@@ -43,10 +45,10 @@ describe("Certificate API - certs.js", () => {
         mockEncryptedCsr,
         "POST"
       );
-      expect(result).toEqual({
+      expect(result).toBeInstanceOf(ApacuanaSuccess);
+      expect(result.data).toEqual({
         cert: "onboarding-cert",
         certifiedid: "onboarding-certified-id",
-        success: true,
       });
     });
 
@@ -93,7 +95,8 @@ describe("Certificate API - certs.js", () => {
         mockUserData,
         true
       );
-      expect(result).toEqual({ status: "VALID", success: true });
+      expect(result).toBeInstanceOf(ApacuanaSuccess);
+      expect(result.data).toEqual({ status: "VALID" });
     });
   });
 
@@ -112,7 +115,8 @@ describe("Certificate API - certs.js", () => {
         {},
         "GET"
       );
-      expect(result).toEqual({ types: mockApiResponse.types, success: true });
+      expect(result).toBeInstanceOf(ApacuanaSuccess);
+      expect(result.data).toEqual({ types: mockApiResponse.types });
     });
 
     it("should throw an error for ONPREMISE integration", async () => {
@@ -159,9 +163,9 @@ describe("Certificate API - certs.js", () => {
         {},
         "GET"
       );
-      expect(result).toEqual({
+      expect(result).toBeInstanceOf(ApacuanaSuccess);
+      expect(result.data).toEqual({
         requirements: mockApiResponse.requirements,
-        success: true,
       });
     });
 
@@ -202,5 +206,94 @@ describe("Certificate API - certs.js", () => {
         'The "params" object with a numeric "type" property is required.'
       );
     });
+    it("should throw a generic error for other failures", async () => {
+      getConfig.mockReturnValue({
+        integrationType: INTEGRATION_TYPE.ONBOARDING,
+      });
+      const genericError = new Error("Network failure");
+      httpRequest.mockRejectedValue(genericError);
+
+      await expect(getRequerimentsByTypeUser({ type: 1 })).rejects.toThrow(
+        `Failed to get requirements: ${genericError.message}`
+      );
+    });
+  });
+});
+
+describe("requestCertificate", () => {
+  const validParams = { type: 1, documents: [] };
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("should throw an error if params are invalid", async () => {
+    await expect(requestCertificate()).rejects.toThrow(
+      'The "params" object with a numeric "type" property and a "documents" array is required.'
+    );
+    await expect(requestCertificate({ type: 1 })).rejects.toThrow(
+      'The "params" object with a numeric "type" property and a "documents" array is required.'
+    );
+    await expect(requestCertificate({ documents: [] })).rejects.toThrow(
+      'The "params" object with a numeric "type" property and a "documents" array is required.'
+    );
+  });
+
+  it("should request a certificate for ONBOARDING integration", async () => {
+    getConfig.mockReturnValue({ integrationType: INTEGRATION_TYPE.ONBOARDING });
+    const mockResponse = { message: "Certificate requested" };
+    httpRequest.mockResolvedValue(mockResponse);
+
+    const result = await requestCertificate(validParams);
+
+    expect(result).toBeInstanceOf(ApacuanaSuccess);
+    expect(result.data).toEqual(mockResponse);
+    expect(httpRequest).toHaveBeenCalledWith(
+      "services/api/customer/request-certificate",
+      validParams,
+      "POST"
+    );
+  });
+
+  it("should throw a NOT_IMPLEMENTED error for ONPREMISE integration", async () => {
+    getConfig.mockReturnValue({ integrationType: INTEGRATION_TYPE.ONPREMISE });
+
+    await expect(requestCertificate(validParams)).rejects.toThrow(
+      new ApacuanaAPIError(
+        "Requesting a certificate is not supported for integration type: ONPREMISE",
+        501,
+        "NOT_IMPLEMENTED"
+      )
+    );
+  });
+
+  it("should throw an UNSUPPORTED_INTEGRATION_TYPE error for unsupported integration types", async () => {
+    getConfig.mockReturnValue({ integrationType: "unsupported-type" });
+
+    await expect(requestCertificate(validParams)).rejects.toThrow(
+      new ApacuanaAPIError(
+        "Unsupported integration type: unsupported-type",
+        400,
+        "UNSUPPORTED_INTEGRATION_TYPE"
+      )
+    );
+  });
+
+  it("should re-throw ApacuanaAPIError if caught", async () => {
+    getConfig.mockReturnValue({ integrationType: INTEGRATION_TYPE.ONBOARDING });
+    const apiError = new ApacuanaAPIError("API Error", 500, "API_ERROR");
+    httpRequest.mockRejectedValue(apiError);
+
+    await expect(requestCertificate(validParams)).rejects.toThrow(apiError);
+  });
+
+  it("should throw a generic error for other failures", async () => {
+    getConfig.mockReturnValue({ integrationType: INTEGRATION_TYPE.ONBOARDING });
+    const genericError = new Error("Network failure");
+    httpRequest.mockRejectedValue(genericError);
+
+    await expect(requestCertificate(validParams)).rejects.toThrow(
+      `Failed to request certificate: ${genericError.message}`
+    );
   });
 });

package/tests/api/faceLiveness.test.js

@@ -0,0 +1,172 @@
+import * as faceLiveness from "../../src/api/faceLiveness";
+import { httpRequest } from "../../src/utils/httpClient";
+import { getConfig } from "../../src/config";
+import { ApacuanaAPIError } from "../../src/errors";
+import ApacuanaSuccess from "../../src/success";
+import { INTEGRATION_TYPE } from "../../src/utils/constant";
+
+jest.mock("../../src/utils/httpClient", () => ({
+  httpRequest: jest.fn(),
+}));
+
+jest.mock("../../src/config", () => ({
+  getConfig: jest.fn(),
+}));
+
+describe("FaceLiveness API", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    getConfig.mockReturnValue({ integrationType: INTEGRATION_TYPE.ONBOARDING });
+  });
+
+  describe("createFaceLivenessSession", () => {
+    it("should create a session for ONBOARDING integration", async () => {
+      httpRequest.mockResolvedValue({ sessionId: "test-session-id" });
+
+      const result = await faceLiveness.createFaceLivenessSession();
+
+      expect(result).toBeInstanceOf(ApacuanaSuccess);
+      expect(result.data).toEqual({ sessionId: "test-session-id" });
+      expect(httpRequest).toHaveBeenCalledWith(
+        "services/api/faceliveness/create",
+        {},
+        "POST"
+      );
+    });
+
+    it("should throw an error if API response does not contain sessionId for ONBOARDING", async () => {
+      httpRequest.mockResolvedValue({}); // No sessionId
+
+      await expect(faceLiveness.createFaceLivenessSession()).rejects.toThrow(
+        new ApacuanaAPIError(
+          "The API response does not contain the session ID.",
+          undefined,
+          "INVALID_API_RESPONSE"
+        )
+      );
+    });
+
+    it("should throw a NOT_IMPLEMENTED error for ONPREMISE integration", async () => {
+      getConfig.mockReturnValue({
+        integrationType: INTEGRATION_TYPE.ONPREMISE,
+      });
+
+      await expect(faceLiveness.createFaceLivenessSession()).rejects.toThrow(
+        new ApacuanaAPIError(
+          "Creating a Face Liveness session is not supported for integration type: ONPREMISE",
+          501,
+          "NOT_IMPLEMENTED"
+        )
+      );
+    });
+
+    it("should throw an UNSUPPORTED_INTEGRATION_TYPE error for unsupported integration types", async () => {
+      getConfig.mockReturnValue({ integrationType: "unsupported-type" });
+
+      await expect(faceLiveness.createFaceLivenessSession()).rejects.toThrow(
+        new ApacuanaAPIError(
+          "Unsupported integration type: unsupported-type",
+          400,
+          "UNSUPPORTED_INTEGRATION_TYPE"
+        )
+      );
+    });
+
+    it("should re-throw ApacuanaAPIError if caught during session creation", async () => {
+      const apiError = new ApacuanaAPIError("API Error", 500, "API_ERROR");
+      httpRequest.mockRejectedValue(apiError);
+
+      await expect(faceLiveness.createFaceLivenessSession()).rejects.toThrow(
+        apiError
+      );
+    });
+
+    it("should throw a generic error for other failures during session creation", async () => {
+      const genericError = new Error("Network Error");
+      httpRequest.mockRejectedValue(genericError);
+
+      await expect(faceLiveness.createFaceLivenessSession()).rejects.toThrow(
+        `Failed to create Face Liveness session: ${genericError.message}`
+      );
+    });
+  });
+
+  describe("validateFaceLiveness", () => {
+    const sessionId = "test-session-id";
+
+    it("should throw an error if sessionId is not provided", async () => {
+      await expect(faceLiveness.validateFaceLiveness({})).rejects.toThrow(
+        new ApacuanaAPIError(
+          "sessionId is a required parameter.",
+          400,
+          "INVALID_PARAMETER"
+        )
+      );
+    });
+
+    it("should return 'verified' on status 200", async () => {
+      httpRequest.mockResolvedValue({ someData: "data" });
+
+      const result = await faceLiveness.validateFaceLiveness({ sessionId });
+
+      expect(result).toBeInstanceOf(ApacuanaSuccess);
+      expect(result.data).toEqual({ status: "verified", someData: "data" });
+      expect(httpRequest).toHaveBeenCalledWith(
+        "services/api/faceliveness/validate",
+        { sessionid: sessionId },
+        "POST"
+      );
+    });
+
+    it.each([
+      [402, "waitingForScan"],
+      [403, "rejected"],
+      [406, "processing"],
+      [408, "expired"],
+    ])(
+      "should return status '%s' for statusCode %i",
+      async (statusCode, status) => {
+        const apiError = new ApacuanaAPIError(
+          "Error",
+          statusCode,
+          "API_ERROR"
+        );
+        httpRequest.mockRejectedValue(apiError);
+
+        const result = await faceLiveness.validateFaceLiveness({ sessionId });
+
+        expect(result).toBeInstanceOf(ApacuanaSuccess);
+        expect(result.data).toEqual({ status });
+      }
+    );
+
+    it("should throw an error for unhandled status codes", async () => {
+      const apiError = new ApacuanaAPIError(
+        "Unhandled Error",
+        500,
+        "API_ERROR"
+      );
+      httpRequest.mockRejectedValue(apiError);
+
+      await expect(
+        faceLiveness.validateFaceLiveness({ sessionId })
+      ).rejects.toThrow(apiError);
+    });
+
+    it("should throw a NOT_IMPLEMENTED error for ONPREMISE integration", async () => {
+      getConfig.mockReturnValue({
+        integrationType: INTEGRATION_TYPE.ONPREMISE,
+      });
+
+      await expect(
+        faceLiveness.validateFaceLiveness({ sessionId })
+      ).rejects.toThrow(
+        new ApacuanaAPIError(
+          "Validating a Face Liveness session is not supported for integration type: ONPREMISE",
+          501,
+          "NOT_IMPLEMENTED"
+        )
+      );
+    });
+  });
+});