biz-sdk
v0.3.27
Published
SDK for BizBot based applications
Downloads
135
Readme
BizBot SDK
Integration to your App
npm install biz-sdk --save
const bizSdk = require('biz-sdk')({ ...params });
Params:
env [string, required] - curent environment. Recommended options are
local
,dev
,stage
,prod
.appToken [string, required] - application token. Contact BizBot in order to get appToken and then to be added to the list of apps when everything ready.
host [string, required] - current url, used for generating links
pageTitle [string, required] - default page title.
showInAppsList [boolean, optional] - default is
false
. Use it to show your App in list on left menu. Designed to be used on dev environment only.appIcon [string, optional] - icon for you app in menu. Check https://feathericons.com/ to choose one.
logLevel [string, optional] - disable logs except passed. Possible options are
all
,info
,warnings
,errors
,none
. Default isall
.Example integration:
// index.js
const port = process.env.port || 8127;
const express = require('express');
const http = require('http');
const app = express();
const { routesPublic, routes } = require('./routes');
const sdk = require('biz-sdk');
async function startServer() {
try {
// biz-sdk initialization
const bizSdk = await sdk({
env: process.env.ENV || 'local',
host: 'http://localhost:8127',
pageTitle: 'BIZSDK DEV - BizBot',
showInAppsList: true,
appIcon: 'external-link',
appToken: 'bd7fac74-2a4b-484d-a88e-f6ea4563564b',
});
bizSdk.setPublicRoutes(
routesPublic(bizSdk.templates, bizSdk.helpers.getTranslationStrings)
);
bizSdk.setPrivateRoutes(
routes(bizSdk.templates, bizSdk.helpers.getTranslationStrings)
);
app.use(bizSdk.getRoutes());
const httpServer = http.createServer(app);
httpServer.listen(port, function() {
console.log('--== Development environment ==--');
console.log('Listening on port %d', httpServer.address().port);
console.log('-== You application config is: ==-');
console.log(bizSdk.appConfig);
});
} catch (err) {
console.error('Error initializing server', err);
}
}
startServer();
module.exports = app;
// routes.js
const { Router } = require('express');
const routes = (templates) => {
const routes = Router();
routes.get('/', async function (req, res, next) {
try {
res.send(await templates.wrapBodyPrivate({
htmlBody: `<Render your private page here>`,
locale: req.cookies.lng,
context: res.locals.context
}));
} catch (err) {
return next(err)
}
});
return routes;
};
const routesPublic = (templates) => {
const routes = Router();
routes.get('/public', async function (req, res, next) {
try {
res.send(await templates.wrapBodyPublic({
htmlBody: `<Render your public page here>`,
locale: req.cookies.lng,
context: res.locals.context
}));
} catch (err) {
return next(err)
}
});
return routes;
};
module.exports = { routes, routesPublic };
- Run you app
BizSDK frontend methods
- login(cb, options)
- cb [function, required]
- options:
- loaderId [string, optional] - loader element id e.g.
auth_loader
to become hidden when auth form loaded. Does not make sense ifparent
ismodal
- requireEmail [boolean, optional] - default is
true
. Show prompt asking email if user doesn't have it already
- loaderId [string, optional] - loader element id e.g.
- logout(redirect)
- redirect [string, optional] - redirect url after logging out
- showError(message)
- message [string, optional] - default is
Unexpected error
- message [string, optional] - default is
- showMessage(message, status)
- message [string, required]
- status [string, optional] - default is
success
.
- blockUI() - show loader blocking UI
- unblockUI() - hide loader that blocks UI
- updateNotificationCounter(contextId, userId, companies)
- contextId [string|number, required] - userId or company orgNumber of current context
- userId [string|number, required] - current userId
- companies [array, required] - list of orgNumbers which counters should be checked, e.g. using data
user.companies.map(i => i.orgNumber)
- getToken() - get current token
Payment process
- make POST request to
/{context}/payments/payment-link
wherecontext
ispersonal
or company org.number with body:- orgNumber [string, optional] - if the payment is on behalf of the company
- redirectUrl [string, required] - redirect if payment is succeed
- failedRedirectUrl [string, optional] - redirects if payment is failed or declined by user.
By default
redirectUrl
will be used if value is not passed. - vat [number, optional] - VAT tax percentage, default is
25
%. Pass0
if VAT should not be applied to your case. - amount [number, required] - in cents excluding VAT, e.g.
1000
for 10 NOK, so total amount is 12.5 NOK incl. VAT. Note that the minimal amount is3000
because of Stripe's limitations. But some currencies are zero-decimal, then you don't need to multiply values. Check the list at https://stripe.com/docs/currencies#zero-decimal - currency [string, optional] - default is NOK.
- description [string, optional] - text description of selling services or goods.
It also will be shown in payment receipt. Default is
payment from Ivan Lee ([email protected]) 10 NOK including VAT 25%
- items [array, optional] - items to be shown on the payment page. This data will not be included into payment receipt.
- name [string] - service or good name, e.g
Lawyer support for preparing Agreement template
- price [number|string] - use ready to show format, e.g.
10 NOK
or15 NOK per signer
- name [string] - service or good name, e.g
- autoCapture [boolean, optional] - default is
true
. Define if funds are charged immediately, otherwise it should be done manually on Stripe's admin panel which is available for BizBot owner and maintainers only - metadata [dict, optional] - any other data you'd like to pass to payment's
metadata
, e.g.{ order_id: 4325, item_name: 'Hamburger' }
. Fieldcustomer_internal_id
will be passed there automatically
- use
url
from the response and go to this page, e.g. usingwindow.location.href = url;
. Note that link is valid for 1 day - don't forget to implement
redirectUrl
andfailedRedirectUrl
to handle payment status changing on your side. Note thatintentId
query parameter will be added to your successful redirect url. You can get payment details such as receipt url using request GET/payments/intent/:intentId
.
Also you can make a refund by calling POST /payments/intent/:intentId/refund
- amount [number, optional] - by default it will refund full amount
Subscription process
- ensure that subscription object is created on Stripe Dashboard and there is a valid tax rate entity for the subscription, tax rate should be exclusive
- make POST request to
/{context}/payments/subscription-link
wherecontext
ispersonal
or company org.number with body:- orgNumber [string, optional] - if the it's on behalf of the company
- redirectUrl [string, required] - redirect if subscription payment is succeed
- failedRedirectUrl [string, optional] - redirects if subscription is failed or declined by user. By default
redirectUrl
will be used if value is not passed. - subscriptionId [string, required] - id of subscription to subscribe on.
- isTrial [boolean, optional] - default is
false
. - trialPeriod [number, optional] - trial period in days, e.g.
14
for 2 weeks. Takes into account only ifisTrial
istrue
. - taxRate [string, optional] - id of Stripe taxRate entity. Default is 25% norwegian VAT.
- trialSubscriptions [array, optional] - list of subscription IDs among which system will try to find and cancel existing trial period and replace it with new subscription. Passed
subscriptionId
will be pushed to the list in any case. It works the same way for trial subscription. If you'd like the trial to be used once only, check it yourself before this endpoint calling. - amount [number, required] - in cents excluding VAT, e.g.
10000
for 10 NOK, so total amount is 12.5 NOK incl. VAT. IfisTrial
istrue
then 0 is allowed. Note that there are different minimal amounts for different currencies because of Stripe's limitations, e.g.3000
NOK. Some currencies are zero-decimal, then you don't need to multiply values. Check the list at https://stripe.com/docs/currencies#zero-decimal - currency [string, optional] - default is NOK.
- description [string, optional] - general text description for subscription. It also will be shown in payment receipt.
- items [array, optional] - items to be shown on subscription page. This data will not be included into receipt.
- name [string] - service or good name, e.g
Lawyer support
,Full access
- value [number|string|boolean] - e.g.
15 NOK per document
ortrue
- will appear as icon ✔ or ❌.
- name [string] - service or good name, e.g
- metadata [dict, optional] - any other data you'd like to pass to
metadata
, e.g.{ type: 'trial', desc: 'Annual Premium plan' }
. Fieldcustomer_internal_id
will be passed there automatically
- use
url
from the response and go to this page, e.g. usingwindow.location.href = url;
. Note that link is valid for 1 day - don't forget to implement
redirectUrl
andfailedRedirectUrl
to handle subscription status changing on your side