@bizzsv/bizz-payment 1.2.2

package/README.md

@@ -0,0 +1,191 @@
+# BizPaymentForm SDK
+
+The BizPaymentForm SDK is designed to provide a secure and isolated form for payment integration.
+
+## Technologies version required
+
+- **Node.js:** 24.14.0 or higher
+- **Vite:** 8.0.1 or higher
+- **TypeScript:** 5.9.3 or higher
+
+In the root of the project, we have .nvmrc file, if you have installed nvm, you can run
+```bash
+nvm use
+```
+to use the correct version of Node.js. If you don't have nvm installed, you can install it [here](https://github.com/nvm-sh/nvm).
+
+
+## Plugins/packages used
+
+This package is the only one that uses for productions.
+
+- **Maska:** Used to mask the input fields, like credit card, number, expiration date, CVV, etc.
+- **Node-Forge:** Used to generate the PKCE challenge and verifier for the OAuth 2.0 flow.
+- **Dompurify:** Used to sanitize the HTML for prevent XSS attacks.
+
+
+## Features includes
+- **Payments without 3DS:** show the form without 3DS if the commerce does not have 3DS enabled.
+- **Payments with 3DS:** show the form with 3DS if the commerce has 3DS enabled.
+
+## Development Workflow: Vite Bundle Plugin
+
+To keep the project scalable and maintainable while using `srcdoc`, we implemented a custom Vite plugin:
+
+1. **TypeScript Native:** We write the iframe logic using modern TypeScript and imports.
+2. **IIFE Transformation:** Vite compiles the entire dependency tree of the iframe into a single, minified, self-executing string (IIFE).
+3. **Dynamic Injection:** This string is injected into the `iframeContent.html` generator, making it available for the `srcdoc` at runtime.
+
+## How run the project
+
+Native development server with Vite:
+
+```bash
+pnpm dev
+```
+
+React development server with Vite:
+
+```bash
+pnpm examples:react:dev
+```
+
+Vue development server with Vite:
+
+```bash
+pnpm examples:vue:dev
+```
+
+Angular development server with Vite:
+
+You need have installed the Angular CLI globally to run the development server. Read more about how to install the Angular CLI [here](https://angular.dev/installation).
+
+```bash
+pnpm install -g @angular/cli
+```
+then:
+```bash
+pnpm examples:angular:dev
+```
+
+Note: for run the examples (React, Vue, Angular), you need to build the project first.
+
+```bash
+pnpm build
+```
+
+### Testing
+
+The project has two types of tests:
+- Unit tests: for testing the iframe logic.
+- End-to-end tests: for testing the iframe in the browser.
+
+To run the tests, you need to run the following command:
+
+```bash
+pnpm test
+```
+
+To run the tests in watch mode, you need to run the following command:
+
+```bash
+pnpm test:watch
+```
+
+To run the end-to-end tests, you need to run the following command:
+
+```bash
+pnpm test:e2e
+```
+
+To run the end-to-end tests, you need to run the following command:
+
+```bash
+pnpm test:e2e
+```
+or run the tests with the UI:
+
+```bash
+pnpm test:e2e:ui
+```
+
+### Documentation website
+
+The documentation is built with Starlight and is hosted in the `docs` directory, run on Astro, and its SSR.
+
+To run the documentation server, you need to run the following command:
+
+```bash
+pnpm docs:dev
+```
+
+To build the documentation, you need to run the following command:
+
+```bash
+pnpm docs:build
+```
+
+To preview the documentation, you need to run the following command:
+
+```bash
+pnpm docs:preview
+```
+
+### Build the project
+
+```bash
+pnpm build
+```
+
+### Serfinsa cards documentation for 3ds implementation
+
+[Read more](https://developer.cardinaltrusted.com/reference/emv-3ds-test-cases-challenge)
+[Read documentation for Cardinal integration](https://developer.cardinaltrusted.com/docs/cardinal-cruise-integration)
+
+### Cards for testing
+
+The expiration data can be 01/2027 or 01/2028, always the year must be in the future.
+
+| Card type | PAN | Cvv | Fecha | Friction |
+|-----------|-----|-----|-------|----------|
+| Visa | 4000000000002701 | 123 | 01 / 2027 | No |
+| Mastercard | 5200000000002235 | 123 | 01 / 2027 | No |
+| Visa | 4000000000002503 | 123 | 01 / 2027 | Yes |
+| Mastercard | 5200000000002151 | 123 | 01 / 2027 | Yes |
+
+
+For no 3DS cards
+
+| Card type | PAN | Cvv | Fecha | Friction | Failed |
+|-----------|-----|-----|-------|----------|--------|
+| Visa | 4242000000000851 | 123 | 01 / 2027 | No | Yes |
+| Visa | 4242000000000000 | 123 | 01 / 2027 | No | No |
+| UnionPay | 6215000000003218 | 123 | 01 / 2027 | No | No |
+
+
+## Security: The `srcdoc` Approach
+
+The package encapsulates the payment form inside an `iframe` with the `srcdoc` attribute. This architectural decision provides several critical security and operational benefits:
+
+### 1. Isolation & Anti-XSS
+By using `srcdoc`, the form lives in a separate environment (`about:srcdoc`). This acts as a "firewall" that prevents:
+- **Script Interception:** External scripts (trackers, malicious ads, or browser extensions) cannot access the data inside the iframe, that means that the commerces can't get access to the data inside the iframe
+- **Keyloggers:** It's significantly harder for generic DOM-based keyloggers to capture inputs inside an isolated iframe.
+- ** CSS Integrity:** The host website's CSS (e.g., `input { margin: 50px !important }`) cannot leak into or break the payment form's layout.
+
+### 2. Style Integrity (Zero Conflict CSS)
+The `srcdoc` ensures that the content is loaded in a "clean room" environment.
+- **CSS Encapsulation:** The host website's CSS (e.g., `input { margin: 50px !important }`) cannot leak into or break the payment form's layout.
+- **Deterministic UI:** The form will look exactly the same on any website, whether it's a WordPress site, a React app, or a legacy HTML page.
+
+### 3. High Portability (Single-File SDK)
+Unlike traditional `iframe.src` approaches used by other packages (which require hosting an external HTML file), our `srcdoc` architecture:
+- **No Extra Hosting:** The entire form (HTML + CSS + JS) is bundled into your final `dist/index.js`.
+- **Instant Load:** There is no additional network request to fetch the iframe content; it renders as soon as the JS is executed.
+
+### 4 Data storage
+The data never is stored in the browser (localStorage, sessionStorage, cookies, etc.), all data keep in the memory, that means that for each page reload, the data is lost, and each page reload, is a new instance of the form.
+
+Information commerce, access token, authorize code, etc, keep in the memory.
+
+When an user fields the form, the data is keeping in memory too, and after submit the form, all data is cleaned.