Stripe: Balance Transactions, Extract as TSV by Payout ID

main();

function main(){

    const auth = configs.get("conf_auth");
    const payoutId = configs.get("conf_payout_id");
    
    const tempDDView = configs.getObject("conf_limit");
    let limit = 0;

    if(tempDDView !== null){
        limit = engine.findDataByNumber(tempDDView.getNumber());
    }else{
        limit = Number(configs.get("conf_limit"));
    }

    const balanceTransactions = listAllBalanceTransactions(auth, payoutId, limit);

    const conf_tsv = configs.get("conf_tsv");
    const conf_num = configs.get("conf_num");    

    if(conf_tsv !== ""){
        engine.setDataByNumber(configs.get("conf_tsv"), createBalanceTransactionsTsv(balanceTransactions));
    }
    if(conf_num !== ""){
        engine.setDataByNumber(configs.get("conf_num"), new java.math.BigDecimal(balanceTransactions.data.length));
    }

}

//limit: can range between 1 and 100, and the default is 10.
function listAllBalanceTransactions(auth, payoutId, limit){

    let request = httpClient.begin();
    request = request.authSetting(auth);

    if(payoutId !== ""){
        request = request.queryParam("payout", payoutId);
    }
    
    if(limit >=1 && limit <= 100){
        request = request.queryParam("limit", String(limit));
    }else{
        engine.log("Limit can range between 1 and 100, and the default is 10.");
    }

    const response = request.get("https://api.stripe.com/v1/balance_transactions");

    const httpStatus = response.getStatusCode();
    const responseStr = response.getResponseAsString();
    engine.log("HTTP Status: " + String(httpStatus));

    const balanceTransactions = JSON.parse(responseStr)
    if(httpStatus===200){
        engine.log(balanceTransactions.data.length + " balance transactions");
        return balanceTransactions;
    }else{
        engine.log(responseStr);
        throw "listAllBalanceTransactions Error: HTTP Status was not 200.";
    }

}

//TSV which consists of the values of Balance Transaction Object(JSON) Elements will be retured.(except for fee_details)
function createBalanceTransactionsTsv(balanceTransactions){
    let tsv = "";
    for(let i = 0 ; i < balanceTransactions.data.length ; i++){
        tsv += balanceTransactions.data[i].id + "\t";
        tsv += balanceTransactions.data[i].amount + "\t";
        tsv += epochTimeToDateString(balanceTransactions.data[i].available_on) + "\t";
        tsv += epochTimeToDateString(balanceTransactions.data[i].created) + "\t";
        tsv += balanceTransactions.data[i].currency + "\t";
        tsv += balanceTransactions.data[i].description + "\t";
        tsv += balanceTransactions.data[i].exchange_rate + "\t";
        tsv += balanceTransactions.data[i].fee + "\t";
        tsv += balanceTransactions.data[i].net + "\t";
        tsv += balanceTransactions.data[i].reporting_category + "\t";
        tsv += balanceTransactions.data[i].source + "\t";
        tsv += balanceTransactions.data[i].status + "\t";
        tsv += balanceTransactions.data[i].type;
        tsv += "\n";
    }
    return tsv;
}

/*
String Format Date("YYYY-MM-DD") will be returned.
timestamp: Integer Unix timestamp(second)
*/
function epochTimeToDateString(timestamp){
    return new java.text.SimpleDateFormat("yyyy-MM-dd").format(new java.sql.Date(timestamp * 1000));
}


/*
Notes:
- Can include the automated step "listng all balance transactions as tsv by payout id" into the workflow.(No code)
    - When the matter reaches, a listing all balance transactions request is automatically sent to the Stripe API.
    - stripe API: GET /v1/balance_transactions
    - https://stripe.com/docs/api/balance_transactions/list
- The Stripe API key "secret key" is required for HTTP_Authz Setting.
    - https://dashboard.stripe.com/apikeys
    - https://dashboard.stripe.com/test/apikeys
- If you want to test-operate the workflow app, use the "test key" of the Stripe API key.
    - Set the secret key starting with `sk_test_` to "HTTP Authorization Aetting > Token Fixed Value".
        - Name: `StripeSecretKeyForXYZ`
        - Token: `sk_test_123456789012345678901234`
    - For actual operation, set a secret key starting with `sk_live_`.
- Extracted TSV has 13 columns. (All elements of Payout except for "fee_details") [Details of Balance Transaction Object](https://stripe.com/docs/api/balance_transactions/object)
    - [0] Balance Transaction ID
    - [1] Amount: Gross Amount of the transaction
    - [2] Available On: (YYYY-MM-DD)
    - [3] Created: (YYYY-MM-DD)
    - [4] Currencty: ("usd" "jpy" etc.)
    - [5] Description
    - [6] Exchange Rate
    - [7] Fee: Fees paid for this transaction
    - [8] Net: Net amount of the transaction
    - [9] Reporting Category
    - [10] Source: The Stripe object to which this transaction is related
    - [11] Status: ("available" or "pending")
    - [12] Type: [Balance transaction types](https://stripe.com/docs/reports/balance-transaction-types)
Notes(ja):
- ワークフロー内に自動工程『残高取引TSV抽出処理(入金ID指定)』を組み込めるようになります。（ノーコード実装）
    - 案件が到達するとStripe APIに対して残高取引抽出リクエストが送信されます。
    - stripe API: GET /v1/balance_transactions
    - https://stripe.com/docs/api/balance_transactions/list
- 通信設定には、Stripe APIキーの "シークレットキー" が必要です。
    - https://dashboard.stripe.com/apikeys
    - https://dashboard.stripe.com/test/apikeys
- ワークフローアプリをテスト運用したい場合は、テスト用のシークレットキー "テストキー" を利用します。
    - `sk_test_` で始まるテストキーを『HTTP認証設定 ＞ トークン直接指定』に設定します。
        - Name: `StripeSecretKeyForXYZ` 
        - Token: `sk_test_123456789012345678901234` 
    - 本運用する場合は `sk_live_` で始まるシークレットキーを設定します。抽出されるTSVは20列。(metadata 以外の全てのPayout要素)
- 抽出されるTSVは13列。Payout fee_details 以外のものすべて。 [Balance Transaction オブジェクトの詳細](https://stripe.com/docs/api/balance_transactions/object)
    - [0] Balance Transaction ID: 取引ID
    - [1] Amount: 取引総額
    - [2] Available On: (YYYY-MM-DD)
    - [3] Created: 取引データが生成された日(YYYY-MM-DD)
    - [4] Currencty: 通貨("usd" "jpy" etc.)
    - [5] Description: 説明
    - [6] Exchange Rate
    - [7] Fee: Stripe 手数料
    - [8] Net: 取引金額からStripe手数料が差し引かれた金額
    - [9] Reporting Category
    - [10] Source: 取引に関連のあるデータのID
    - [11] Status: ("available" or "pending")
    - [12] Type: [Balance transaction types](https://stripe.com/docs/reports/balance-transaction-types)
*/