I Packaged Our Tariff Engine for npm — Versioned Data, Zero Dependencies, and Trusted Publishing

说明与用途

将关税计算引擎打包到 npm 包中，实现可复现、可审计的结果，消除外部依赖。

问题

US tariff calculations change frequently, making it hard to reproduce past quotes and answer audit questions.

结果

The packaged engine delivers reproducible, auditable tariff calculations without external dependencies, simplifying CI pinning and audit trails.

工作流

• 1. Bundle the ruleset JSON and TypeScript engine into a single ESM package using esbuild with platform neutral and minify options.
• 2. Ensure the published artifact is built only from public, cleaned data by removing internal metadata paths.
• 3. Publish the package to npm staging, obtain manual approval, then promote to live.
• 4. Consume the package in client code by importing rulesetSeed, searchHts, and calculateLandedCost, passing entryDate and other parameters.
• 5. Receive deterministic results that include legalBasis, source URLs, and status for each layer, enabling auditability.

证据

US tariff math has a reproducibility problem. The rules changed roughly five times a month through 2026 — new Section 301 tiers, sector measures, fee schedules — and every change retroactively makes your old quotes look wrong.

来源

The package ships one versioned seed — rulesetVersion and dataAsOf right in the JSON — and the engine is a set of pure functions over it.

来源

The build is a thin esbuild script: ... platform: 'neutral' keeps Node built-ins out of the bundle graph, minified ruleset JSON inlines into the output, and a hand-written CLI (bin: us-tariff) gets copied in as a separate file.

来源

npm's flow for a first-time publisher turned out to be sensibly paranoid: publish to staging, a human approves, then it goes live.

来源