{
  "schema": "leumas.docs.page/1",
  "id": "adapter:domain/shipping-calculator",
  "slug": "adapters/domain/shipping-calculator",
  "kind": "capabilities",
  "bucket": "package",
  "title": "shipping-calculator",
  "name": "Shipping Calculator",
  "eyebrow": null,
  "chip": null,
  "summary": "Shipping, freight and landed-cost calculator for e-commerce, logistics and fulfillment. dimWeight computes dimensional (volumetric) weight from length x width x height / divisor and returns the...",
  "keywords": [
    "shipping-calculator",
    "freight",
    "landed-cost",
    "calculator",
    "logistics",
    "shipping calculator api",
    "how to use shipping calculator",
    "fulfillment"
  ],
  "audience": "both",
  "funnel": {
    "product": null,
    "cta": null
  },
  "body": "# shipping-calculator\n\n**Shipping / freight / landed-cost microservice** for e-commerce, logistics and fulfillment. Pure,\ndeterministic math — no external carrier API. Compute dimensional weight, look up zone/weight-break\nrates, roll up full landed cost (duty + tax), map distance to a zone, compare carrier quotes and drive\nfree-shipping upsell messaging.\n\nEvery tool runs fully **offline**. The one analytical tool (`compareCarriers`) also wires an optional\nLLM path that adds a plain-English recommendation and silently falls back — that result carries\n`{ mode: 'heuristic' | 'llm' }`.\n\n## Tools\n\n| Tool | Input | What it does |\n|---|---|---|\n| `dimWeight` | `l`, `w`, `h`, `divisor?`, `weight?` | Volumetric weight = l·w·h / divisor; returns chargeable = max(actual, dim). Unit-aware (cm→5000, in→139). |\n| `rate` | `zone`, `weight`, `table` | Looks up price from a zone × weight-break rate table with per-kg overflow beyond the top break. |\n| `landedCost` | `item`, `ship`, `dutyPct`, `taxPct` | Sums item + shipping + duty + tax into total landed cost with a full breakdown. |\n| `zoneFromDistance` | `distance` | Maps a shipping distance (km/mi) to a zone band 1–8. |\n| `compareCarriers` | `carriers` | Ranks quotes by price + delivery days; returns cheapest, fastest, best value + recommendation. |\n| `freeShippingThreshold` | `cartTotal`, `threshold` | How much more to unlock free shipping, progress % and incentive copy. |\n\n## Usage\n\n```js\nimport pack from './index.js';\n\npack.adapters.dimWeight({ l: 40, w: 30, h: 20, weight: 3, options: { unit: 'cm' } });\n// → chargeableWeight = max(3, 24000/5000 = 4.8) = 4.8, billedBy: 'dimensional'\n\npack.adapters.rate({\n  zone: 3, weight: 2.5,\n  table: [{ maxWeight: 1, rates: { 3: 8 } }, { maxWeight: 5, rates: { 3: 14 } }],\n});\n\npack.adapters.landedCost({ item: 100, ship: 20, dutyPct: 5, taxPct: 8 });\n\nawait pack.adapters.compareCarriers({ carriers: [{ name: 'UPS', price: 14, days: 3 }, { name: 'USPS', price: 9, days: 6 }] });\n```\n\nEach tool takes ONE args object (maps 1:1 to an HTTP POST body). Invalid input throws `TypeError`;\nmissing zone rates throw a 404-tagged error.\n\n## Options\n\n`options`: `unit` (cm/in for `dimWeight`; km/mi for `zoneFromDistance`), `currency`, `precision`,\n`dutyOnShipping` (charge duty on item+ship), `taxBase` (`landed` vs `item`), `narrate` (LLM path for\n`compareCarriers`).\n\n## DRY boundaries\n\n- General currency/percent math lives in `numbers` / `finance` / `tax`. This pack owns the **shipping\n  domain model** (dim weight, zone rate tables, landed cost, carrier compare). The duty/tax percentage\n  math is reused inline to keep the pack self-contained.\n- No cross-pack imports except `../_shared/llm.js`.\n",
  "source": {
    "path": "shared/engines/adapters/domain/shipping-calculator/README.md",
    "blobSha": "",
    "commit": "",
    "committedAt": "",
    "provenance": "no-git",
    "bytes": 2964,
    "hash": "5e64770677551ae15392b066dbb4f1a50a9e8457"
  },
  "urls": {
    "html": "/p/adapters/domain/shipping-calculator",
    "json": "/docs/adapters/domain/shipping-calculator.json",
    "md": "/docs/adapters/domain/shipping-calculator.md"
  },
  "links": {
    "composes": [],
    "usedBy": [],
    "product": [],
    "howTo": [],
    "skills": []
  }
}