@nmbrco/sdk

@nmbr/sdk [internal]

This is an SDK for Nmbr's APIs meant for internal use only.

Everything about it is subject to change. We do not officially support it for external use. If you would like to use it in your project, please reach out to the Nmbr team.

TODO

• [ ] T-4012 Decouple SDK from API spec codegen

Clients

Nmbr Client [server-to-server only]

import { fetchWithCachedResponse } from "@example/fetch-compatible-lib";
import Nmbr, * as nmbr from "nmbr/server";

const nmbr = new Nmbr({
  apiKey: process.env.NMBR_API_KEY,
  apiSecret: process.env.NMBR_API_SECRET,
  // optional; defaults to `nmbr.utils.fetchJSON`
  fetcher: (path, init) =>
      fetchWithCachedResponse(path, init).then(nmbr.utils.expectJSONResponse),

  // [more optional parameters]:
  // apiHost = "https://staging.nmbr.co",
  // apiPath = "/services/payroll",
  // tokenStorage?: {
  //   getItem: (companyId: string) => Promise<Record<string, unknown>>;
  //   setItem: (companyId: string, token: Record<string, unknown>) => Promise<void>;
  // }
});

// example usage
const company = await nmbr.companies.create({ name: "Acme Burgers" });
const businessEntity = await nmbr.forCompany(company)
  .businessEntities.create({ name: "Acme Burgers" });

• Implements core REST API [full API coming soon]
• Accepts credentials (public & secret); optional API host & path; optional fetcher (default fetch) and optional token storage (default none)
• Manages token re/issuance lifecycle for company-scoped resources
• Supports addl partner-level resources, e.g. webhooks [coming soon]

Company Client [browser & server-to-server]

// example browser usage
// servers access via `nmbr.forCompany(companyOrCompanyId)`
import * as nmbr from "@nmbrco/sdk";
import { fetchWithCustomAuthHeaders } from "@example/fetch-compatible-lib";

const client = new nmbr.CompanyClient({
  baseUrl: "/api/nmbr",
  // optional; defaults to nmbr.utils.fetchJSON
  fetcher: fetchWithCustomAuthHeaders.then(nmbr.utils.expectJSONResponse),
  company: {
    id: window.authenticatedNmbrCompanyId, // required
    // businessEntities: [...],
    // employees: [...],
    // ...more initial data
  },
});

// example usage — subscribe to observable dbs
client.businessEntities.db$.subscribe((values) =>
  console.log("emitted new business entities", values)
);
client.businessEntities.payrolls.db$.subscribe((values) =>
  console.log("emitted new payrolls", values)
);

// example usage - `findAll` on an entity, with expands
client.businessEntities
  .findAll({ expand: ["payrolls.pay_stubs.line_items.recurrence"] })
  .then(console.log);

// expected console output:
// => [returned businessEntities]
// => "emitted new business entities", [returned businessEntities]
// => "emitted new payrolls", [returned payrolls, flattened]

• Provides typesafe find, findAll, create, update, destroy for core company-scoped resources, e.g. employees, business entities, payrolls…
• Maintains a local cache linked to related resources; updates mutate cache objects & emit on an observable
• In server-to-server environments, fetcher provided automatically when accessed through Nmbr Client. In browser environments, fetcher should use a fetch authed to the host app

💡 For browser CompanyClients, we suggest setting up middleware on a generic path (e.g. api.myapp.com/nmbr/*) to authorize and proxy the request.

// the `@nmbrco/sdk/connect` interface provides helpers for express.js & other connect-based apps
import { initialize } from "@nmbrco/sdk/connect";
import express from "express";

const app = express();
const nmbr = initialize({
  apiKey: process.env.NMBR_API_KEY,
  apiSecret: process.env.NMBR_API_SECRET,
});

// authenticate & authorize the request; in this case on all `/api` requests.
// assume this throws an error, or otherwise sets `res.locals.authorizedUser`
app.use("/api", function authorizeMiddleware(_req, _res, next) {
  next();
});

// prepare a `res.locals.nmbr` client for the authorized request
app.use("/api/nmbr", (res) => {
  const { nmbrCompanyId } = res.locals.authorizedUser;

  res.locals.nmbr = nmbr.forCompany(nmbrCompanyId);
});

// override any routes before falling through to a proxy
// app.post("/api/nmbr/employments", myCustomHandler);
app.use(
  "/api/nmbr",
  nmbr.proxyWithCompanyClient((req, res) => res.locals.nmbr)
);

HTTP Client [internal; browser & server-to-server]

• Used by Nmbr Client, Company Client, and Resource Clients [also elsewhere in the demo site]
• Abstract class, extend it to provide typesafe get, post, put, delete methods
• Constructed with a baseUrl and a generic fetcher: <ResponseType = Response>(path: string | URL, init?: RequestInit) => ResponseType
• Request paths are resolved against baseUrl and converted to ResponseType

[fin]