@nmbrco/components
v0.8.0
Published
Nmbr's components library - host js
Downloads
17
Readme
@nmbr/components
💡 Follow along in our official Quickstart Guide
Nmbr Components offer a fully-featured payroll suite in a lightweight integration. It takes less than an hour for a single developer to add payroll features to any app using our embeddable payroll module, designed and built by our in-house experts to work seamlessly with your data in any environment.
To get started, you will need the following:
- A Partner ID, API Key, and API Secret from our Portal.
- The ability to add a server-side endpoint in your app's API
- The ability to add or change HTML pages in your app's UI
1 - Set up the Server
Every API request made by Nmbr Components requires a signature from your app. This keeps your users' data secure, and minimizes the PII available to your systems.
Install a JWT library
Nmbr Components use JSON Web Tokens (JWTs) signed on your server to prove a user is authorized to read and write payroll data. Their website features libraries in several languages, although some listed may be out of date.
npm install jsonwebtoken🙋 Don't want to use a library? You may also implement signing yourself by following the JWT spec (RFC 7519).
Create a signing endpoint
Add an endpoint on your server to sign pre-formed JWTs. When you mount Nmbr Components in your app (step 2), this endpoint will be used to initialize the library.
// server.js
import jwt from 'jsonwebtoken';
import express from 'express';
import crypto from 'node:crypto';
const PORT = process.env.PORT ? parseInt(process.env.PORT) : 8080;
const NMBR_API_SECRET = process.env.NMBR_API_SECRET ?? 'invalid-secret';
const SIGNING_HASH = crypto // We will sign request bodies
.createHash('sha256') // with the SHA-256 hash
.update(NMBR_API_SECRET) // of your API Secret
.digest('hex'); // formatted as a hex string
// (though base64 is supported too)
const app = express();
app.post(
'/sign_nmbr_request',
// Your app should authenticate the user and
// ensure they are authorized to administer payroll
express.json(),
(req, res) => res.status(201).send(jwt.sign(req.body, SIGNING_HASH)),
);
app.listen(PORT, () => console.log(`Running on port ${PORT}`));2 - Mount the Run Screen
Nmbr Components use a single script to securely initialize, load, and orchestrate components from Nmbr's servers inside your app.
Install @nmbr/components
Download the script directly from Nmbr's CDN
npm install @nmbr/componentsInitialize Nmbr Components
As soon as your page allows it, initialize host.js to start loading resources that will make the components load faster and smoother for your users.
<!doctype html>
<html>
<head>
<!-- Critical scripts -->
<script type="module">
import * as nmbr from '@nmbr/components';
// You must provide these when initializing the host script.
// These are anonymized identifiers we generate that do not contain PII.
const partnerId = 'your-partner-id';
const companyId = 'user-company-id';
// Initialize Nmbr Components as early as you can
// to minimize perceived latency for the user.
window.components = nmbr.initialize({
companyId,
partnerId,
signingUrl: '/sign_nmbr_request', // Use the same value as above
// [optional params]
// sandbox = false,
// sign = async (json: string): Promise<string> => {
// const response = await fetch(this.signingUrl, {
// method: 'POST',
// headers: {
// Accept: 'text/plain',
// 'Content-Type': 'application/json',
// },
// body: json,
// });
//
// return response.text();
// }
});
// if your ui supports toggling between companies or between sandbox
// and production, you may `reinitialize` any loaded components:
nmbr.reinitialize({
companyId: 'another-company-id',
sandbox: true
});
</script>
<!-- Meta tags; style links; other scripts; etc -->
</head>
<body>
<!-- Continued below -->
</body>
</html>Load the Run Payroll component
Once your host.js script is initialized, you may embed Nmbr's Run Payroll component into any element on your page.
<!doctype html>
<html>
<head>
<!-- From above -->
</head>
<body>
<header>
<!-- Your app's topbar content -->
</header>
<div>
<aside>
<!-- Your app's sidebar content -->
</aside>
<main id="nmbr-container">
<!-- Your app might do more; we will embed directly here -->
</main>
<script type="text/javascript">
// Start loading the component as soon as its container is in the DOM
const container = document.querySelector('#nmbr-container');
const frame = components.load('run', container, {
// hideUntilReady = false
});
frame.ready
.then(() =>
console.log('Nmbr Components Run Screen loaded'),
)
.catch((err) =>
console.error(
'Could not load Nmbr Components Run Screen',
err,
),
);
</script>
</div>
</body>
</html>3 - Test your page
At this point, you have finished writing all code required to set up Nmbr Components. Let's see it in action!
Load the payroll page
Start by loading the page you set up in Step 2; you should see the embedded iframe start loading in your container. New companies will always start at the Company Setup screen; once they have completed setup the component will default to the Payroll Dashboard.
🙋 Have a question? Not looking right? Book a call with a Nmbr Components expert today.
Run a payroll in sandbox
Once you've confirmed the component is loading, it is time to submit data. To simulate payroll before you go live, provide the additional option sandbox: true for Nmbr Components to use the sandbox environment. (You may also need to provide different partner credentials configured for the sandbox environment).
const components = nmbr.initialize({
// ...
sandbox: true,
});Congratulations!
You have successfully embedded Nmbr Components in your app.