@khalidadil/shipping-manager (0.1.0-alpha.0)

2026-09-02T02:16:47Z

Setup this registry in your project .npmrc file:

@khalidadil:registry=

To install the package using npm, run the following command:

npm install @khalidadil/shipping-manager@0.1.0-alpha.0

or add it to the package.json file:

"@khalidadil/shipping-manager": "0.1.0-alpha.0"

For more information on the npm registry, see the documentation.

@khalidadil/shipping-manager

Carrier-rate engine for the commerce stack. One RateProvider abstraction, failure as a first-class case (four US carriers died 2024–26), and the economics posture the 2026 research forced: checkout quotes from tables/cache, live rate-shopping runs at label time and on the bench — because aggregators meter rate calls and USPS's default quota is ~60/hour.

. (core) — RateEngine (fan-out, per-provider timeouts, partial-failure tolerance, dedupe, cheapest/cheapestPerTier/ fastestUnder, CONUS coverage guard: zero national rates = degraded), TableRateProvider with day-level surcharge windows, quote/OAuth caches, and a USPS Ground Advantage TX-origin table seeded from published Notice-123 anchors (flagged approximate until the bench regenerates it).
./providers — EasyPost (wallet discounts, delivery-verified residential), USPS direct (priceType: COMMERCIAL), UPS Rating v2409 (presence-only residential indicator handled correctly; negotiated-rate ready), FedEx Rates & Transit Times (LIST+ACCOUNT). All fixture-tested; live verification lights up per-provider as credentials land in .env.
./ops — runRateBench: the empirical cheapest-finder across parcel profiles × destinations; failures are part of the output.

Status

0.1.0-alpha — engine + table fallback fully verified offline (npm test, 20 tests; npm run bench quotes the table with the current surcharge windows applied). Providers await credentials: copy .env.example → .env and follow docs/ACCOUNT-SETUP.md step by step; each filled section makes npm run bench quote that carrier live. Missing credentials never break anything — providers are excluded, the table always answers.

Consumption

commerce-manager ≥0.2.0 plugs this in via its shipping.rates seam (quote-then-choose with a tamper-proof server-side quote store):

import { RateEngine, TableRateProvider, approximateTxZoneResolver, USPS_GA_TX_TABLE }
  from '@khalidadil/shipping-manager';
import { UspsProvider } from '@khalidadil/shipping-manager/providers';

const engine = new RateEngine({
  providers: [
    new TableRateProvider({ tables: [USPS_GA_TX_TABLE], zoneResolver: approximateTxZoneResolver }),
    ...(process.env.USPS_CLIENT_ID ? [new UspsProvider({ ... })] : []),
  ],
});

// commerce-manager ShippingConfig:
shipping: {
  skeletonPriceId,
  shipFrom,
  rates: { quote: async (s) => (await engine.quote(s, 'checkout')).rates },
}

Install: npm config set @khalidadil:registry https://git.kadil.dev/api/packages/khalidadil/npm/ then npm install @khalidadil/shipping-manager.

Development Dependencies

ID	Version
tsx	^4.19.2
typescript	^5.7.3

Details

npm

2026-09-02 02:16:47 +00:00

1

alpha

28 KiB

Assets (1)

shipping-manager-0.1.0-alpha.0.tgz 28 KiB

Versions (1) View all

0.1.0-alpha.0

2026-09-02

@khalidadil/shipping-manager (0.1.0-alpha.0)

Installation

About this package

@khalidadil/shipping-manager

Status

Consumption

Dependencies