diff --git a/Readme.md b/Readme.md index 48d6167..60c1cdc 100644 --- a/Readme.md +++ b/Readme.md @@ -1,6 +1,59 @@ -[![NPM Version][npm-image]][npm-url] +[![npm](https://img.shields.io/npm/v/open-fin-ts-js-client-promise.svg)](https://www.npmjs.com/package/open-fin-ts-js-client-promise) + +## Quick-Start Async +Der einfachste Weg ist Open-Fin-TS-JS-Client über NPM durch eine Dependency in der package.json in ein Projekt einzubinden. +Am folgenden Beispiel zum Laden von Kontoumsätzen wird gezeigt wie der Client zu bedienen ist. Bitte beachten: für die keywords async/await und Promise ist die entsprechende Nodejs Version nötig >= 7.6 + +```js +var FinTSClient = require("open-fin-ts-js-client"); +// 1. Definition der Bankenliste - Echte URLs sind hier http://www.hbci-zka.de/institute/institut_auswahl.htm erhältlich. Für mehrere Urls ist ein Object nötig. +var bankenliste = "http://localhost:3000/cgi-bin/hbciservlet" +// 2. FinTSClient anlegen +// BLZ: 12345678 +// Kunden-ID/Benutzerkennung: test1 +// PIN: 1234 +// Bankenliste siehe oben +var client = new FinTSClient(12345678, "test1", "1234", bankenliste); +// start +GetKontoUmsaetze() + +async function GetKontoUmsaetze () { + try{ + // 3. Verbindung aufbauen + await client.EstablishConnection() + console.log('Erfolgreich Verbunden') + + // 4. Kontoumsätze für alle Konten nacheinander laden + let daten=[] + for (let konto of client.konten) { + let data = await client.MsgGetKontoUmsaetze(konto.sepa_data, null, null) + daten.push(data) + } + // Alles gut + // 5. Umsätze darstellen + console.log(JSON.stringify(daten)) + + // 6. Zeige Salden aller Konten + for (let konto of client.konten) { + let saldo = await client.MsgGetSaldo(konto.sepa_data) + console.log('Saldo von Konto ' + konto.iban + ' ist ' + JSON.stringify(saldo.saldo.saldo)) + } + + // 7. Verbindung beenden + await client.MsgEndDialog() + }catch(exception){ + console.error("Fehler: " + exception) + } + // 8. Secure Daten im Objekt aus dem Ram löschen + client.closeSecure() + console.log('ENDE') +} +``` + # Open-Fin-TS-JS-Client + npm i open-fin-ts-js-client-promise + FinTS/HBCI ist eine standardisierte Schnittstelle zur Kommunikation mit Banken von der Deutschen Kreditwirtschaft (DK). Es existieren derzeit drei Versionen der Schnittstelle. * HBCI 2.2 bzw. HBCI+ - Diese API unterstützt diese Version. diff --git a/examples/zeige_kontoumsaetze_async.js b/examples/zeige_kontoumsaetze_async.js new file mode 100644 index 0000000..b61cf34 --- /dev/null +++ b/examples/zeige_kontoumsaetze_async.js @@ -0,0 +1,95 @@ +/* + * Copyright 2015-2016 Jens Schyma jeschyma@gmail.com + * and in case of this file Reiner Bamberger + * This File is a Part of the source of Open-Fin-TS-JS-Client. + * + * This file is licensed to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * or in the LICENSE File contained in this project. + * + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * + * See the NOTICE file distributed with this work for additional information + * regarding copyright ownership. + */ +/* + Dieses Beispiel veranschaulicht wie der Client mit Promises und async/await zu verwenden ist um Kontoumsätze anzuzeigen. +*/ +var FinTSClient = require('../') // require("open-fin-ts-js-client"); +var log = null +try { + var logme = false + process.argv.forEach(function (val, index, array) { + if (val == 'log') logme = true + }) + if (logme) { + var bunyan = require('bunyan') + log = bunyan.createLogger({ + name: 'demo_fints_logger', + stream: process.stdout, + level: 'trace' + }) + } +} catch (ee) { + +}; +// 1. Definition der Bankenliste - Echte URLs sind hier http://www.hbci-zka.de/institute/institut_auswahl.htm erhältlich +var bankenliste = { + '12345678': { + 'blz': 12345678, + 'url': 'http://localhost:3000/cgi-bin/hbciservlet' + }, + 'undefined': { + 'url': '' + } +} + +// 2. FinTSClient anlegen +// BLZ: 12345678 +// Kunden-ID/Benutzerkennung: test1 +// PIN: 1234 +// Bankenliste siehe oben +var client = new FinTSClient(12345678, 'test1', '1234', bankenliste, log) +// start +GetKontoUmsaetze() + +async function GetKontoUmsaetze () { + try{ + // 3. Verbindung aufbauen + await client.EstablishConnection() + console.log('Erfolgreich Verbunden') + + // 4. Kontoumsätze für alle Konten nacheinander laden + let daten=[] + for (let konto of client.konten) { + let data = await client.MsgGetKontoUmsaetze(konto.sepa_data, null, null) + daten.push(data) + } + // Alles gut + // 5. Umsätze darstellen + console.log(JSON.stringify(daten)) + + // 6. Zeige Salden + for (let konto of client.konten) { + let saldo = await client.MsgGetSaldo(konto.sepa_data) + console.log('Saldo von Konto ' + konto.iban + ' ist ' + JSON.stringify(saldo.saldo.saldo)) + } + + // 7. Verbindung beenden + await client.MsgEndDialog() + }catch(exception){ + console.error("Fehler: " + exception) + } + // 8. Secure Daten im Objekt aus dem Ram löschen + client.closeSecure() + console.log('ENDE') +} diff --git a/lib/FinTSClient.js b/lib/FinTSClient.js index 0599d14..d5532c3 100644 --- a/lib/FinTSClient.js +++ b/lib/FinTSClient.js @@ -273,6 +273,16 @@ var FinTSClient = function (in_blz, in_kunden_id, in_pin, in_bankenlist, logger) me.tan = NULL me.debug_mode = false + // Use given blz and forth parameter as url if it's a string + if (typeof in_bankenlist === 'string'){ + var bank_url = in_bankenlist + in_bankenlist = {} + in_bankenlist[in_blz] = { + 'blz': in_blz, + 'url': bank_url + } + } + // Technical me.dialog_id = 0 me.next_msg_nr = 1 @@ -711,10 +721,29 @@ var FinTSClient = function (in_blz, in_kunden_id, in_pin, in_bankenlist, logger) } } } - me.MsgEndDialog(cb) + MsgEndDialog(cb) } + /** + * Beendet eine Verbindung + * @param {function} callback - optional if promise is possible + * @return {promise} The optional Promise when no cb is given or Promise is undefined + */ me.MsgEndDialog = function (cb) { + if(cb || typeof Promise !== 'function') + MsgEndDialog(cb) + else + return new Promise(function(resolve, reject) { + MsgEndDialog(function (error, recvMsg) { + if(error) + reject(error) + else + resolve(recvMsg) + }) + }) + } + + function MsgEndDialog (cb) { var msg = new Nachricht(me.proto_version) if (me.kunden_id != 9999999999) { msg.sign({ @@ -848,13 +877,29 @@ var FinTSClient = function (in_blz, in_kunden_id, in_pin, in_bankenlist, logger) }) } - /* - konto = {iban,bic,konto_nr,unter_konto,ctry_code,blz} - from_date - to_date können null sein - cb + /** + * Lädt die Kontenumsätze für ein bestimmtes Konto + * @param {object} konto - {iban,bic,konto_nr,unter_konto,ctry_code,blz} + * @param {Date} from_date - The date to start from_date + * @param {Date} to_date - The date to stop at + * @param {function} callback - optional if promise is possible + * @return {promise} The optional Promise when no cb is given or Promise is undefined */ me.MsgGetKontoUmsaetze = function (konto, from_date, to_date, cb) { + if(cb || typeof Promise !== 'function') + MsgGetKontoUmsaetze(konto, from_date, to_date, cb) + else + return new Promise(function(resolve, reject) { + MsgGetKontoUmsaetze(konto, from_date, to_date, function (error, recvMsg, umsaetze) { + if(error) + reject(error) + else + resolve({recvMsg, umsaetze}) + }) + }) + } + + function MsgGetKontoUmsaetze(konto, from_date, to_date, cb) { var processed = false var v7 = null var v5 = null @@ -970,11 +1015,27 @@ var FinTSClient = function (in_blz, in_kunden_id, in_pin, in_bankenlist, logger) return result } - /* - konto = {iban,bic,konto_nr,unter_konto,ctry_code,blz} - cb + /** + * Lädt den Saldo eines bestimmten Kontos + * @param {object} konto - Das Konto für das der Saldo geladen werden sollen: {iban,bic,konto_nr,unter_konto,ctry_code,blz} + * @param {function} callback - optional if promise is possible + * @return {promise} The optional Promise when no cb is given or Promise is undefined */ me.MsgGetSaldo = function (konto, cb) { + if(cb || typeof Promise !== 'function') + MsgGetSaldo(konto, cb) + else + return new Promise(function (resolve, reject) { + MsgGetSaldo(konto, function (error, recvMsg, saldo) { + if(error) + reject(error) + else + resolve({recvMsg, saldo}) + }) + }) + } + + function MsgGetSaldo (konto, cb) { var req_saldo = new Order(me) var processed = false var v5 = null @@ -1075,8 +1136,26 @@ var FinTSClient = function (in_blz, in_kunden_id, in_pin, in_bankenlist, logger) } }) } - + /** + * Vereinfachte Variante um eine Verbindung mit der Bank aufzubauen + * @param {function} callback - optional if promise is possible + * @return {promise} The optional Promise when no cb is given or Promise is undefined + */ me.EstablishConnection = function (cb) { + if(cb || typeof Promise !== 'function') + EstablishConnection(cb) + else + return new Promise(function(resolve, reject) { + EstablishConnection(function (error) { + if(error) + reject(error) + else + resolve() + }) + }) + } + + function EstablishConnection (cb) { var protocol_switch = false var vers_step = 1 var original_bpd = me.bpd.clone()