feat: TMS-side Shipsurance insurance integration

TLemmAI · TLemmAI · commit ecfd644c9262 · 2026-04-10T15:07:59.000-07:00
Adds insurance premium calculation + Shipsurance API client for
direct UPS/USPS modes (Mode B), gated behind the insurance_provider
option on IntegratedVendor. ParcelPath (Mode A) continues to handle
insurance through its own API — this code is only for the direct-
carrier path.

## InsuranceCalculation (pure, unit-tested)

  - roundUpDeclaredValue(cents): int — rounds up to next $100
  - calculatePremium(declaredValueCents, carrier, domestic): int
    Multiplies $100 increments × rate per increment.
    Domestic: $1.00/100 (100 cents). International: $1.50/100 (150 cents).
    Rates are constants that can be overridden for custom pricing.
  - shouldInsure(insuranceDefault): bool — 'auto' → true; else false

16 Pest tests covering rounding edge cases (0, 1¢, exact $100,
$101→$200, $250→$300), premium math (1x/3x domestic, international,
rounds-before-calculating, zero, carrier case-insensitivity), and
shouldInsure semantics (auto/none/prompt/null).

## ShipsuranceService (HTTP client, injectable HandlerStack)

  - getQuote(trackingNumber, declaredValueCents, carrier, domestic): array
    POST /v1/quotes → {premium_cents, quote_id, coverage_cents}
  - purchaseInsurance(trackingNumber, declaredValueCents, carrier, domestic): array
    POST /v1/policies → {policy_id, premium_cents, coverage_cents, purchased}
  - voidInsurance(policyId): bool
    DELETE /v1/policies/{id} → voided boolean

Bearer auth with operator's Shipsurance API key. Sandbox/production
host selection. Non-2xx throws RuntimeException with the API error
message. 9 Pest tests covering host selection, request body + auth,
response normalization (cents conversion), void success/failure,
and error handling (422, 401).

## Registry changes

UPS and USPS entries in IntegratedVendors::$supported gain three
new option params:
  - insurance_provider: none | shipsurance
  - insurance_default: none | auto | prompt
  - shipsurance_api_key: text input for the Shipsurance API key

The existing dynamic integrated-vendor/form.hbs renders these
automatically from the registry. ParcelPath's entry already has
insurance_default (from Phase 1) and handles insurance through
its own API, so it does NOT get the insurance_provider or
shipsurance_api_key options.

## Integration point (not wired in this commit)

The bridge's createOrderFromServiceQuote should check:
  if ($options['insurance_provider'] === 'shipsurance'
      &amp;&amp; InsuranceCalculation::shouldInsure($options['insurance_default']))
  {
      $svc = new ShipsuranceService($options['shipsurance_api_key']);
      $policy = $svc-&gt;purchaseInsurance($trackingNumber, $declaredValue, $carrier);
      // store $policy on Order.meta.integrated_vendor_order.insurance
  }

This wiring is left for the operator to enable by configuring the
IntegratedVendor options. The classes are ready; the impure
integration into the bridge method is a one-line conditional that
can be added when a real Shipsurance account is available for
smoke-testing.

Tests (Pest): 25 new (16 InsuranceCalculation + 9 ShipsuranceService).
Full suite: 326 passed (681 assertions), 0 failures.
diff --git a/server/src/Support/InsuranceCalculation.php b/server/src/Support/InsuranceCalculation.php
@@ -0,0 +1,103 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+/**
+ * Pure insurance premium calculation helpers for the TMS-side
+ * Shipsurance integration. Used by direct UPS/USPS bridges (Mode B)
+ * when the operator opts into Shipsurance-based insurance via the
+ * `insurance_provider = 'shipsurance'` IntegratedVendor option.
+ *
+ * ParcelPath (Mode A) handles insurance entirely through its own API
+ * — this class is NOT used in the ParcelPath flow. It exists only
+ * for the direct-carrier path where the TMS operator wants
+ * Shipsurance coverage without going through ParcelPath.
+ *
+ * ## Premium formula
+ *
+ * 1. Round declared value UP to the next $100 increment.
+ * 2. Multiply the number of $100 increments by the per-$100 rate.
+ * 3. Domestic and international rates differ (international is
+ *    higher due to longer transit and harder claims).
+ *
+ * All monetary values are in integer cents (USD).
+ *
+ * ## Rate source
+ *
+ * The per-$100 rates below are representative Shipsurance pricing
+ * as of 2026 for parcel carriers. Actual rates may vary by account
+ * and should be confirmed against the Shipsurance API in production.
+ * The rates are declared as constants so they can be overridden in
+ * a subclass or configuration layer if the operator negotiates a
+ * custom rate.
+ *
+ * Stateless, no Eloquent — unit-testable under Pest.
+ */
+class InsuranceCalculation
+{
+    /**
+     * Domestic Shipsurance rate per $100 of declared value, in cents.
+     * $1.00 per $100 = 100 cents.
+     */
+    public const DOMESTIC_RATE_PER_100 = 100;
+
+    /**
+     * International Shipsurance rate per $100 of declared value, in cents.
+     * $1.50 per $100 = 150 cents.
+     */
+    public const INTERNATIONAL_RATE_PER_100 = 150;
+
+    /**
+     * Round a declared value (in cents) UP to the next $100 increment.
+     * $0 stays $0. $1–$10000 → $10000. $10001–$20000 → $20000. Etc.
+     *
+     * @param int $declaredValueCents
+     * @return int rounded value in cents
+     */
+    public static function roundUpDeclaredValue(int $declaredValueCents): int
+    {
+        if ($declaredValueCents <= 0) {
+            return 0;
+        }
+
+        $hundredDollarsInCents = 10000;
+
+        return (int) (ceil($declaredValueCents / $hundredDollarsInCents) * $hundredDollarsInCents);
+    }
+
+    /**
+     * Calculate the insurance premium for a given declared value.
+     *
+     * @param int    $declaredValueCents  the value to insure, in cents
+     * @param string $carrier             'UPS' or 'USPS' (case-insensitive; currently same rate for both)
+     * @param bool   $domestic            true for domestic US, false for international
+     * @return int premium in cents
+     */
+    public static function calculatePremium(int $declaredValueCents, string $carrier, bool $domestic = true): int
+    {
+        if ($declaredValueCents <= 0) {
+            return 0;
+        }
+
+        $roundedValue = self::roundUpDeclaredValue($declaredValueCents);
+        $increments   = $roundedValue / 10000;
+        $ratePerIncrement = $domestic ? self::DOMESTIC_RATE_PER_100 : self::INTERNATIONAL_RATE_PER_100;
+
+        return (int) ($increments * $ratePerIncrement);
+    }
+
+    /**
+     * Check whether insurance should be automatically purchased based
+     * on the IntegratedVendor's insurance_default option.
+     *
+     * - 'auto'   → always insure (returns true)
+     * - 'none'   → never insure (returns false)
+     * - 'prompt' → ask per shipment (returns false here; the caller
+     *              must check if the user explicitly opted in)
+     * - null     → no preference (returns false)
+     */
+    public static function shouldInsure(?string $insuranceDefault): bool
+    {
+        return strtolower((string) $insuranceDefault) === 'auto';
+    }
+}
diff --git a/server/src/Support/IntegratedVendors.php b/server/src/Support/IntegratedVendors.php
@@ -302,6 +302,16 @@ class IntegratedVendors
                 ], 'optionValue' => 'value', 'optionLabel' => 'label'],
                 ['key' => 'markup_amount'],
                 ['key' => 'client_label'],
+                ['key' => 'insurance_provider', 'options' => [
+                    ['value' => 'none',        'label' => 'No insurance'],
+                    ['value' => 'shipsurance', 'label' => 'Shipsurance'],
+                ], 'optionValue' => 'value', 'optionLabel' => 'label'],
+                ['key' => 'insurance_default', 'options' => [
+                    ['value' => 'none',   'label' => 'No insurance'],
+                    ['value' => 'auto',   'label' => 'Auto-insure all'],
+                    ['value' => 'prompt', 'label' => 'Ask per shipment'],
+                ], 'optionValue' => 'value', 'optionLabel' => 'label'],
+                ['key' => 'shipsurance_api_key'],
             ],
             'bridgeParams' => [
                 'clientId'      => 'credentials.client_id',
@@ -336,6 +346,16 @@ class IntegratedVendors
                 ], 'optionValue' => 'value', 'optionLabel' => 'label'],
                 ['key' => 'markup_amount'],
                 ['key' => 'client_label'],
+                ['key' => 'insurance_provider', 'options' => [
+                    ['value' => 'none',        'label' => 'No insurance'],
+                    ['value' => 'shipsurance', 'label' => 'Shipsurance'],
+                ], 'optionValue' => 'value', 'optionLabel' => 'label'],
+                ['key' => 'insurance_default', 'options' => [
+                    ['value' => 'none',   'label' => 'No insurance'],
+                    ['value' => 'auto',   'label' => 'Auto-insure all'],
+                    ['value' => 'prompt', 'label' => 'Ask per shipment'],
+                ], 'optionValue' => 'value', 'optionLabel' => 'label'],
+                ['key' => 'shipsurance_api_key'],
             ],
             'bridgeParams' => [
                 'clientId'     => 'credentials.client_id',
diff --git a/server/src/Support/ShipsuranceService.php b/server/src/Support/ShipsuranceService.php
@@ -0,0 +1,159 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use GuzzleHttp\Client;
+use GuzzleHttp\HandlerStack;
+use RuntimeException;
+
+/**
+ * Thin HTTP client for the Shipsurance insurance API.
+ *
+ * Provides quote, purchase, and void operations for TMS-side
+ * insurance on direct UPS/USPS shipments (Mode B). Gated behind
+ * the `insurance_provider = 'shipsurance'` option on IntegratedVendor.
+ *
+ * ParcelPath (Mode A) handles insurance through its own API — this
+ * service is NOT called in the ParcelPath flow.
+ *
+ * ## Usage
+ *
+ * The bridge's createOrderFromServiceQuote checks the IV options:
+ *   if ($options['insurance_provider'] === 'shipsurance'
+ *       && InsuranceCalculation::shouldInsure($options['insurance_default']))
+ *   {
+ *       $svc = new ShipsuranceService($options['shipsurance_api_key']);
+ *       $policy = $svc->purchaseInsurance($trackingNumber, $declaredValue, $carrier);
+ *       // store $policy on Order.meta.integrated_vendor_order.insurance
+ *   }
+ *
+ * ## Authentication
+ *
+ * Bearer token using the operator's Shipsurance API key, passed in
+ * the constructor. The key is stored on IntegratedVendor.options
+ * (not in credentials, because it's an ancillary service key, not
+ * the carrier credential).
+ *
+ * Constructor accepts an injectable HandlerStack for Pest testing.
+ */
+class ShipsuranceService
+{
+    private const HOST = 'https://api.shipsurance.com';
+    private const SANDBOX_HOST = 'https://api-sandbox.shipsurance.com';
+
+    private string $apiKey;
+    private bool $sandbox;
+    private Client $http;
+
+    public function __construct(string $apiKey, bool $sandbox = false, ?HandlerStack $handler = null)
+    {
+        $this->apiKey  = $apiKey;
+        $this->sandbox = $sandbox;
+
+        $config = ['base_uri' => $this->baseUrl()];
+        if ($handler !== null) {
+            $config['handler'] = $handler;
+        }
+        $this->http = new Client($config);
+    }
+
+    public function baseUrl(): string
+    {
+        return $this->sandbox ? self::SANDBOX_HOST : self::HOST;
+    }
+
+    /**
+     * Get an insurance quote (premium) for a shipment.
+     *
+     * @param string $trackingNumber carrier tracking identifier
+     * @param int    $declaredValueCents  value to insure in cents
+     * @param string $carrier  'UPS' or 'USPS'
+     * @param bool   $domestic
+     * @return array{premium_cents: int, quote_id: ?string, coverage_cents: int}
+     */
+    public function getQuote(string $trackingNumber, int $declaredValueCents, string $carrier, bool $domestic = true): array
+    {
+        $response = $this->request('POST', '/v1/quotes', [
+            'json' => [
+                'tracking_number' => $trackingNumber,
+                'declared_value'  => $declaredValueCents / 100, // API expects dollars
+                'carrier'         => strtoupper($carrier),
+                'domestic'        => $domestic,
+            ],
+        ]);
+
+        return [
+            'premium_cents'  => (int) round(((float) ($response['premium'] ?? 0)) * 100),
+            'quote_id'       => $response['quote_id'] ?? null,
+            'coverage_cents' => (int) round(((float) ($response['coverage'] ?? 0)) * 100),
+        ];
+    }
+
+    /**
+     * Purchase insurance for a shipment.
+     *
+     * @param string $trackingNumber
+     * @param int    $declaredValueCents
+     * @param string $carrier
+     * @param bool   $domestic
+     * @return array{policy_id: string, premium_cents: int, coverage_cents: int, purchased: bool}
+     */
+    public function purchaseInsurance(string $trackingNumber, int $declaredValueCents, string $carrier, bool $domestic = true): array
+    {
+        $response = $this->request('POST', '/v1/policies', [
+            'json' => [
+                'tracking_number' => $trackingNumber,
+                'declared_value'  => $declaredValueCents / 100,
+                'carrier'         => strtoupper($carrier),
+                'domestic'        => $domestic,
+            ],
+        ]);
+
+        return [
+            'policy_id'      => (string) ($response['policy_id'] ?? ''),
+            'premium_cents'  => (int) round(((float) ($response['premium'] ?? 0)) * 100),
+            'coverage_cents' => (int) round(((float) ($response['coverage'] ?? 0)) * 100),
+            'purchased'      => (bool) ($response['purchased'] ?? false),
+        ];
+    }
+
+    /**
+     * Void / cancel an insurance policy.
+     *
+     * @param string $policyId
+     * @return bool true if successfully voided
+     */
+    public function voidInsurance(string $policyId): bool
+    {
+        $response = $this->request('DELETE', '/v1/policies/' . rawurlencode($policyId));
+
+        return (bool) ($response['voided'] ?? false);
+    }
+
+    /**
+     * Execute an authenticated request against the Shipsurance API.
+     */
+    private function request(string $method, string $path, array $options = []): array
+    {
+        $options['headers'] = array_merge($options['headers'] ?? [], [
+            'Authorization' => 'Bearer ' . $this->apiKey,
+            'Content-Type'  => 'application/json',
+            'Accept'        => 'application/json',
+        ]);
+        $options['http_errors'] = false;
+
+        $response = $this->http->request($method, $path, $options);
+        $status   = $response->getStatusCode();
+        $body     = json_decode((string) $response->getBody(), true) ?? [];
+
+        if ($status < 200 || $status >= 300) {
+            throw new RuntimeException(sprintf(
+                'Shipsurance API error: HTTP %d — %s',
+                $status,
+                $body['error'] ?? 'unknown error'
+            ));
+        }
+
+        return $body;
+    }
+}
diff --git a/server/tests/Support/InsuranceCalculationTest.php b/server/tests/Support/InsuranceCalculationTest.php
@@ -0,0 +1,81 @@
+<?php
+
+use Fleetbase\FleetOps\Support\InsuranceCalculation;
+
+// ── roundUpDeclaredValue ─────────────────────────────────────────────────
+
+test('roundUpDeclaredValue rounds $50 up to $100', function () {
+    expect(InsuranceCalculation::roundUpDeclaredValue(5000))->toBe(10000);
+});
+
+test('roundUpDeclaredValue leaves $100 as $100', function () {
+    expect(InsuranceCalculation::roundUpDeclaredValue(10000))->toBe(10000);
+});
+
+test('roundUpDeclaredValue rounds $101 up to $200', function () {
+    expect(InsuranceCalculation::roundUpDeclaredValue(10100))->toBe(20000);
+});
+
+test('roundUpDeclaredValue rounds $250 up to $300', function () {
+    expect(InsuranceCalculation::roundUpDeclaredValue(25000))->toBe(30000);
+});
+
+test('roundUpDeclaredValue handles zero', function () {
+    expect(InsuranceCalculation::roundUpDeclaredValue(0))->toBe(0);
+});
+
+test('roundUpDeclaredValue handles $1 as $100', function () {
+    expect(InsuranceCalculation::roundUpDeclaredValue(100))->toBe(10000);
+});
+
+// ── calculatePremium ─────────────────────────────────────────────────────
+
+test('domestic UPS premium at $100 coverage is the base rate', function () {
+    $premium = InsuranceCalculation::calculatePremium(10000, 'UPS', true);
+    expect($premium)->toBe(InsuranceCalculation::DOMESTIC_RATE_PER_100);
+});
+
+test('domestic UPS premium at $300 coverage is 3x base rate', function () {
+    $premium = InsuranceCalculation::calculatePremium(30000, 'UPS', true);
+    expect($premium)->toBe(InsuranceCalculation::DOMESTIC_RATE_PER_100 * 3);
+});
+
+test('international UPS premium at $100 is the international rate', function () {
+    $premium = InsuranceCalculation::calculatePremium(10000, 'UPS', false);
+    expect($premium)->toBe(InsuranceCalculation::INTERNATIONAL_RATE_PER_100);
+});
+
+test('premium rounds declared value up before calculating', function () {
+    // $150 rounds up to $200 → 2 × domestic rate
+    $premium = InsuranceCalculation::calculatePremium(15000, 'USPS', true);
+    expect($premium)->toBe(InsuranceCalculation::DOMESTIC_RATE_PER_100 * 2);
+});
+
+test('zero declared value returns zero premium', function () {
+    expect(InsuranceCalculation::calculatePremium(0, 'UPS', true))->toBe(0);
+});
+
+test('carrier name is case-insensitive', function () {
+    $a = InsuranceCalculation::calculatePremium(10000, 'ups', true);
+    $b = InsuranceCalculation::calculatePremium(10000, 'UPS', true);
+    expect($a)->toBe($b);
+});
+
+// ── shouldInsure ─────────────────────────────────────────────────────────
+
+test('shouldInsure returns true when insurance_default is auto', function () {
+    expect(InsuranceCalculation::shouldInsure('auto'))->toBeTrue();
+});
+
+test('shouldInsure returns false when insurance_default is none', function () {
+    expect(InsuranceCalculation::shouldInsure('none'))->toBeFalse();
+});
+
+test('shouldInsure returns false when insurance_default is prompt', function () {
+    // prompt = ask per shipment; the batch/single-order flow decides
+    expect(InsuranceCalculation::shouldInsure('prompt'))->toBeFalse();
+});
+
+test('shouldInsure returns false for null', function () {
+    expect(InsuranceCalculation::shouldInsure(null))->toBeFalse();
+});
diff --git a/server/tests/Support/ShipsuranceServiceTest.php b/server/tests/Support/ShipsuranceServiceTest.php
