🤖 Merge PR #49967 feature: Add TapPay payment typing. by @Yu-Jack

* feature: Add TapPay payment typing.

* fix: remove rules from tslint.json

* fix: fix code style

* feature: fix typo and add more detail for merchant_reference_info field

* fix: change project url to official documentation

* feature: remove README and change major version in the header of index.d.ts

types/tpdirect/common.d.ts

@@ -0,0 +1,105 @@
+type AllowedNetworks = "AMEX" | "JCB" | "MASTERCARD" | "VISA";
+
+interface BaseResult {
+    /**
+     * 0 is successful.
+     */
+    status: number;
+    msg: string;
+    prime: string;
+    client_ip: string;
+}
+
+interface MerchantReferenceInfo {
+    /**
+     * ```markdown
+     * If the merchant uses the co-branded card management in the TapPay portal,
+     * and the transaction card number meets the setting.
+     * ```
+     */
+    merchant_reference_info: {
+        /**
+         * Affiliated codes set by the merchant in the Co-brand card management
+         * area of the TapPay portal.
+         */
+        affiliate_codes: string[];
+    };
+}
+
+interface BaseCardInfo {
+    issuer: string;
+    issuer_zh_tw: string;
+    bank_id: string;
+    /**
+     * ```markdown
+     * -1 = Unkonwn
+     * 0 = Credit Card
+     * 1 = Debit Card
+     * 2 = Prepaid Card
+     * ```
+     */
+    funding: -1 | 0 | 1 | 2;
+    /**
+     * ```markdown
+     * -1 = Unkown
+     * 1 = VISA
+     * 2 = MasterCard
+     * 3 = JCB
+     * 4 = Union Pay
+     * 5 = AMEX
+     * ```
+     */
+    type: 1 | 2 | 3 | 4 | 5;
+    level: string;
+    country: string;
+}
+
+interface Card extends Pick<BaseCardInfo, "funding" | "type"> {
+    /**
+     * Real Card
+     */
+    lastfour: string;
+}
+
+interface CardInfoV1 extends BaseCardInfo {
+    bincode: string;
+    /**
+     * Real Card for Direct Pay
+     */
+    lastfour: string;
+    countrycode: string;
+}
+
+interface CardInfoV2 extends BaseCardInfo {
+    bin_code: string;
+    /**
+     * ```markdown
+     * Real Card for Google Pay (card isn't installed in phohe)
+     * Token Card for Google Pay, Apple Pay, Samsung Pay
+     * ```
+     */
+    last_four: string;
+    country_code: string;
+}
+
+interface Address {
+    country: string;
+    addressLine: string[];
+    region: string;
+    city: string;
+    dependentLocality: string;
+    postalCode: string;
+    sortingCode: string;
+    languageCode: string;
+    organization: string;
+    recipient: string;
+    phone: string;
+}
+
+interface PaymentRequestAmount {
+    label: string;
+    amount: {
+        currency: string;
+        value: string;
+    };
+}

types/tpdirect/direct-pay.d.ts

@@ -0,0 +1,77 @@
+/// <reference path="common.d.ts" />
+
+interface UpdateResult {
+    /**
+     * ```markdown
+     * `true` means all fields are correct.
+     * You may now call getPrime.
+     * ```
+     */
+    canGetPrime: boolean;
+    cardType: "mastercard" | "visa" | "jcb" | "amex" | "unionpay" | "unknown";
+    status: {
+        /**
+         * ```markdown
+         * 0 is successful
+         * 1 is typing
+         * 2 is error
+         * ```
+         */
+        number: 0 | 1 | 2;
+        /**
+         * ```markdown
+         * 0 is successful
+         * 1 is typing
+         * 2 is error
+         * ```
+         */
+        expiry: 0 | 1 | 2;
+        /**
+         * ```markdown
+         * 0 is successful
+         * 1 is typing
+         * 2 is error
+         * ```
+         */
+        ccv: 0 | 1 | 2;
+    };
+}
+
+interface elementObject {
+    element: string;
+    placeholder: string;
+}
+
+type cssKeyName =  "color" | "font" | "font-family" | "font-size" | "font-size-adjust" | "font-stretch" | "font-style"
+| "font-variant" | "font-variant-alternates" | "font-variant-caps" | "font-variant-east-asian" | "font-variant-ligatures" | "font-variant-numeric"
+| "font-weight" | "line-height" | "outline" | "opacity" | "text-shadow" | "transition" | "-moz-osx-font-smoothing" | "-moz-transition" | "-webkit-font-smoothing" | "-webkit-transitio";
+
+interface DirectPay {
+    setup(fields: {
+        number: elementObject;
+        expirationDate: elementObject;
+        ccv: elementObject;
+    }, styles?: {
+        [key: string]: {
+            [key in cssKeyName]?: string;
+        };
+    }): void;
+
+    onUpdate(callback: (
+        update: UpdateResult
+    ) => void): void;
+
+    getTappayFieldsStatus(): UpdateResult;
+
+    getPrime(callback: (
+        result: {
+            /**
+             * 0 is successful.
+             */
+            status: Pick<BaseResult, "status">;
+            clientip: Pick<BaseResult, "client_ip">;
+            card_identifier: string;
+            card: CardInfoV1 & Pick<BaseResult, "prime">;
+        } & MerchantReferenceInfo
+    ) => void): void;
+}

types/tpdirect/easy-wallet.d.ts

@@ -0,0 +1,7 @@
+/// <reference path="common.d.ts" />
+
+interface EasyWallet {
+    getPrime(callback: (
+        result: BaseResult
+    ) => void): void;
+}

types/tpdirect/google-pay.d.ts

@@ -0,0 +1,61 @@
+/// <reference path="common.d.ts" />
+
+type AuthMethods = "PAN_ONLY" | "CRYPTOGRAM_3DS";
+
+interface GooglePay {
+    setupGooglePay(setting: {
+        googleMerchantId: string;
+        allowedCardAuthMethods: AuthMethods[];
+        merchantName: string;
+        billingAddressFormat: "FULL" | "MIN";
+        allowPrepaidCards: boolean;
+        allowedCountryCodes: string[]
+        emailRequired?: boolean;
+        shippingAddressRequired?: boolean;
+        billingAddressRequired?: boolean;
+        phoneNumberRequired?: boolean;
+    }): void;
+
+    setupPaymentRequest(paymentReqeuestData: {
+        allowedNetworks: AllowedNetworks[];
+        price?: string;
+        currency?: string;
+    }): void;
+
+    setupGooglePayButton(setting: {
+        el: string;
+        color: "black" | "white";
+        type: "long" | "short";
+        getPrimeCallback: (
+            err: {
+                status: number;
+                msg: string;
+                originalError: string | Error;
+            },
+            prime: Pick<BaseResult, "prime">,
+            result: Pick<BaseResult, "client_ip"> & MerchantReferenceInfo & {
+                card_info: CardInfoV2;
+            }
+        ) => void;
+    }): void;
+
+    setupTransactionPrice(transactionPrice: {
+        price: string;
+        currency: string;
+    }): void;
+
+    getPrime(callback: (
+            err: {
+                status: number;
+                msg: string;
+                originalError: string | Error;
+            },
+            prime: Pick<BaseResult, "prime">,
+            result: Pick<BaseResult, "client_ip"> & {
+                card_info: CardInfoV2;
+                merchant_reference_info: {
+                    affiliate_codes: string[];
+                };
+            }
+        ) => void): void;
+}

types/tpdirect/index.d.ts

@@ -0,0 +1,7 @@
+// Type definitions for non-npm package tpdirect-browser 5.5
+// Project: https://docs.tappaysdk.com/tutorial/en/home.html
+// Definitions by: Yu-Jack <https://github.com/Yu-Jack>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+/// <reference path="tpdirect.d.ts" />
+
+declare const TPDirect: TPDirect;

types/tpdirect/jko-pay.d.ts

@@ -0,0 +1,7 @@
+/// <reference path="common.d.ts" />
+
+interface JkoPay {
+    getPrime(callback: (
+        result: BaseResult
+    ) => void): void;
+}

types/tpdirect/line-pay.d.ts

@@ -0,0 +1,11 @@
+/// <reference path="common.d.ts" />
+
+interface LinePayGetPrimeResult extends BaseResult {
+    cs_key: string;
+}
+
+interface LinePay {
+    getPrime(callback: (
+        result: LinePayGetPrimeResult
+    ) => void): void;
+}

types/tpdirect/payment-request-api.d.ts

@@ -0,0 +1,65 @@
+/// <reference path="common.d.ts" />
+
+interface PaymentRequestData {
+    supportedNetworks: AllowedNetworks[];
+    supportedMethods: string[];
+    options?: {
+        requestPayerEmail: boolean;
+        requestPayerName: boolean;
+        requestPayerPhone: boolean;
+        requestShipping: boolean;
+        shippingType: 'shipping' | 'delivery' | 'pickup';
+    };
+    shippingOptions: Array<PaymentRequestAmount & {
+        id: string;
+        detail: string;
+    }>;
+    displayItems: PaymentRequestAmount[];
+    total: PaymentRequestAmount;
+}
+
+interface PaymentRequestApi {
+    /**
+     * ```markdown
+     * `true` support payment request api
+     * `false` doesn't support payment request api
+     * ```
+     */
+    checkAvailability(): boolean;
+
+    setupPaymentRequest(paymentRequestData: PaymentRequestData, callback: (result: {
+        /**
+         * Does Browser support Payment Request API
+         */
+        browserSupportPaymentRequest: boolean;
+        /**
+         * Does this device have card to make payment
+         */
+        canMakePaymentWithActiveCard: boolean;
+    }) => void): void;
+
+    setupApplePay(applePaySetting: {
+        merchantIdentifier: string;
+        countryCode: string;
+    }): void;
+
+    getPrime(callback: (result: BaseResult & MerchantReferenceInfo & {
+        prime_expiry_millis: number;
+        total_amount: string;
+        payer: {
+            name: string;
+            email: string;
+            phone: string;
+        }
+        billingAddress: Address;
+        shippingAddress: Address;
+        shippingOption: string;
+        methodName: string;
+        requestId: string;
+        card_info: CardInfoV2;
+        /**
+         * Real Card Info
+         */
+        card: Card
+    }) => void): void;
+}

types/tpdirect/samsung-pay.d.ts

@@ -0,0 +1,29 @@
+/// <reference path="common.d.ts" />
+
+interface SamsungPay {
+    setup(setting: {
+        country_code: string;
+    }): void;
+
+    setupPaymentRequest(paymentReqeuestData: {
+        supportedNetworks: AllowedNetworks[];
+        total: PaymentRequestAmount
+    }): void;
+
+    setupSamsungPayButton(
+        element: string,
+        setting: {
+            color: "black" | "white";
+            type: "pay" | "buy";
+            shape: "shape" | "rectangular";
+        }
+    ): void;
+
+    getPrime(callback: (
+        result: BaseResult & MerchantReferenceInfo & {
+            card_info: CardInfoV2;
+            card: Card;
+            total_amount: string;
+        }
+    ) => void): void;
+}

types/tpdirect/tpdirect-tests.ts

@@ -0,0 +1,231 @@
+/**
+ * Test the startup function
+ */
+
+// $ExpectType void
+TPDirect.setupSDK(1, "appKey", "sandbox");
+// $ExpectType void
+TPDirect.setupSDK(1, "appKey", "production");
+
+/**
+ * Test DirectPay
+ */
+
+// $ExpectType void
+TPDirect.card.getPrime((result) => {
+    /**
+     * Only test different field with other payment response
+     */
+    result.clientip; // $ExpectType Pick<BaseResult, "client_ip">
+    result.card.countrycode; // $ExpectType string
+    result.card.lastfour; // $ExpectType string
+});
+
+// $ExpectType UpdateResult
+TPDirect.card.getTappayFieldsStatus();
+
+// $ExpectType void
+TPDirect.card.onUpdate((update) => {
+    update.cardType; // $ExpectType "mastercard" | "visa" | "jcb" | "amex" | "unionpay" | "unknown"
+});
+
+// $ExpectType void
+TPDirect.card.setup({
+    number: {
+        element: "#body",
+        placeholder: "**** **** **** ****"
+    },
+    ccv: {
+        element: "#body",
+        placeholder: "***"
+    },
+    expirationDate: {
+        element: "#body",
+        placeholder: "MM / YYYY"
+    }
+});
+
+// $ExpectType void
+TPDirect.card.setup({
+    number: {
+        element: "#body",
+        placeholder: "**** **** **** ****"
+    },
+    ccv: {
+        element: "#body",
+        placeholder: "***"
+    },
+    expirationDate: {
+        element: "#body",
+        placeholder: "MM / YYYY"
+    },
+}, {
+    input: {
+        color: "red"
+    }
+});
+
+/**
+ * Test Apple Pay
+ */
+
+// $ExpectType boolean
+TPDirect.paymentRequestApi.checkAvailability();
+
+// $ExpectType void
+TPDirect.paymentRequestApi.setupApplePay({
+    countryCode: "TW",
+    merchantIdentifier: "merchantid"
+});
+
+TPDirect.paymentRequestApi.getPrime((result) => {
+    /**
+     * Only test different field with other payment response
+     */
+    result.client_ip; // $ExpectType string
+    result.card_info.country_code; // $ExpectType string
+    result.card_info.last_four; // $ExpectType string
+    result.card.lastfour; // $ExpectType string
+});
+
+/**
+ * Test Google Pay
+ */
+
+// $ExpectType void
+TPDirect.googlePay.getPrime((error, prime, result) => {
+    error.originalError; // // $ExpectType string | Error
+    prime; // $ExpectType Pick<BaseResult, "prime">
+
+    /**
+     * Only test different field with other payment response
+     */
+    result.client_ip; // $ExpectType string
+    result.card_info.country_code; // $ExpectType string
+    result.card_info.last_four; // $ExpectType string
+});
+
+// $ExpectType void
+TPDirect.googlePay.setupGooglePay({
+    allowPrepaidCards: true,
+    allowedCardAuthMethods: ["CRYPTOGRAM_3DS", "PAN_ONLY"],
+    allowedCountryCodes: ["TW"],
+    billingAddressFormat: "FULL",
+    googleMerchantId: "test",
+    merchantName: "merchant name"
+});
+
+// $ExpectType void
+TPDirect.googlePay.setupTransactionPrice({
+    currency: "TWD",
+    price: "1.00"
+});
+
+// $ExpectType void
+TPDirect.googlePay.setupGooglePayButton({
+    color: "black",
+    el: "#button",
+    type: "long",
+    getPrimeCallback: (error, prime, result) => {
+        error.originalError; // // $ExpectType string | Error
+        prime; // $ExpectType Pick<BaseResult, "prime">
+        /**
+         * Only test different field with other payment response
+         */
+        result.client_ip; // $ExpectType string
+        result.card_info.country_code; // $ExpectType string
+        result.card_info.last_four; // $ExpectType string
+    }
+});
+
+// $ExpectType void
+TPDirect.googlePay.setupPaymentRequest({
+    allowedNetworks: ["AMEX"],
+    currency: "TWD",
+    price: "1.00"
+});
+
+/**
+ * Test Samsung Pay
+ */
+
+// $ExpectType void
+TPDirect.samsungPay.getPrime((result) => {
+    result.client_ip; // $ExpectType string
+    result.msg; // $ExpectType string
+    result.prime; // $ExpectType string
+    result.status; // $ExpectType number
+    result.card.lastfour; // $ExpectType string
+    /**
+     * Only test different field with other payment response
+     */
+    result.client_ip; // $ExpectType string
+    result.card_info.country_code; // $ExpectType string
+    result.card_info.last_four; // $ExpectType string
+});
+
+// $ExpectType void
+TPDirect.samsungPay.setup({
+    country_code: "tw"
+});
+
+// $ExpectType void
+TPDirect.samsungPay.setupPaymentRequest({
+    supportedNetworks: ["AMEX"],
+    total: {
+        label: "test",
+        amount: {
+            currency: "TWD",
+            value: "1.00"
+        }
+    }
+});
+
+// $ExpectType void
+TPDirect.samsungPay.setupSamsungPayButton(
+    "#button", {
+        color: "black",
+        shape: "rectangular",
+        type: "buy"
+    }
+);
+
+/**
+ * Test LINE Pay
+ * LINE Pay doesn't have card_info fields
+ */
+
+// $ExpectType void
+TPDirect.linePay.getPrime((result) => {
+    result.client_ip; // $ExpectType string
+    result.msg; // $ExpectType string
+    result.prime; // $ExpectType string
+    result.status; // $ExpectType number
+    result.cs_key; // $ExpectType string
+});
+
+/**
+ * Test JKOPay
+ * JKOPay doesn't have card_info fields
+ */
+
+// $ExpectType void
+TPDirect.jkoPay.getPrime((result) => {
+    result.client_ip; // $ExpectType string
+    result.msg; // $ExpectType string
+    result.prime; // $ExpectType string
+    result.status; // $ExpectType number
+});
+
+/**
+ * Test EasyWallet
+ * EasyWallet doesn't have card_info fields
+ */
+
+// $ExpectType void
+TPDirect.easyWallet.getPrime((result) => {
+    result.client_ip; // $ExpectType string
+    result.msg; // $ExpectType string
+    result.prime; // $ExpectType string
+    result.status; // $ExpectType number
+});

types/tpdirect/tpdirect.d.ts

@@ -0,0 +1,23 @@
+/// <reference path="direct-pay.d.ts" />
+/// <reference path="payment-request-api.d.ts" />
+/// <reference path="line-pay.d.ts" />
+/// <reference path="jko-pay.d.ts" />
+/// <reference path="easy-wallet.d.ts" />
+/// <reference path="google-pay.d.ts" />
+/// <reference path="samsung-pay.d.ts" />
+
+interface TPDirect {
+    card: DirectPay;
+    paymentRequestApi: PaymentRequestApi;
+    linePay: LinePay;
+    jkoPay: JkoPay;
+    easyWallet: EasyWallet;
+    googlePay: GooglePay;
+    samsungPay: SamsungPay;
+
+    setupSDK: (
+        appId: number,
+        appKey: string,
+        environment: "sandbox" | "production"
+    ) => void;
+}

types/tpdirect/tsconfig.json

@@ -0,0 +1,23 @@
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "lib": [
+            "es6"
+        ],
+        "noImplicitAny": true,
+        "noImplicitThis": true,
+        "strictFunctionTypes": true,
+        "strictNullChecks": true,
+        "baseUrl": "../",
+        "typeRoots": [
+            "../"
+        ],
+        "types": [],
+        "noEmit": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "files": [
+        "index.d.ts",
+        "tpdirect-tests.ts"
+    ]
+}

types/tpdirect/tslint.json

@@ -0,0 +1 @@
+{"extends": "dtslint/dt.json"}