Merge branch 'main' into support-308-redirect

Author: gcatanese

README.md

@@ -89,10 +89,10 @@ Check for breaking changes on the [releases page](https://github.com/Adyen/adyen
 
 ``` javascript
 // Step 1: Require the parts of the module you want to use
-const { Client, CheckoutAPI} = require('@adyen/api-library');
+const { Client, CheckoutAPI, EnvironmentEnum} = require('@adyen/api-library');
 
 // Step 2: Initialize the client object
-const client = new Client({apiKey: "YOUR_API_KEY", environment: "TEST"}); 
+const client = new Client({apiKey: "YOUR_API_KEY", environment: EnvironmentEnum.TEST}); 
 
 // Step 3: Initialize the API object
 const checkoutApi = new CheckoutAPI(client);
@@ -143,7 +143,7 @@ Use the Node.js `require` function to load the `Client` and API objects from the
 For example, to use the [Checkout API](https://docs.adyen.com/api-explorer/Checkout/70/overview):
 
 ``` javascript
-const { Client, CheckoutAPI} = require('@adyen/api-library');
+const { Client, CheckoutAPI, EnvironmentEnum} = require('@adyen/api-library');
 ```
 
 ### Step 2: Initialize the client object
@@ -155,7 +155,7 @@ Initialize the client object, passing the following:
 For example:
 
 ``` javascript
-const client = new Client({apiKey: "YOUR_API_KEY", environment: "TEST"}); 
+const client = new Client({apiKey: "YOUR_API_KEY", environment: EnvironmentEnum.TEST}); 
 ```
 
 ### Step 3: Initialize the API object
@@ -208,18 +208,18 @@ checkoutApi.PaymentsApi.payments(paymentRequest)
 
 For APIS that require your [Live URL Prefix](https://docs.adyen.com/development-resources/live-endpoints#live-url-prefix) (Binlookup, BalanceControl, Checkout, Payout and Recurring) the client is set up as follows in order to start processing live payments:
 ``` typescript
-const { Client } = require('@adyen/api-library');
+const { Client, EnvironmentEnum } = require('@adyen/api-library');
 
-const client = new Client({apiKey: "YOUR_API_KEY", environment: "TEST", liveEndpointUrlPrefix: "YOUR_LIVE_URL_PREFIX"}); 
+const client = new Client({apiKey: "YOUR_API_KEY", environment: EnvironmentEnum.LIVE, liveEndpointUrlPrefix: "YOUR_LIVE_URL_PREFIX"}); 
 ```
 
 ### Usage in TypeScript
 
 Alternatively, you can use the `Types` included in this module for Typescript and `async` syntax.
 
 ``` typescript
-  const { Client, CheckoutAPI, Types } = require('@adyen/api-library');
-  const client = new Client({apiKey: "YOUR_API_KEY", environment: "TEST"});
+  const { Client, EnvironmentEnum, CheckoutAPI, Types } = require('@adyen/api-library');
+  const client = new Client({apiKey: "YOUR_API_KEY", environment: EnvironmentEnum.LIVE, liveEndpointUrlPrefix: "YOUR_LIVE_URL_PREFIX"});
 
   const makePaymentsRequest = async () => {
     const paymentsRequest : Types.checkout.PaymentRequest = {
@@ -265,6 +265,8 @@ const paymentRequest: checkout.PaymentRequest = await checkout.ObjectSerializer.
 
 By default, [Node.js https](https://nodejs.org/api/https.html) is used to make API requests. Alternatively, you can set a custom `HttpClient` for your `Client` object.
 
+**Note**: when using your custom `HttpClient`, you must define all required properties (API key, content-type, timeouts, etc..) 
+
 For example, to set `axios` as your HTTP client:
 
 ``` javascript
@@ -330,20 +332,26 @@ const client = new Client({ config });
 const httpClient = new HttpURLConnectionClient();
 httpClient.proxy = { host: "http://google.com", port: 8888,  };
 
-client.setEnvironment('TEST');
+client.setEnvironment(EnvironmentEnum.TEST);
 client.httpClient = httpClient;
 
 // ... more code
 ```
 
-### Using the Cloud Terminal API Integration
-In order to submit In-Person requests with [Terminal API over Cloud](https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/cloud/) you need to initialize the client in a similar way as the steps listed above for Ecommerce transactions, but make sure to include `TerminalCloudAPI`:
+### Using the Cloud Terminal API 
+For In-Person Payments integrations with the [Cloud Terminal API](https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/cloud/), you must initialise the Client **setting the closest** [Region](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/#cloud):
 ``` javascript
 // Step 1: Require the parts of the module you want to use
 const {Client, TerminalCloudAPI} from "@adyen/api-library";
+const { Config, EnvironmentEnum, RegionEnum } = require("@adyen/api-library");
 
 // Step 2: Initialize the client object
-const client = new Client({apiKey: "YOUR_API_KEY", environment: "TEST"});
+const config = new Config({
+    apiKey: "YOUR_API_KEY",
+    environment: EnvironmentEnum.LIVE,
+    region: RegionEnum.US
+});
+const client = new Client(config);
 
 // Step 3: Initialize the API object
 const terminalCloudAPI = new TerminalCloudAPI(client);
@@ -507,6 +515,75 @@ const paymentRequest: SaleToPOIRequest = {
 // Step 5: Make the request
 const terminalApiResponse: terminal.TerminalApiResponse = await terminalLocalAPI.request(paymentRequest);
 ```
+### Using the Cloud Terminal API Integration (async)
+If you choose to integrate [Terminal API over Cloud](https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/cloud/) **asynchronously**, you need to follow similar steps to initialize the client and prepare the request object. However the response will be asynchronous:
+* a successful request will return `200` status code and `ok` as response body. Make sure to setup the [event notifications](https://docs.adyen.com/point-of-sale/design-your-integration/notifications/event-notifications/)
+* a request that fails will return `200` status code and the `TerminalApiResponse` as response body
+``` typescript
+// Step 1: Require the parts of the module you want to use
+const {Client, TerminalCloudAPI} from "@adyen/api-library";
+
+// Step 2: Initialize the client object
+const client = new Client({apiKey: "YOUR_API_KEY", environment: "TEST"});
+
+// Step 3: Initialize the API object
+const terminalCloudAPI = new TerminalCloudAPI(client);
+
+// Step 4: Create the request object
+const serviceID = "123456789";
+const saleID = "POS-SystemID12345";
+const POIID = "Your Device Name(eg V400m-123456789)";
+
+// Use a unique transaction for every transaction you perform
+const transactionID = "TransactionID";
+const paymentRequest: SaleToPOIRequest = {
+    MessageHeader: {
+        MessageClass: MessageClassType.Service,
+        MessageCategory: MessageCategoryType.Payment,
+        MessageType: MessageType.Request,
+        ProtocolVersion: "3.0",
+        ServiceID: serviceID,
+        SaleID: saleID,
+        POIID: POIID
+    },
+    PaymentRequest: {
+        SaleData: {
+            SaleTransactionID: {
+                TransactionID: transactionID,
+                TimeStamp: new Date().toISOString()
+            },
+
+            SaleToAcquirerData: {
+                applicationInfo: {
+                    merchantApplication: {
+                        version: "1",
+                        name: "test",
+                    }
+                }
+            }
+        },
+        PaymentTransaction: {
+            AmountsReq: {
+                Currency: "EUR",
+                RequestedAmount: 1000
+            }
+        }
+    }
+};
+
+// Step 5: Make the request
+const response = await terminalCloudAPI.async(paymentRequest);
+// handle both `string` and `TerminalApiResponse`
+if (typeof response === "string") {
+  // request was successful
+  console.log("response:", response); // should be 'ok'
+} else {
+  // request failed: see details in the EventNotification object
+  console.log("EventToNotify:", response.SaleToPOIRequest?.EventNotification?.EventToNotify);
+  console.log("EventDetails:", response.SaleToPOIRequest?.EventNotification?.EventDetails);
+}
+```
+
 ## Feedback
 We value your input! Help us enhance our API Libraries and improve the integration experience by providing your feedback. Please take a moment to fill out [our feedback form](https://forms.gle/A4EERrR6CWgKWe5r9) to share your thoughts, suggestions or ideas. 
 

src/__mocks__/base.ts

@@ -18,7 +18,7 @@
  */
 
 import Client from "../client";
-import Config from "../config";
+import Config, { EnvironmentEnum } from "../config";
 import {
     AmountsReq,
     MessageCategoryType,
@@ -37,18 +37,19 @@ import {
 
 export const createClient = (apiKey = process.env.ADYEN_API_KEY): Client => {
     const config: Config = new Config();
+    config.environment = EnvironmentEnum.TEST;
     config.terminalApiCloudEndpoint = Client.TERMINAL_API_ENDPOINT_TEST;
     config.terminalApiLocalEndpoint = "https://mocked_local_endpoint.com";
     config.marketPayEndpoint = Client.MARKETPAY_ENDPOINT_TEST;
     config.apiKey = apiKey == null ? "apiKey" : apiKey;
-    return new Client({ config });
+    return new Client(config);
 };
 
 export const createBasicAuthClient = (): Client => {
     return new Client({
         username: process.env.ADYEN_USER!,
         password: process.env.ADYEN_PASSWORD!,
-        environment: "TEST",
+        environment: EnvironmentEnum.TEST,
         applicationName: "adyen-node-api-library"
     });
 };

src/__mocks__/terminalApi/async.ts

@@ -18,3 +18,25 @@
  */
 
 export const asyncRes = "ok";
+
+export const asyncErrorRes = {
+    SaleToPOIRequest: {
+        EventNotification: {
+            EventToNotify: "Reject",
+            EventDetails: "message=Did+not+receive+a+response+from+the+POI.",
+            RejectedMessage: "ewoi...0KfQo=",
+            TimeStamp: "2020-03-31T10:28:39.515Z"
+        },
+        MessageHeader: {
+            DeviceID: "666568147",
+            MessageCategory: "Event",
+            MessageClass: "Event",
+            MessageType: "Notification",
+            POIID: "P400Plus-123456789",
+            ProtocolVersion: "3.0",
+            SaleID: "saleid-4c32759faaa7",
+            ServiceID: "31122609"
+        }
+    }
+};
+

src/__tests__/checkout.spec.ts

@@ -16,6 +16,7 @@ import { checkout } from "../typings";
 import { IRequest } from "../typings/requestOptions";
 import { SessionResultResponse } from "../typings/checkout/sessionResultResponse";
 import { payments3DS2NativeAction } from "../__mocks__/checkout/payments3DS2NativeAction";
+import { EnvironmentEnum } from "../config";
 
 const merchantAccount = process.env.ADYEN_MERCHANT!;
 const reference = "Your order number";
@@ -384,14 +385,14 @@ describe("Checkout", (): void => {
     // });
 
     test("should have missing identifier on live", async (): Promise<void> => {
-        client.setEnvironment("LIVE");
+        client.config.environment = EnvironmentEnum.LIVE;
         try {
             const liveCheckout = new CheckoutAPI(client);
             await liveCheckout.PaymentsApi.payments(createPaymentsCheckoutRequest());
             fail();
         } catch (e) {
             if(e instanceof Error) {
-                expect(e.message).toEqual("Please provide your unique live url prefix on the setEnvironment() call on the Client.");
+                expect(e.message).toEqual("Live endpoint URL prefix must be provided for LIVE environment.");
 
             } else {
                 fail();