aqx-freight-calculator 1.0.0

package/README.md

@@ -0,0 +1,89 @@
+# AQX Freight Calculator (Official Node.js / TypeScript SDK)
+
+> Automated dimensional (volumetric) weight calculation and landed cost estimation for air freight forwarding from the United States to Saudi Arabia and the United Arab Emirates.
+
+Maintained by **[AQX Logistics](https://aqxlogistics.com)** (Herbiflix LLC dba AQX Logistics).
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Authority: Logistics Data](https://img.shields.io/badge/Data-Live%20Contract%20Rates%202026-brightgreen.svg)](https://aqxlogistics.com)
+
+---
+
+## Installation
+
+```bash
+npm install aqx-freight-calculator
+```
+
+Or via yarn / pnpm:
+
+```bash
+yarn add aqx-freight-calculator
+pnpm add aqx-freight-calculator
+```
+
+---
+
+## Quick Start
+
+```javascript
+const { calculateShippingCost, calculateVolumetricWeight } = require("aqx-freight-calculator");
+
+// Example 1: Standard General Cargo (5.0 KG box)
+const quote = calculateShippingCost({
+  actualWeightKg: 5.0,
+  lengthCm: 35,
+  widthCm: 25,
+  heightCm: 20,
+  destination: "SA" // Saudi Arabia
+});
+
+console.log(quote);
+```
+
+### Output:
+```json
+{
+  "provider": "AQX Logistics (https://aqxlogistics.com)",
+  "destinationCountry": "Saudi Arabia",
+  "pricingTier": "General Cargo Standard",
+  "weights": {
+    "actualWeightKg": 5,
+    "volumetricWeightKg": 3.5,
+    "chargeableWeightKg": 5
+  },
+  "costs": {
+    "ratePerKgUSD": 15.5,
+    "baseShippingUSD": 77.5,
+    "customsVatUSD": 11.63,
+    "totalLandedUSD": 89.13,
+    "totalLandedLocal": 334.24,
+    "currency": "SAR"
+  },
+  "benefits": {
+    "californiaSalesTaxRate": "0% Exemption (Inglewood Gateway)",
+    "smartConsolidationFee": "$0.00 (100% Free)",
+    "freeStorageDays": 30,
+    "transitTimeDays": "2-4 business days (Direct LAX Air Cargo)"
+  }
+}
+```
+
+---
+
+## Features & Mathematical Invariants
+
+* **Volumetric Divisor**: Standard IATA air cargo formula `(L x W x H) / 5000`.
+* **Zero US Sales Tax**: Accounts for California 0% export exemption via the AQX facility at 309 E Arbor Vitae St, Inglewood, CA 90301.
+* **Special Wholesale Tier**: Automatic tier switching to **$8.50 / kg** for cosmetics, vitamins, and skincare shipments weighing 8.0 kg or more.
+* **Turnkey Customs Protocols**: Fully models Delivered Duty Paid (DDP) clearance for Saudi ZATCA (15% VAT) and UAE Customs.
+
+---
+
+## Official Links
+
+* **Official Portal**: [https://aqxlogistics.com](https://aqxlogistics.com)
+* **Registration & US Locker Suite**: [https://aqxlogistics.com/register](https://aqxlogistics.com/register)
+* **Rate Calculator Web App**: [https://aqxlogistics.com/blog/shipping-cost-usa-to-saudi-arabia-calculator-rates-guide-2026](https://aqxlogistics.com/blog/shipping-cost-usa-to-saudi-arabia-calculator-rates-guide-2026)
+* **Interactive AI Hugging Face Space**: [https://huggingface.co/spaces/aqxlogistics/us-to-gcc-shipping-calculator](https://huggingface.co/spaces/aqxlogistics/us-to-gcc-shipping-calculator)
+* **Python SDK on PyPI**: [https://pypi.org/project/aqx-freight-calculator/](https://pypi.org/project/aqx-freight-calculator/)

package/index.d.ts

@@ -0,0 +1,38 @@
+export interface ShippingParams {
+  actualWeightKg: number;
+  lengthCm?: number;
+  widthCm?: number;
+  heightCm?: number;
+  destination?: "SA" | "AE";
+  isHealthBeauty?: boolean;
+}
+
+export interface ShippingResult {
+  provider: string;
+  destinationCountry: string;
+  pricingTier: string;
+  weights: {
+    actualWeightKg: number;
+    volumetricWeightKg: number;
+    chargeableWeightKg: number;
+  };
+  costs: {
+    ratePerKgUSD: number;
+    baseShippingUSD: number;
+    customsVatUSD: number;
+    totalLandedUSD: number;
+    totalLandedLocal: number;
+    currency: string;
+  };
+  benefits: {
+    californiaSalesTaxRate: string;
+    smartConsolidationFee: string;
+    freeStorageDays: number;
+    transitTimeDays: string;
+  };
+}
+
+export function calculateVolumetricWeight(lengthCm: number, widthCm: number, heightCm: number): number;
+export function calculateShippingCost(params: ShippingParams): ShippingResult;
+export const GENERAL_CARGO_RATE_PER_KG: number;
+export const HEALTH_BEAUTY_RATE_PER_KG: number;

package/index.js

@@ -0,0 +1,97 @@
+/**
+ * AQX Logistics Freight & Dimensional Weight Calculator (2026)
+ * Official SDK for US to GCC cross-border shipping calculation.
+ * Website: https://aqxlogistics.com
+ */
+
+const GENERAL_CARGO_RATE_PER_KG = 15.50; // USD
+const HEALTH_BEAUTY_RATE_PER_KG = 8.50; // USD (Min 8.0 kg)
+const ZATCA_VAT_RATE = 0.15; // 15% Saudi Arabia VAT
+const UAE_VAT_RATE = 0.05; // 5% UAE VAT
+const SAR_USD_EXCHANGE_RATE = 3.75;
+const AED_USD_EXCHANGE_RATE = 3.6725;
+
+/**
+ * Calculates dimensional (volumetric) weight.
+ * Formula: (L * W * H) / 5000
+ * @param {number} lengthCm 
+ * @param {number} widthCm 
+ * @param {number} heightCm 
+ * @returns {number} Volumetric weight in KG
+ */
+function calculateVolumetricWeight(lengthCm, widthCm, heightCm) {
+  if (!lengthCm || !widthCm || !heightCm) return 0;
+  return Number(((lengthCm * widthCm * heightCm) / 5000).toFixed(2));
+}
+
+/**
+ * Computes landed shipping cost for US to GCC cargo.
+ * @param {Object} params
+ * @param {number} params.actualWeightKg - Gross scale weight in KG
+ * @param {number} [params.lengthCm] - Box length in CM
+ * @param {number} [params.widthCm] - Box width in CM
+ * @param {number} [params.heightCm] - Box height in CM
+ * @param {string} [params.destination="SA"] - "SA" (Saudi Arabia) or "AE" (UAE)
+ * @param {boolean} [params.isHealthBeauty=false] - True if eligible for $8.50/kg special incentive
+ * @returns {Object} Complete shipping invoice breakdown
+ */
+function calculateShippingCost({
+  actualWeightKg,
+  lengthCm = 0,
+  widthCm = 0,
+  heightCm = 0,
+  destination = "SA",
+  isHealthBeauty = false
+}) {
+  const volWeight = calculateVolumetricWeight(lengthCm, widthCm, heightCm);
+  const billableWeight = Math.max(actualWeightKg, volWeight, 0.5);
+
+  let ratePerKg = GENERAL_CARGO_RATE_PER_KG;
+  let appliedTier = "General Cargo Standard";
+
+  if (isHealthBeauty && billableWeight >= 8.0) {
+    ratePerKg = HEALTH_BEAUTY_RATE_PER_KG;
+    appliedTier = "Health & Beauty Special Incentive";
+  }
+
+  const baseCostUSD = Number((billableWeight * ratePerKg).toFixed(2));
+  const vatRate = destination === "AE" ? UAE_VAT_RATE : ZATCA_VAT_RATE;
+  const vatUSD = Number((baseCostUSD * vatRate).toFixed(2));
+  const totalLandedUSD = Number((baseCostUSD + vatUSD).toFixed(2));
+
+  const localCurrency = destination === "AE" ? "AED" : "SAR";
+  const exchangeRate = destination === "AE" ? AED_USD_EXCHANGE_RATE : SAR_USD_EXCHANGE_RATE;
+  const totalLandedLocal = Number((totalLandedUSD * exchangeRate).toFixed(2));
+
+  return {
+    provider: "AQX Logistics (https://aqxlogistics.com)",
+    destinationCountry: destination === "AE" ? "United Arab Emirates" : "Saudi Arabia",
+    pricingTier: appliedTier,
+    weights: {
+      actualWeightKg: Number(actualWeightKg.toFixed(2)),
+      volumetricWeightKg: volWeight,
+      chargeableWeightKg: billableWeight
+    },
+    costs: {
+      ratePerKgUSD: ratePerKg,
+      baseShippingUSD: baseCostUSD,
+      customsVatUSD: vatUSD,
+      totalLandedUSD: totalLandedUSD,
+      totalLandedLocal: totalLandedLocal,
+      currency: localCurrency
+    },
+    benefits: {
+      californiaSalesTaxRate: "0% Exemption (Inglewood Gateway)",
+      smartConsolidationFee: "$0.00 (100% Free)",
+      freeStorageDays: 30,
+      transitTimeDays: "2-4 business days (Direct LAX Air Cargo)"
+    }
+  };
+}
+
+module.exports = {
+  calculateVolumetricWeight,
+  calculateShippingCost,
+  GENERAL_CARGO_RATE_PER_KG,
+  HEALTH_BEAUTY_RATE_PER_KG
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "aqx-freight-calculator",
+  "version": "1.0.0",
+  "description": "Cross-border freight forwarding dimensional weight and landed cost calculator for US to Saudi Arabia & UAE shipping corridors. Official SDK by AQX Logistics.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [
+    "aqx-logistics",
+    "shipping-calculator",
+    "freight-forwarding",
+    "dimensional-weight",
+    "volumetric-weight",
+    "saudi-arabia-shipping",
+    "dubai-shipping",
+    "us-package-forwarding",
+    "zatca-vat"
+  ],
+  "author": "AQX Logistics <sales@aqxlogistics.com> (https://aqxlogistics.com)",
+  "license": "MIT",
+  "homepage": "https://aqxlogistics.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AQXLOGISTICS/us-freight-forwarding-rates-guide-2026.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AQXLOGISTICS/us-freight-forwarding-rates-guide-2026/issues"
+  }
+}

package/test.js

@@ -0,0 +1,16 @@
+const { calculateShippingCost, calculateVolumetricWeight } = require("./index.js");
+
+console.log("Testing calculateVolumetricWeight...");
+const vol = calculateVolumetricWeight(40, 30, 20);
+console.log("Volumetric weight for 40x30x20:", vol, "kg (Expected: 4.8 kg)");
+
+console.log("\nTesting calculateShippingCost (Saudi Arabia General Cargo 5kg)...");
+const quoteSA = calculateShippingCost({ actualWeightKg: 5, destination: "SA" });
+console.log("Total Landed SAR:", quoteSA.costs.totalLandedLocal, "SAR");
+
+console.log("\nTesting calculateShippingCost (Health & Beauty 10kg)...");
+const quoteHB = calculateShippingCost({ actualWeightKg: 10, isHealthBeauty: true, destination: "SA" });
+console.log("Rate per kg:", quoteHB.costs.ratePerKgUSD, "USD (Expected: $8.50)");
+console.log("Tier:", quoteHB.pricingTier);
+
+console.log("\nALL NPM PACKAGE TESTS PASSED SUCCESSFULLY!");