@tonder.io/ionic-lite-sdk 0.0.35-beta.22 → 0.0.35-beta.24

package/.idea/workspace.xml

@@ -6,6 +6,7 @@
   <component name="ChangeListManager">
     <list default="true" id="49ce0c58-6ae2-4b0a-9ac0-48692c69c15e" name="Changes" comment="">
       <change beforePath="$PROJECT_DIR$/.idea/workspace.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/workspace.xml" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/package-lock.json" beforeDir="false" afterPath="$PROJECT_DIR$/package-lock.json" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/package.json" beforeDir="false" afterPath="$PROJECT_DIR$/package.json" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/src/classes/BaseInlineCheckout.ts" beforeDir="false" afterPath="$PROJECT_DIR$/src/classes/BaseInlineCheckout.ts" afterDir="false" />
@@ -23,6 +24,16 @@
       <change beforePath="$PROJECT_DIR$/src/types/checkout.ts" beforeDir="false" afterPath="$PROJECT_DIR$/src/types/checkout.ts" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/src/types/commons.ts" beforeDir="false" afterPath="$PROJECT_DIR$/src/types/commons.ts" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/src/types/index.d.ts" beforeDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/types/liteInlineCheckout.d.ts" beforeDir="false" afterPath="$PROJECT_DIR$/src/types/liteInlineCheckout.ts" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/tests/classes/liteCheckout.test.ts" beforeDir="false" afterPath="$PROJECT_DIR$/tests/classes/liteCheckout.test.ts" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/tests/methods/createOrder.test.ts" beforeDir="false" afterPath="$PROJECT_DIR$/tests/methods/createOrder.test.ts" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/tests/methods/createPayment.test.ts" beforeDir="false" afterPath="$PROJECT_DIR$/tests/methods/createPayment.test.ts" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/tests/methods/customerRegister.test.ts" beforeDir="false" afterPath="$PROJECT_DIR$/tests/methods/customerRegister.test.ts" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/tests/methods/getBusiness.test.ts" beforeDir="false" afterPath="$PROJECT_DIR$/tests/methods/getBusiness.test.ts" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/tests/methods/getCustomerCards.test.ts" beforeDir="false" afterPath="$PROJECT_DIR$/tests/methods/getCustomerCards.test.ts" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/tests/methods/registerCustomerCard.test.ts" beforeDir="false" afterPath="$PROJECT_DIR$/tests/methods/registerCustomerCard.test.ts" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/tests/methods/startCheckoutRouter.test.ts" beforeDir="false" afterPath="$PROJECT_DIR$/tests/methods/startCheckoutRouter.test.ts" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/tests/methods/startCheckoutRouterFull.test.ts" beforeDir="false" afterPath="$PROJECT_DIR$/tests/methods/startCheckoutRouterFull.test.ts" afterDir="false" />
     </list>
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />
@@ -85,7 +96,7 @@
       <workItem from="1725305433705" duration="21026000" />
       <workItem from="1725333899382" duration="2939000" />
       <workItem from="1725337022494" duration="3671000" />
-      <workItem from="1725378545854" duration="14902000" />
+      <workItem from="1725378545854" duration="22151000" />
     </task>
     <servers />
   </component>
@@ -108,7 +119,7 @@
       <breakpoints>
         <line-breakpoint enabled="true" type="javascript">
           <url>file://$PROJECT_DIR$/src/classes/liteCheckout.ts</url>
-          <line>219</line>
+          <line>218</line>
           <option name="timeStamp" value="16" />
         </line-breakpoint>
         <line-breakpoint enabled="true" type="javascript">
@@ -118,9 +129,15 @@
         </line-breakpoint>
         <line-breakpoint enabled="true" type="javascript">
           <url>file://$PROJECT_DIR$/src/classes/liteCheckout.ts</url>
-          <line>223</line>
+          <line>222</line>
           <option name="timeStamp" value="18" />
         </line-breakpoint>
+        <line-breakpoint enabled="true" type="javascript">
+          <url>file://$PROJECT_DIR$/src/classes/liteCheckout.ts</url>
+          <line>304</line>
+          <properties lambdaOrdinal="-1" />
+          <option name="timeStamp" value="21" />
+        </line-breakpoint>
       </breakpoints>
     </breakpoint-manager>
   </component>

package/README.md

@@ -1,6 +1,22 @@
 # Tonder SDK
 
-Tonder SDK Lite to integrate REST service
+Tonder SDK helps to integrate the services Tonder offers in your own mobile app
+
+
+## Table of Contents
+
+1. [Installation](#installation)
+2. [Usage](#usage)
+3. [Configuration Options](#configuration-options)
+4. [Styling InlineCheckout](#styling-inlinecheckout)
+5. [Payment Data Structure](#payment-data-structure)
+6. [Field Validation Functions](#field-validation-functions)
+7. [API Reference](#api-reference)
+8. [Examples](#examples)
+9. [Deprecated Fields](#deprecated-fields)
+10. [Deprecated Functions](#deprecated-functions)
+11. [License](#license)
+
 
 ## Installation
 
@@ -16,6 +32,7 @@ Add dependencies to the root of the app (index.html)
 ```
 
 ## Usage
+LiteCheckout allows you to build a custom checkout interface using Tonder's core functionality
 ## Import LiteCheckout class
 ```javascript
 import { LiteCheckout } from "@tonder.io/ionic-lite-sdk"
@@ -29,172 +46,446 @@ const liteCheckout = new LiteCheckout({
   apiKeyTonder
 })
 
+// The configureCheckout function allows you to set initial information,
+// such as the customer's email, which is used to retrieve a list of saved cards, save new card, etc.
+inlineCheckout.configureCheckout({ customer: { email: "example@email.com" } });
+
+// Initialize the checkout
+await liteCheckout.injectCheckout();
+
 // To verify a 3ds transaction you can use the following method
 // It should be called after the injectCheckout method
 // The response status will be one of the following
 // ['Declined', 'Cancelled', 'Failed', 'Success', 'Pending', 'Authorized']
 
 inlineCheckout.verify3dsTransaction().then(response => {
-  console.log('Verify 3ds response', response)
+    console.log('Verify 3ds response', response)
 })
 ```
 
-| Property        | Type          | Description                                                             |
-|:---------------:|:-------------:|:-----------------------------------------------------------------------:|
-| signal          | AborSignal    | Signal from AbortController instance if it need cancel request          |
-| baseUrlTonder   | string        | Live server: http://stage.tonder.io                                     |
-|                 |               | Mock Server: https://stoplight.io/mocks/tonder/tonder-api-v1-2/3152148  |
-| apiKeyTonder    | string        | You can take this from you Tonder Dashboard                             |
-|                 |               |                                                                         |
+```javascript
+// Retrieve customer's saved cards
+const cards = await liteCheckout.getCustomerCards();
+```
 
-# Class methods
+```javascript
+// Save a new card
+const newCard = await liteCheckout.saveCustomerCard(cardData);
+```
 
-# Checkout router
+```javascript
+// Remove a saved card
+await liteCheckout.removeCustomerCard(cardId);
+```
 
-```typescript
+```javascript
+// Get available payment methods
+const paymentMethods = await liteCheckout.getCustomerPaymentMethods();
+```
+
+```javascript
+// Process a payment
+const paymentResponse = await liteCheckout.payment(paymentData);
+```
+
+## Configuration Options
+
+| Property  |   Type   |                                         Description                                          |
+|:---------:|:--------:|:--------------------------------------------------------------------------------------------:|
+|   mode    |  string  | Environment mode. Options: 'stage', 'production', 'sandbox', 'development'. Default: 'stage' |
+|  apiKey   |  string  |                            Your API key from the Tonder Dashboard                            |
+| returnUrl |  string  |                    URL where the checkout form is mounted (used for 3DS)                     |
+| callBack  | function |         Callback function to be invoked after the payment process ends successfully.         |
+
+## Payment Data Structure
+
+When calling the `payment` method, use the following data structure:
+
+### Field Descriptions
+
+- **customer**: Object containing the customer's personal information to be registered in the transaction.
+
+- **cart**: Object containing the total amount and an array of items to be registered in the Tonder order.
 
-const returnUrl = "http://localhost:8100/payment/success";
+    - **total**: The total amount of the transaction.
+    - **items**: An array of objects, each representing a product or service in the order.
+        - name: name of the product
+        - price_unit: valid float string with the price of the product
+        - quantity: valid integer string with the quantity of this product
 
-let checkoutData = {
+- **currency**: String representing the currency code for the transaction (e.g., "MXN" for Mexican Peso).
+
+- **metadata**: Object for including any additional information about the transaction. This can be used for internal references or tracking.
+
+- **card**: (for LiteCheckout) Object containing card information. This is used differently depending on whether it's a new card or a saved card:
+
+    - For a new card: Include `card_number`, `cvv`, `expiration_month`, `expiration_year`, and `cardholder_name`.
+    - For a saved card: Include only the `skyflow_id` of the saved card.
+    - This is only used when not paying with a payment_method.
+
+- **payment_method**: (for LiteCheckout) String indicating the alternative payment method to be used (e.g., "Spei"). This is only used when not paying with a card.
+
+```javascript
+const paymentData = {
   customer: {
-    name: "Jhon",
-    lastname: "Doe",
-    email: "john.c.calhoun@examplepetstore.com",
-    phone: "+58452258525"
+    firstName: "John",
+    lastName: "Doe",
+    country: "USA",
+    address: "123 Main St",
+    city: "Anytown",
+    state: "CA",
+    postCode: "12345",
+    email: "john.doe@example.com",
+    phone: "1234567890",
   },
-  order: {
+  cart: {
+    total: "100.00",
     items: [
       {
-        description: "Test product description",
+        description: "Product description",
         quantity: 1,
-        price_unit: 25,
-        discount: 1,
-        taxes: 12,
-        product_reference: 89456123,
-        name: "Test product",
-        amount_total: 25
-      }
-    ]
+        price_unit: "100.00",
+        discount: "0.00",
+        taxes: "0.00",
+        product_reference: "PROD123",
+        name: "Product Name",
+        amount_total: "100.00",
+      },
+    ],
   },
-  return_url: returnUrl,
-  total: 25,
-  isSandbox: true,
-  metadata: {},
   currency: "MXN",
-  skyflowTokens: {
-    cardholder_name: "",
-    card_number: "",
-    expiration_year: "",
-    expiration_month: "",
-    cvv: "",
-    skyflow_id: ""
-  }
-}
+  metadata: {
+    order_id: "ORDER123",
+  },
+  // For a new card:
+  card: {
+    card_number: "4111111111111111",
+    cvv: "123",
+    expiration_month: "12",
+    expiration_year: "25",
+    cardholder_name: "John Doe",
+  },
+  // card: "skyflow_id" // for a selected saved card.
+  // payment_method: "Spei", // For the selected payment method.
+};
+```
+
+## Field Validation Functions
+
+For LiteCheckout implementations, the SDK provides validation functions to ensure the integrity of card data before submitting:
 
+- `validateCardNumber(cardNumber)`: Validates the card number using the Luhn algorithm.
+- `validateCardholderName(name)`: Checks if the cardholder name is valid.
+- `validateCVV(cvv)`: Ensures the CVV is in the correct format.
+- `validateExpirationDate(expirationDate)`: Validates the expiration date in MM/YY format.
+- `validateExpirationMonth(month)`: Checks if the expiration month is valid.
+- `validateExpirationYear(year)`: Validates the expiration year.
+
+Example usage:
+
+```javascript
+import {
+  validateCardNumber,
+  validateCardholderName,
+  validateCVV,
+  validateExpirationDate,
+} from "@tonder.io/ionic-lite-sdk";
+
+const cardNumber = "4111111111111111";
+const cardholderName = "John Doe";
+const cvv = "123";
+const expirationDate = "12/25";
+
+if (
+  validateCardNumber(cardNumber) &&
+  validateCardholderName(cardholderName) &&
+  validateCVV(cvv) &&
+  validateExpirationDate(expirationDate)
+) {
+  // Proceed with payment
+} else {
+  // Show error message
+}
 ```
 
-<font size="4">It is required get the skyflow tokens to add it to the checkout router method, the values of the variable skyflowFields come from your html form</font>
+
+## API Reference
+
+### LiteCheckout Methods
+
+- `configureCheckout(data)`: Set initial checkout data
+- `injectCheckout()`: Initialize the checkout
+- `getCustomerCards()`: Retrieve saved cards
+- `saveCustomerCard(cardData)`: Save a new card
+- `removeCustomerCard(cardId)`: Remove a saved card
+- `getCustomerPaymentMethods()`: Get available payment methods
+- `payment(data)`: Process a payment
+- `verify3dsTransaction()`: Verify a 3DS transaction
+
+
+## Examples
+
+Here are examples of how to implement Tonder Lite SDK:
+
+### Angular
+
+For Angular, we recommend using a service to manage the Tonder instance:
 
 ```typescript
+// tonder.service.ts
+import { Injectable } from "@angular/core";
+import { LiteCheckout } from "@tonder.io/ionic-lite-sdk";
 
-const merchantData: any = await liteCheckout.getBusiness();
+@Injectable({
+  providedIn: "root",
+})
+export class TonderService {
+  private liteCheckout!: LiteCheckout;
 
-const { vault_id, vault_url } = merchantData;
+  constructor(@Inject(Object) private sdkParameters: IInlineLiteCheckoutOptions) {
+    this.initializeInlineCheckout();
+  }
+
+  private initializeInlineCheckout(): void {
+    this.liteCheckout = new LiteCheckout({ ...this.sdkParameters });
+  }
+
+  configureCheckout(customerData: IConfigureCheckout): void {
+    this.liteCheckout.configureCheckout({ ...customerData });
+  }
+
+  async injectCheckout(): Promise<void> {
+    await this.liteCheckout.injectCheckout();
+  }
+
+  verify3dsTransaction(): Promise<ITransaction | void> {
+    return this.liteCheckout.verify3dsTransaction();
+  }
 
-const skyflowFields = {
-  card_number: this.paymentForm.value.cardNumber,
-  cvv: this.paymentForm.value.cvv,
-  expiration_month: this.paymentForm.value.month,
-  expiration_year: this.paymentForm.value.expirationYear,
-  cardholder_name: this.paymentForm.value.name
+  payment(
+      checkoutData: IProcessPaymentRequest,
+  ): Promise<IStartCheckoutResponse> {
+      return this.inlineCheckout.payment(checkoutData);
+  }
+
+  // Add more functions, for example for lite sdk: get payment methods
+
+  // getCustomerPaymentMethods(): Promise<IPaymentMethod[]> {
+  //     return this.liteCheckout.getCustomerPaymentMethods();
+  // }
 }
 
-const skyflowTokens = await liteCheckout.getSkyflowTokens({
-  vault_id: vault_id,
-  vault_url: vault_url,
-  data: skyflowFields
+// checkout.component.ts
+import { Component, OnInit, OnDestroy } from "@angular/core";
+import { TonderService } from "./tonder.service";
+
+@Component({
+  selector: "app-tonder-checkout",
+  template: `
+    <div id="container">
+      <form [formGroup]="paymentForm">
+        <div class="lite-container-tonder">
+            <div id="id-name" class="empty-div">
+              <label for="name">Namess: </label>
+              <input id="name" type="text" formControlName="name">
+            </div>
+            <div id="id-cardNumber" class="empty-div">
+              <label for="cardNumber">Card number: </label>
+              <input id="cardNumber" type="text" formControlName="cardNumber">
+            </div>
+            <div class="collect-row">
+              <div class="empty-div">
+                <label for="month">Month: </label>
+                <input id="month" type="text" formControlName="month">
+              </div>
+              <div class="expiration-year">
+                <label for="expirationYear">Year: </label>
+                <input id="expirationYear" type="text" formControlName="expirationYear">
+              </div>
+              <div class="empty-div">
+                <label for="cvv">CVV: </label>
+                <input id="cvv" type="text" formControlName="cvv">
+              </div>
+            </div>
+          <div id="msgError">{{ errorMessage }}</div>
+          <div id="msgNotification"></div>
+          <div class="container-pay-button">
+            <button class="lite-pay-button" (click)="onPayment($event)">Pay</button>
+          </div>
+        </div>
+    
+      </form>
+    </div>
+  `,
+  providers: [
+    {
+      provide: TonderInlineService,
+      // Initialization of the Tonder Lite SDK.
+      // Note: Replace these credentials with your own in development/production.
+      useFactory: () =>
+        new TonderInlineService({
+          apiKey: "11e3d3c3e95e0eaabbcae61ebad34ee5f93c3d27",
+          returnUrl: "http://localhost:8100/tabs/tab5",
+          mode: "stage",
+        }),
+    },
+  ],
 })
+export class TonderCheckoutComponent implements OnInit, OnDestroy {
+  loading = false;
+  checkoutData: IProcessPaymentRequest;
+    paymentForm = new FormGroup({
+        name: new FormControl('Pedro Paramo'),
+        cardNumber: new FormControl('4242424242424242'),
+        month: new FormControl('12'),
+        expirationYear: new FormControl('28'),
+        cvv: new FormControl('123')
+    });
+  constructor(private tonderService: TonderService) {
+      this.checkoutData = {
+          customer: {
+              firstName: "Jhon",
+              lastName: "Doe",
+              email: "john.c.calhoun@examplepetstore.com",
+              phone: "+58452258525"
+          },
+          cart: {
+              total: 25,
+              items: [
+                  {
+                      description: "Test product description",
+                      quantity: 1,
+                      price_unit: 25,
+                      discount: 1,
+                      taxes: 12,
+                      product_reference: 89456123,
+                      name: "Test product",
+                      amount_total: 25
+                  }
+              ]
+          },
+          metadata: {},
+          currency: "MXN"
+      }
+  }
 
-checkoutData.skyflowTokens = skyflowTokens;
+  ngOnInit() {
+    this.initCheckout();
+  }
 
-const jsonResponseRouter: any = await liteCheckout.startCheckoutRouterFull(
-  checkoutData
-);
+  async initCheckout() {
+    this.tonderService.configureCheckout({
+      customer: { email: "example@email.com" },
+    });
+    await this.tonderService.injectCheckout();
+    this.tonderService.verify3dsTransaction().then((response) => {
+      console.log("Verify 3ds response", response);
+    });
+    
+    // Calls more functions to get payment methods, saved cards, etc.
+  }
 
+  async pay() {
+    this.loading = true;
+    try {
+      const response = await this.tonderService.payment({
+          ...this.checkoutData,
+          card: { // Card details, if not using a payment method.
+              card_number: this.paymentForm.value.cardNumber || "",
+              cvv: this.paymentForm.value.cvv || "",
+              expiration_month: this.paymentForm.value.month || "",
+              expiration_year: this.paymentForm.value.expirationYear || "",
+              cardholder_name: this.paymentForm.value.name || ""
+          },
+          // card: "skyflow_id" // In case a saved card is selected.
+          // payment_method: "" // Payment method if not using the card form
+      });
+      console.log("Payment successful:", response);
+      alert("Payment successful");
+    } catch (error) {
+      console.error("Payment failed:", error);
+      alert("Payment failed");
+    } finally {
+      this.loading = false;
+    }
+  }
+}
 ```
 
-<font size="4">Take actions on base to the checkout router response</font>
+## Deprecated Fields
 
-# Customer Cards(Register)
+The following functions and fields have been deprecated and should no longer be used. Consider using the recommended alternatives:
 
-## Register customer card
+### `apiKeyTonder` Property
 
-```typescript
+- **Deprecated Reason:** The `apiKeyTonder` property in the constructor and `IInlineLiteCheckoutOptions` interface is no longer required.
+- **Alternative:** Use the `apiKey` field.
 
-customer_auth_token: string;
+### `baseUrlTonder` Property
 
-data: {
-    skyflow_id: string;
-};
+- **Deprecated Reason:** The `baseUrlTonder` property in the constructor and `IInlineLiteCheckoutOptions` interface is no longer required.
+- **Alternative:** Use the `mode` field with `stage` | `development` | `sandbox` | `production` options.
 
-const jsonResponseOrder = await liteCheckout.registerCustomerCard(
-  customer_auth_token,
-  data
-);
-```
+### `signal` Property
 
-## Return register customer card
-```typescript
-{
-    skyflow_id: string;
-    user_id: number;
-}
-```
+- **Deprecated Reason:** The `signal` property in the constructor and `IInlineLiteCheckoutOptions` interface is no longer required.
 
-# Customer Cards(Get)
 
-## Get customer cards
+## Deprecated Functions
 
-```typescript
+### `customerRegister`
 
-customer_auth_token: string;
+- **Deprecated Reason:** This function is no longer necessary as registration is now automatically handled during payment processing or when using card management methods.
 
-query: string = "?ordering=<string>&search=<string>";
+### `createOrder` and `createPayment`
 
-const jsonResponseOrder = await liteCheckout.getCustomerCards(
-  customer_auth_token,
-  query
-);
-```
+- **Deprecated Reason:** These functions have been replaced by the `payment` function, which now automatically handles order creation and payment processing.
+- **Alternative:** Use the `payment` function.
 
-## Return get customer cards
-```typescript
-{
-    user_id: number,
-    cards: [
-        {
-            fields: {
-                card_number: string,
-                cardholder_name: string,
-                cvv: string,
-                expiration_month: string,
-                expiration_year: string,
-                skyflow_id: string
-            }
-        }
-    ]
-}
-```
+### `startCheckoutRouter` and `startCheckoutRouterFull`
 
-## Delete customer card
+- **Deprecated Reason:** These functions have been replaced by the `payment` function.
+- **Alternative:** Use the `payment` function.
 
-```typescript
+### `registerCustomerCard`
+
+- **Deprecated Reason:** This function has been renamed to `saveCustomerCard` to better align with its purpose. The method's usage has also been updated.
+- **Alternative:** Use the `saveCustomerCard` method and update your implementation to reflect the changes.
+
+### `deleteCustomerCard`
+
+- **Deprecated Reason:** This function has been renamed to `removeCustomerCard` to better align with its purpose. The method's usage has also been updated.
+- **Alternative:** Use the `removeCustomerCard` method and update your implementation to reflect the changes.
 
-const deleted: boolean = await liteCheckout.deleteCustomerCard(
-  customer_auth_token,
-  skyflow_id
-);
+### `getActiveAPMs`
 
+- **Deprecated Reason:** This function has been renamed to `getCustomerPaymentMethods` to better align with its purpose. The method's usage has also been updated.
+- **Alternative:** Use the `getCustomerPaymentMethods` method and update your implementation to reflect the changes.
+
+### `getSkyflowTokens`
+
+- **Deprecated Reason:** Card registration and checkout are now automatically handled during the payment process or through card management methods, making this method unnecessary.
+
+### `getOpenpayDeviceSessionID`
+
+- **Deprecated Reason:** It is no longer necessary to use this method is now automatically handled during the payment process.
+
+
+## Notes
+
+### General
+
+- Replace `'your-api-key'`, `'http://your-website.com/checkout'`, `returnUrl`, and `paymentData` with your actual values.
+- The `paymentData` should be defined according to your specific requirements.
+- Remember to use the `configureCheckout` function after creating an instance of `LiteCheckout`. This ensures that functions such as payment processing, saving cards, deleting cards, and others work correctly.
+
+### Script Dependencies
+
+For all implementations, ensure you include the necessary scripts:
+
+```html
+<script src="https://openpay.s3.amazonaws.com/openpay.v1.min.js"></script>
+<script src="https://openpay.s3.amazonaws.com/openpay-data.v1.min.js"></script>
 ```
 
 ## License