Aviation & Transport Compliance

import ComplianceGrid from "@compliancegrid/sdk";

const cg = new ComplianceGrid({
  apiKey: process.env.COMPLIANCEGRID_API_KEY,
});

// Look up aircraft by N-number (tail number)
const aircraft = await cg.aviation.faaAircraftSearch({
  nNumber: "N12345",
});

const reg = aircraft.data.results[0];
console.log("N-Number:", reg.nNumber);
console.log("Serial:", reg.serialNumber);
console.log("Manufacturer:", reg.manufacturer);
console.log("Model:", reg.model);
console.log("Year:", reg.yearManufactured);
console.log("Registrant:", reg.registrantName);
console.log("Type:", reg.registrantType); // "Corporation", "Individual", etc.
console.log("Airworthiness:", reg.airworthinessCertificate);
console.log("Status:", reg.status); // "Valid", "Expired", "Revoked"
console.log("Expiration:", reg.expirationDate);

// Search by registrant name
const fleet = await cg.aviation.faaAircraftSearch({
  registrantName: "Delta Air Lines",
});
console.log(`Found ${fleet.data.totalResults} registered aircraft`);

// Look up motor carrier by USDOT number
const carrier = await cg.aviation.fmcsaCarrierSearch({
  dotNumber: "1234567",
});

const c = carrier.data;
console.log("Carrier:", c.legalName);
console.log("DOT#:", c.dotNumber);
console.log("MC#:", c.mcNumber);
console.log("Safety Rating:", c.safetyRating); // "Satisfactory", "Conditional", "Unsatisfactory"
console.log("Operating Status:", c.operatingStatus); // "AUTHORIZED"
console.log("Insurance Status:", c.insuranceStatus);
console.log("Hazmat:", c.hmFlag ? "Authorized" : "Not authorized");
console.log("Vehicles:", c.totalVehicles);
console.log("Drivers:", c.totalDrivers);

// Check out-of-service rates
console.log("Vehicle OOS Rate:", c.vehicleOosRate, "%");
console.log("Driver OOS Rate:", c.driverOosRate, "%");

// Flag carriers with poor safety records
if (c.safetyRating === "Unsatisfactory" || c.vehicleOosRate > 30) {
  console.warn("HIGH RISK — carrier has poor safety record");
}

// Search by name
const carriers = await cg.aviation.fmcsaCarrierSearch({
  companyName: "XPO Logistics",
});

// Screen the aircraft owner / carrier against federal watchlists
const screening = await cg.compliance.screenParties([
  {
    name: reg.registrantName, // From FAA lookup
    country: "US",
    type: "COUNTERPARTY",
  },
]);

if (screening.data.overallResult === "HIT") {
  console.error("SANCTIONS HIT on aircraft registrant");
  console.error("Do NOT proceed with transaction");
} else {
  console.log("Registrant is CLEAR on all federal watchlists");
}

interface CarrierVerification {
  carrier: string;
  dotNumber: string;
  safetyRating: string;
  operatingStatus: string;
  sanctionsClear: boolean;
  riskLevel: "LOW" | "MEDIUM" | "HIGH" | "BLOCKED";
  issues: string[];
}

async function verifyCarrier(dotNumber: string): Promise<CarrierVerification> {
  const result: CarrierVerification = {
    carrier: "",
    dotNumber,
    safetyRating: "UNKNOWN",
    operatingStatus: "UNKNOWN",
    sanctionsClear: true,
    riskLevel: "LOW",
    issues: [],
  };

  // Step 1: FMCSA lookup
  const carrier = await cg.aviation.fmcsaCarrierSearch({ dotNumber });
  const c = carrier.data;
  result.carrier = c.legalName;
  result.safetyRating = c.safetyRating;
  result.operatingStatus = c.operatingStatus;

  // Check safety flags
  if (c.safetyRating === "Unsatisfactory") {
    result.riskLevel = "HIGH";
    result.issues.push("Unsatisfactory safety rating");
  } else if (c.safetyRating === "Conditional") {
    result.riskLevel = "MEDIUM";
    result.issues.push("Conditional safety rating");
  }

  if (c.operatingStatus !== "AUTHORIZED") {
    result.riskLevel = "HIGH";
    result.issues.push(`Operating status: ${c.operatingStatus}`);
  }

  if (c.vehicleOosRate > 30) {
    result.issues.push(`High vehicle OOS rate: ${c.vehicleOosRate}%`);
    if (result.riskLevel === "LOW") result.riskLevel = "MEDIUM";
  }

  // Step 2: Sanctions screening
  const screening = await cg.compliance.screenParties([
    { name: c.legalName, country: "US", type: "COUNTERPARTY" },
  ]);

  if (screening.data.overallResult === "HIT") {
    result.sanctionsClear = false;
    result.riskLevel = "BLOCKED";
    result.issues.push("Federal watchlist match found");
  }

  return result;
}

// Usage
const verification = await verifyCarrier("1234567");
console.log(`Carrier: ${verification.carrier}`);
console.log(`Risk: ${verification.riskLevel}`);
if (verification.issues.length > 0) {
  console.log("Issues:", verification.issues.join(", "));
}