@paydock/client-sdk 1.120.1 → 1.121.0

package/slate.md

@@ -99,6 +99,7 @@ through named imports or namespaced imports.
 
 
 ## Widget
+
 You can find description of all methods and parameters [here](https://www.npmjs.com/package/@paydock/client-sdk#widget-simple-example)
 
 A payment form where it is possible to enter card data/bank accounts and then receive a one-time
@@ -115,8 +116,8 @@ It is possible in real-time to monitor the actions of user with widget and get i
 
 You must create a container for the widget. Inside this tag, the widget will be initialized
 
-
 ### Initialization
+
 ```javascript
 var widget = new paydock.HtmlWidget('#widget', 'publicKey');
 widget.load();
@@ -133,7 +134,6 @@ widget.load();
 
 Then write only need 2 lines of code in js to initialize widget
 
-
 ### Full example
 
 ```html
@@ -159,19 +159,18 @@ Then write only need 2 lines of code in js to initialize widget
 </html>
 ```
 
-
 ## Widget advanced example
 
 ### Customization
 
 ```javascript
 widget.setStyles({
-		background_color: 'rgb(0, 0, 0)',
-		border_color: 'yellow',
-		text_color: '#FFFFAA',
-		button_color: 'rgba(255, 255, 255, 0.9)',
-		font_size: '20px'
-	});
+  background_color: 'rgb(0, 0, 0)',
+  border_color: 'yellow',
+  text_color: '#FFFFAA',
+  button_color: 'rgba(255, 255, 255, 0.9)',
+  font_size: '20px'
+ });
 ```
 
 This example shows how you can customize to your needs and design
@@ -180,9 +179,9 @@ This example shows how you can customize to your needs and design
 
 ```html
 <div id="widget"
-	 widget-style="text-color: #FFFFAA; border-color: #yellow"
-	 title="Payment form"
-	 finish-text="Payment resource was successfully accepted"></div>
+  widget-style="text-color: #FFFFAA; border-color: #yellow"
+  title="Payment form"
+  finish-text="Payment resource was successfully accepted"></div>
 ```
 
 This example shows how you can set style and texts from html
@@ -199,19 +198,112 @@ widget.setSupportedCardIcons(['mastercard', 'visa']); // add icons of supported
 
 This example shows how you can use a lot of other methods to settings your form
 
-
 ### Error handling
 
+## Overview
+
+Error events are emitted when an error occurs during widget operations. These events provide detailed information about the error, including its category, cause, and contextual details.
+
+## Error Event Structure
+
+### Base Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `event` | `string` | Always set to `"error"` |
+| `purpose` | `string` | Indicates the purpose of the action that triggered the error event (e.g., `"payment_source"`) |
+| `message_source` | `string` | Source of the message (e.g., `"widget.paydock"`) |
+| `ref_id` | `string` | Reference ID for the operation |
+| `widget_id` | `string` | Unique identifier of the widget instance |
+| `error` | `object` | Error object containing error information |
+
+### Error Object Properties
+
+The `error` object contains detailed information about the error:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `category` | `string` | High-level error classification |
+| `cause` | `string` | Specific error cause |
+| `retryable` | `boolean` | Indicates if the operation can be retried |
+| `details` | `object` | Additional error context |
+
+## Error Categories
+
+| Category | Description |
+|----------|-------------|
+| `configuration` | Configuration-related errors |
+| `identity_access_management` | Authentication and authorization errors |
+| `internal` | Internal system errors |
+| `process` | Process and operation errors |
+| `resource` | Resource-related errors |
+| `validation` | Input validation errors |
+
+## Error Causes
+
+| Cause | Category | Description |
+|-------|----------|-------------|
+| `aborted` | `process` | Operation was aborted |
+| `access_forbidden` | `identity` | Access to resource is forbidden |
+| `already_exists` | `validation` | Resource already exists |
+| `canceled` | `process` | Operation was canceled |
+| `invalid_configuration` | `configuration` | Invalid widget configuration |
+| `invalid_input` | `validation` | Invalid input provided |
+| `not_found` | `resource` | Requested resource not found |
+| `not_implemented` | `process` | Requested feature not implemented |
+| `rate_limited` | `process` | Too many requests |
+| `server_busy` | `process` | Server is too busy to handle request |
+| `service_unreachable` | `process` | Unable to reach required service |
+| `unauthorized` | `identity` | Authentication required |
+| `unknown_error` | `internal` | Unexpected error occurred |
+| `unprocessable_entity` | `validation` | Valid input but cannot be processed |
+
+## Error Details Object
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `cause` | `string` | Matches the top-level error cause |
+| `contextId` | `string` | Context identifier (usually matches widget_id) |
+| `message` | `string` | Human-readable error message |
+| `timestamp` | `string` | ISO 8601 timestamp of when the error occurred |
+
+## Example
+
 ```javascript
+widget.hideUiErrors(); // hide default UI errors and handle errors by listening to error events with widget.on('error')
+
 widget.on('error', (error) => {
-    const errorDiv = document.getElementById('error');
-    const errorMessage = document.getElementById('error-message');
-    
-    errorMessage.textContent = error.data.message;
-    errorDiv.style.display = 'block';
+    console.log(error);
+    // {
+    //     "event": "error",
+    //     "purpose": "payment_source",
+    //     "message_source": "widget.paydock",
+    //     "ref_id": "",
+    //     "widget_id": "d4744f30-dcf5-168e-7f78-c8273a3401d4",
+    //     "error": {
+    //         "category": "process",
+    //         "cause": "service_unreachable",
+    //         "details": {
+    //             "cause": "service_unreachable",
+    //             "contextId": "d4744f30-dcf5-168e-7f78-c8273a3401d4",
+    //             "message": "The service is not availabe",
+    //             "timestamp": "2025-02-13T09:30:21.157Z"
+    //         },
+    //         "retryable": false
+    //     }
+    // }
 });
 ```
 
+## Handling Errors (Tips)
+
+When handling errors, consider:
+
+1. Check the `retryable` flag to determine if the operation can be retried
+2. Use the `category` for high-level error handling logic
+3. Use the `cause` for specific error handling cases
+4. The `contextId` can be used for error tracking and debugging
+5. The `timestamp` helps with error logging and debugging
 
 ### Full example
 
@@ -219,9 +311,9 @@ widget.on('error', (error) => {
 <!DOCTYPE html>
 <html lang="en">
 <head>
-	<meta charset="UTF-8">
-	<title>Title</title>
-	<style>iframe {border: 0;width: 100%;height: 400px;}</style>
+ <meta charset="UTF-8">
+ <title>Title</title>
+ <style>iframe {border: 0;width: 100%;height: 400px;}</style>
 </head>
 <body>
 <form id="paymentForm">
@@ -260,18 +352,18 @@ widget.on('error', (error) => {
 
 <script src="https://widget.paydock.com/sdk/latest/widget.umd.js" ></script>
 <script>
-	var widget = new paydock.HtmlWidget('#widget', 'publicKey', 'gatewayId');
+ var widget = new paydock.HtmlWidget('#widget', 'publicKey', 'gatewayId');
 
-	widget.setSupportedCardIcons(['mastercard', 'visa']);
-	widget.setFormFields(['phone', 'email']);
-	widget.setRefId('custom-ref-id');
+ widget.setSupportedCardIcons(['mastercard', 'visa']);
+ widget.setFormFields(['phone', 'email']);
+ widget.setRefId('custom-ref-id');
     widget.onFinishInsert('input[name="payment_source_token"]', 'payment_source');
 
-    widget.on('error', (error) => {
-        document.getElementById('error-message').textContent = error.data.message;
+    widget.on('error', ({ error }) => {
+        document.getElementById('error-message').textContent = error.details.message;
         document.getElementById('error').style.display = 'block';
     });
-	widget.load();
+ widget.load();
 </script>
 
 </body>
@@ -1335,7 +1427,7 @@ button.onUpdate((data) => {
 After the payment is completed, the onPaymentSuccessful(data) will be called if the payment was successful. If the payment was not successful, the function onPaymentError(data) will be called. If fraud check is active for the gateway, a fraud body was sent in the wallet charge initialize call and the fraud service left the charge in review, then the onPaymentInReview(data) will be called.
 All three callbacks return relevant data according to each one of the scenarios.
 
-Note that these callbacks will not trigger for Afterpay wallet since the payment completion for it is done via Redirect method, and therefore this SDK won't be loaded once the payment is completed at checkout.
+>*Note that these callbacks will not be triggered for the Afterpay wallet when Redirect mode is used, that is when the charge is initialized with the success_url and error_url parameters, since the payment completion is done through the Redirect method, and therefore this SDK will not be loaded once the payment is completed at checkout.*
 
 ```javascript
 button.onPaymentSuccessful((data) => console.log("The payment was successful"));
@@ -1537,7 +1629,7 @@ _(Required `meta` fields: - . Optional `meta` fields: -)_
 
 This example shows how to use these functions for **ApplePay via MPGS** and **GooglePay via MPGS**:
 
-_(Required `meta` fields: `amount_label`, `country`. Optional `meta` fields: `raw_data_initialization`, `request_shipping`, `style.button_type`)_
+_(Required `meta` fields: `amount_label`, `country`. Optional `meta` fields: `raw_data_initialization`, `request_shipping`, `style.button_type`, `style.button_style`)_
 ### ApplePay and GooglePay via MPGS Full example
 
 ```html
@@ -1569,6 +1661,7 @@ _(Required `meta` fields: `amount_label`, `country`. Optional `meta` fields: `ra
                 },
                 apple: {
                     button_type: 'buy',
+                    button_style: 'black',
                 },
             },
             shipping_options: [
@@ -1685,6 +1778,7 @@ Similarly, for **GooglePay via MPGS** you can initialize the `PaymentMethodSpeci
                 },
                 apple: {
                     button_type: 'buy',
+                    button_style: 'black',
                 },
             },
             shipping_options: [

package/bundles/types/helper/custom-error.d.ts

@@ -1,8 +0,0 @@
-export declare class CustomError extends Error {
-    status?: number | undefined;
-    data: {
-        _message: string;
-    } & Record<string, any>;
-    constructor(message: string, status?: number, data?: any);
-}
-//# sourceMappingURL=custom-error.d.ts.map

package/bundles/types/helper/custom-error.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"custom-error.d.ts","sourceRoot":"","sources":["../../src/helper/custom-error.ts"],"names":[],"mappings":"AAAA,qBAAa,WAAY,SAAQ,KAAK;IAC7B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;gBAE7C,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG;CAMzD"}

package/bundles/types/wallet-buttons/helpers/apple-pay.helper.d.ts

@@ -1,3 +0,0 @@
-import type { ApplePayStyles } from "../../components/param";
-export declare const APPLE_PAY_BUTTON_TYPES_ARIA_LABEL_MAPPING: Record<ApplePayStyles['button_type'], string>;
-//# sourceMappingURL=apple-pay.helper.d.ts.map

package/bundles/types/wallet-buttons/helpers/apple-pay.helper.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"apple-pay.helper.d.ts","sourceRoot":"","sources":["../../../src/wallet-buttons/helpers/apple-pay.helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,eAAO,MAAM,yCAAyC,EAAE,MAAM,CAC5D,cAAc,CAAC,aAAa,CAAC,EAC7B,MAAM,CAmBP,CAAC"}