npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

kempo-tax

v0.4.0

Published

Sales tax, VAT and GST for kempo — look up what to charge for an address and items, with Stripe Tax built in

Readme

kempo-tax

Sales tax, VAT and GST for the kempo CMS. Hand it an address and some items, get back what tax to charge — and keep a record of what you collected, in the shape a return asks for.

Two ways to get the rates, behind one interface:

  • Rate table — rows you maintain: a state rate, a local option, which things are exempt. No external service, no per-transaction fee, works with any payment processor. The right choice for a seller in one place, or a few.
  • Stripe Tax — Stripe works out rates and rules for you, which is the right choice once you sell into enough places that keeping a table is the problem.

Switching between them is a setting. Callers do not change.

This kempo (CMS) extension depends on no other kempo extension. It has no catalog, no cart and no idea what a "product" is — the caller supplies the classification of each line, which is what lets a subscription, a donation or an invoice use it exactly as a store checkout does. It sits beside kempo-payments, not on top of it: one works out what is owed, the other moves the money, and either can be swapped without touching the other.

This extension works out tax and keeps a record. It does not register you with, or file returns to, any tax authority, and it does not pay anything to anyone. Whether you owe tax, where, and from when depends on where you are based, where your customers are, how much you sell and what you sell. Talk to an accountant, or to your tax authority.

What it is for

Other kempo (CMS) extensions.

import { calculateTax, recordTransaction, reverseTransaction } from 'kempo-tax/sdk';

const [error, quote] = await calculateTax({
  address: { country: 'US', state: 'VT', postalCode: '05401', city: 'Burlington' },
  lines: [
    { amount: 4999, reference: 'sku-1', taxClass: 'physical' },
    { amount: 1500, reference: 'sku-2', quantity: 3, taxClass: 'digital' },
  ],
  shipping: { amount: 800 },
});

// quote.tax          what is owed
// quote.total        what to charge — hand this to createPayment
// quote.collecting   true when this site collects tax where the customer is
// quote.lines[]      the tax on each line, matched back by your reference
// quote.breakdown[]  per jurisdiction: name, level, rate, taxable amount, amount

// …and once the payment has *succeeded*, not before:
const [, sale] = await recordTransaction({ calculationId: quote.calculationId, reference: order.id });

// on a refund, whole or part:
await reverseTransaction({ transactionId: sale.transactionId, reference: `${order.id}-refund-1`, amount: 1000 });

All amounts are integers in the currency's smallest unit — 4999 is $49.99 — the same as kempo-payments, so quote.total goes straight into createPayment.

Install

npm install kempo-tax

Install it from Admin > Extensions, then open Tax in the admin menu.

For the rate table, open the Rates tab and use the quick start: your country and state, the rate, which classes are taxable and which exempt, whether shipping is taxed, and any local option taxes. It writes ordinary rows you can then edit.

For Stripe Tax, save a Stripe secret key on the Settings tab (or install kempo-payments and connect Stripe there, and this extension borrows its key), switch on Stripe Tax in the Stripe dashboard, and register where you are required to collect. SETTINGS_ENCRYPTION_KEY must be set on the server for a key to be stored.

Connected is not the same as collecting

Both providers answer "what would the tax be" and "are we collecting it here" separately.

  • Rate table: there is a rate row for that place and class, or there is not.
  • Stripe Tax: Stripe calculates a rate for any address and only collects where your account is registered. Everywhere else the tax is 0 with the reason not_collecting.

So quote.collecting distinguishes "this is a 0% rate" from "this site does not collect here". That is not a fault: a small seller under every threshold owes nothing in most places. It matters because a sale made where you are based, with no rate, is the one that makes a return short without anything looking wrong — see Sales at home.

The rate table

Rows are layers

A place is taxed in layers that stack — a country, a state, a county, a city, a district. Vermont's 6% state rate plus a 1% local option in some towns is two rows, and a customer in such a town pays both.

For one line, the rows that apply are chosen like this:

  1. Rows are filtered to those matching the destination (country, then state, town, postal pattern — each blank meaning "any"), the line's class (or *), and the date.
  2. Within one level, the most specific row wins: a postal-code row beats a town row beats a state-wide row. At equal specificity a row for a named class beats a * row, then higher priority, then the later effectiveFrom, then the newer row.
  3. The winners, one per level, are the layers that apply, and their rates add.

A line with no matching row at any level is not_collecting. An exempt row (kind exempt) is different: it says "sold here, no tax", and it is reported on a return as an exempt sale.

A row

| Field | | |---|---| | country, state, locality, postalPattern | Where. Blank means any. State uses the same code your checkout sends (VT). A postal pattern is a comma list of exact codes, prefixes (054*) and ranges (05400-05499). | | taxClass | physical, digital, saas, saas-business, nontaxable, shipping, a txcd_… code, or * for every class | | kind | taxable or exempt | | rate | A percentage with up to four decimals: 6, 7.25, 6.625 | | level | country, state, county, city, district or special — worked out from the place if left blank | | appliesToShipping | Whether this row taxes shipping charges. Shipping is only taxed by rows that say so | | shippingProportional | With appliesToShipping: tax shipping only in proportion to the taxable goods. See below | | effectiveFrom / effectiveTo | YYYY-MM-DD. effectiveTo is exclusive | | jurisdiction, label | The name a report uses, and the name a receipt may show | | priority, enabled, note | |

Shipping

A row with appliesToShipping taxes the shipping charge in full. Add shippingProportional and it taxes only the share of shipping that matches the taxable goods in the order: with $49.99 of taxable goods, $10.00 of exempt goods and $8.00 of shipping, five-sixths of the shipping is taxed. Which one applies is your tax authority's rule, and some states work proportionally. Stripe does for Vermont, which is why this exists: the two providers agree to the cent on the same cart.

Proportional applies to tax added on top. A tax-inclusive shipping charge is taxed in full, because the tax already inside a price cannot be split by what else was bought.

A rate is ended, not edited

When a rate changes, end the old row and add a new one. A sale quoted last month must still be taxed at last month's rate, and a report has to be reproducible. Edit a row only to fix a mistake.

Rates are not floats

A rate is held as an integer count of millionths of a percent (6.625% is 66250), and tax is computed in BigInt and rounded half-up. A tax return that does not reconcile by a cent is one somebody has to explain.

Rounding

Per line by default: each line's tax is rounded, then they are added. rounding: invoice rounds once per tax layer for the whole sale and spreads the result back over the lines (largest remainder), so every line still shows its own share and they sum to the total. Tax-inclusive lines are always rounded by themselves. Use whichever your tax authority's instructions describe.

Sourcing

Destination sourcing — tax by where the goods go — is the default. For a state that taxes an in-state sale by where the seller is, list it under origin_sourcing_states and set your home city and postal code: a sale to your own state is then taxed by your address, and everything else stays destination-based.

Import and export

Export the table as CSV, edit it in a spreadsheet, import it back. An import only adds rows, and if any row is wrong nothing is added and the error names the row. A misspelt column is an error, not silently dropped.

Vermont's local option taxes and what it exempts are not shipped in this package. Rates change, and stale ones are worse than none. Take them from the Vermont Department of Taxes' own published list and enter or import them.

Tax classes

Say what kind of thing a line is.

| Class | Meaning | |---|---| | physical | General tangible goods | | digital | Electronically supplied services and digital goods | | saas | Software as a service, personal use | | saas-business | Software as a service, business use | | nontaxable | Never taxed | | shipping | Shipping and delivery charges |

A rate-table site matches rows by class name. Stripe uses the category behind the name. A line that names no class uses the default tax class setting — a class name or a Stripe category id — and shipping always uses shipping.

Taxing by product type

A line that names no tax class of its own is taxed as the class of its product type, set in the table on Settings → What each product type is taxed as (the tax_class_by_type setting). A caller passes productType on a line, and kempo-commerce does, from the product: { amount: 900, reference: 'x', productType: 'credits-only' }. The order is the line's own taxClass or taxCode, then its product type's class, then the default tax class.

The built-in map is Physical Item → physical and Credits Only → digital. Credits are a digital asset (a game currency, bought for power-ups and cosmetics), so they are taxed as digital goods. They are not stored value like a gift card: that is Store Credit (kempo-store-credit), a money balance that is not sold as a product. That is a reasonable default, not tax advice, and states differ; change it on the Settings screen if your adviser says otherwise. A different class for one product means giving it a different product type.

Prices that already include tax

Off by default, which is US-style pricing: tax is added on top. Turn Prices already include tax on for VAT-style pricing, where the sticker price is what the customer pays. A single line can override with taxBehavior: 'inclusive' | 'exclusive'.

In the result, taxAmountExclusive is tax to add and taxAmountInclusive is tax already inside the amounts. tax is their sum and total is what is actually charged.

Recording, reversing and the ledger

A calculation is a quote. It is safe to ask as often as the page changes, and nothing is reported anywhere. It only counts once you record it.

Recording writes a row to this site's ledger — for every provider, so a return can be produced without depending on any third party, and so history survives a change of provider. With Stripe it also creates the Stripe transaction that appears in their reports.

  • The figures come from the stored quote, never from the caller. You pass a calculationId and your own reference; you cannot pass an amount.
  • Idempotent on reference. Recording the same order twice — a webhook delivered twice, a retry after a timeout — returns the first entry. This is also enforced by a unique index.
  • One calculation records one sale. The same calculationId under a second reference is refused.
  • Reversals take the sale's transactionId, a reference of their own, and optionally an amount (of the tax-inclusive total). Omit it to reverse whatever is left. They are stored as negative entries, always satisfy sales + tax = −amount exactly, and cannot exceed what is left.
  • Entries are immutable. A mistake is corrected by a reversal and a new sale.

A quote is kept for 90 days, then pruned — it holds a customer's address.

Hooks

Fired in notification mode through kempo's triggerHook. Register handlers in your own kempo-config.json.

| Hook | Data | |---|---| | tax:recorded | { entry } — a sale was recorded (not on a repeat) | | tax:reversed | { entry, original } — a reversal was recorded | | tax:uncollected-home-sale | { entry } — see below |

Reports

Admin > Tax > Reports builds totals for a quarter or any date range, by currency and by jurisdiction, and exports them as CSV. The screen and the CSV are built from one report object, so they cannot disagree.

| Figure | Meaning | |---|---| | Sales | Amounts, without tax | | Taxable | Sales that tax was charged on | | Exempt | Sold where you collect, carrying no tax — still reported | | Not collected | Sold where you have no rate — appears on no return | | Tax collected / reversed / net | Sales and refunds, net |

  • A refund counts in the period it happened in, not the period of the original sale.
  • Sales in different currencies are never added together.
  • It is a record, not a filing. The screen says so.
  • Quarters are calendar quarters in UTC. For a fiscal calendar use a custom range (to is exclusive).

Sales at home with no tax collected

If you set the country and state you are based in, then a sale to there that is recorded with no tax collected fires tax:uncollected-home-sale and logs a warning. That is the case that makes a return short silently: the rate was never entered, or the registration was never added. It cannot catch a sale that was never recorded.

Uninstalling

The ledger is a legal record. kempo drops this extension's tables on uninstall, and reinstalling does not bring the rows back. Uninstall prints how many entries and rates are about to be lost and points at the export. Export the ledger first: Admin > Tax > Reports > Export the whole ledger (or GET /tax/api/ledger-export).

SDK

| Function | Does | |---|---| | calculateTax(request) | A quote for an address and lines | | recordTransaction({ calculationId, reference }) | Record a finished sale in the ledger | | reverseTransaction({ transactionId, reference, amount? }) | Reverse some or all of a recorded sale | | listEntries, entriesInPeriod, buildReport, quarterRange | Read the ledger and build reports | | listRates, createRate, updateRate, deleteRate, cleanRate | Manage the rate table from code | | TAX_CLASSES, resolveTaxClass, parseAddress, parsePercent | Validation, for callers that want to check first |

Everything returns [error, data] with error as { code, msg }, like the rest of kempo. These are the data operations with no permission checks of their own — the routes enforce who may do what.

Request

| Field | Notes | |---|---| | address | { country (required, 2 letters), state, postalCode, city, line1 } | | addressSource | 'shipping' (default) or 'billing' | | lines[] | { amount, reference?, quantity?, taxClass?, productType?, taxBehavior? } — amount is the line's total; productType picks the class when none is named (see Taxing by product type) | | shipping | { amount, taxClass?, taxBehavior? } | | currency | Defaults to the setting | | taxIds | [{ type, value }] — Stripe only; may make a sale B2B / reverse-charge | | taxDate | Unix seconds — use the rules in force on that day |

A line with an amount of 0 is kept in the answer, at zero tax, and is never sent. A cart of nothing but free items is answered without calling anything, and has no calculationId — there is nothing to record.

Result

calculationId (record from this), tax, total, collecting, lines[] (each with tax, netAmount, status: taxed / exempt / not_collecting / zero), shipping, breakdown[], currency, provider, expiresAt.

HTTP API

Served under /tax/api/, and every route needs a signed-in user holding the permission. There is deliberately no anonymous endpoint: with Stripe each calculation is an API call and an open one would let anyone spend them, and with either provider it would let anyone fill the quote table. A storefront shows its customers a tax figure by asking from its own server through the SDK.

| Route | Permission | |---|---| | POST /calculate | tax:calculate | | POST /transactions/record, POST /transactions/reverse | tax:record | | GET /rates, GET /rate-export, GET /status, GET /registrations, GET /tax-codes | tax:view | | POST /rates, PUT/DELETE /rate/:id, POST /rate-import, POST /rate-quickstart | tax:rates | | GET /ledger, GET /ledger-export, GET /reports, GET /report-export | tax:reports | | GET /settings, PUT /settings | tax:settings |

Groups: kempo-tax:viewer, kempo-tax:bookkeeper (what an order system or accountant acts as) and kempo-tax:administrator. Browser client: import { calculateTax } from '/tax/sdk.js'.

Failing loudly

Not connected, or Stripe unreachable, is an error, never a quiet zero. A checkout that silently stops charging tax for a week because a key expired is a liability that grows with every order; a loud failure is fixed the same afternoon. Decide in the caller what to do with one — most checkouts should refuse to complete.

The people who hold tax:settings are also told. When a calculation fails because tax is not working (not connected, a key that was refused, the service down; not a bad address, which is the caller's to fix) a banner that must be acknowledged says so and links to the settings. It is raised at most once an hour however many calculations fail, and acknowledged by the first calculation that works again. Needs kempo >= 4.15.0.

Providers

rates and stripe, behind a small interface (server/providers/index.js documents it). TaxJar and Avalara are the intended extensibility targets — each a new file there, not a change to anything that ever called calculateTax.

Stripe Tax, as it actually behaves

Verified against a live test-mode Stripe account on 2026-10-14: a calculation for a registered state, an unregistered one, recording a sale and finding the transaction at Stripe under the same reference, idempotent re-recording, a partial reversal and the remainder (each found at Stripe, pointing at the sale), a refused over-reversal, and a report that nets to zero. The default test run never calls Stripe; to repeat the check yourself, use a test-mode key from an account with Stripe Tax switched on and a head office address, add a test registration, and run a calculation, a record and a reversal through the API.

Things that only a live run showed, and that are worth knowing:

  • Stripe combines the layers of a place into one rate. Vermont's 6% and a town's 1% arrive as a single 7.0, with no jurisdiction names, so a Stripe-backed report groups by state (VT, rate 7). The rate table is what gives a per-layer breakdown.
  • Stripe taxes shipping in proportion to the goods. With $49.99 taxable and $10 exempt, only that share of an $8 shipping charge is taxed. Give the rate table's shipping rows shippingProportional and the two agree: a head-to-head of 21 carts across Burlington, Montpelier and Rutland (goods, mixed carts, digital, SaaS, odd cents, shipping) matched Stripe to the cent once the table held the same rows. Where they differed it was data — a local-option town that was not in the table — not arithmetic.
  • Stripe returns a rate for any address and not_collecting outside your registrations, which is what collecting reports.
  • The six class names resolve to the right categories. Each id was checked against Stripe's own list of 677 codes: txcd_99999999 General - Tangible Goods, txcd_10000000 Electronically Supplied Services, txcd_10103000 / txcd_10103001 SaaS personal / business use, txcd_00000000 Nontaxable, txcd_92010001 Shipping.

Not here

  • Filing returns, registering, and paying.
  • An address book. The caller owns addresses; this takes a plain object.
  • Shipping rates. This works out tax on a shipping charge, not what to charge.
  • Exemption certificates and resale handling.
  • A bundled rate dataset. Deliberately — see above.

Development

npm install
npm run link:local   # symlink sibling kempo checkouts; never commit a file: specifier
npm test

Tests run against an in-memory Postgres (PGlite) and never call Stripe. A symlinked kempo cannot see this package's test dependencies; to run them as CI does, install the registry copies instead: npm install --no-save --no-legacy-peer-deps --force kempo@latest kempo-ui@latest kempo-server@latest.