Firearms License Verification

const API = "https://api.compliancegrid.ai";
const headers = { "x-api-key": process.env.CG_API_KEY! };
const get = (path: string) => fetch(API + path, { headers }).then((r) => r.json());

// Search FFLs by state, city and license type (also: name, zip)
const ffls = await get("/v1/firearms/ffl/search?state=TX&city=Dallas&type=01&limit=10");

console.log("Found " + ffls.totalResults + " dealers in Dallas, TX");
for (const ffl of ffls.results) {
  console.log("  " + (ffl.businessName || ffl.licenseName));   // businessName is often empty: licenseName is the licensee
  console.log("    License: " + ffl.fflNumber);
  console.log("    Type: " + ffl.licenseType + " - " + ffl.licenseTypeName);
  console.log("    Premises: " + ffl.premiseStreet + ", " + ffl.premiseCity + " " + ffl.premiseState + " " + ffl.premiseZip);
}

// Search by business or licensee name (matches either)
const byName = await get("/v1/firearms/ffl/search?name=Champion&state=TX");
console.log(byName.totalResults + " licensees match");

// Verify a specific FFL number against the ATF listing
const fflNumber = ffls.results[0].fflNumber;   // for example 5-75-113-01-7A-18504
const verification = await get("/v1/firearms/ffl/verify/" + fflNumber);

// valid is true only when the number is well formed AND on the listing; record is the licensee
console.log("On the ATF listing:", verification.valid);
if (verification.valid) {
  const ffl = verification.record;
  console.log("Licensee:", ffl.businessName || ffl.licenseName);
  console.log("Type:", ffl.licenseType, ffl.licenseTypeName);
  console.log("Region:", verification.parsed.regionName);
  console.log("Expiration cycle:", verification.parsed.expirationCycle, "month:", verification.parsed.expirationMonth);

  // The listing carries no status or expiry date, only licensees that are currently listed
  const isDealer = ["01", "02"].includes(ffl.licenseType);
  console.log(isDealer ? "License type allows retail dealing" : "License type does not allow retail dealing");
} else {
  console.error("Not on the ATF listing: do not treat this as a licensed dealer");
}

// Parse a number without looking it up (format check only)
const parsed = await get("/v1/firearms/ffl/parse/" + fflNumber);
console.log(parsed.valid, parsed.regionName, parsed.licenseTypeName);

// Screen the FFL holder against the U.S. restricted-party lists
const holder = verification.record.businessName || verification.record.licenseName;
const screening = await fetch(API + "/v1/compliance/restricted-party-screening", {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ parties: [{ name: holder, country: "US" }] }),
}).then((r) => r.json());

// overallResult is CLEAR or POTENTIAL_MATCH; a potential match needs human review
if (screening.data.overallResult === "POTENTIAL_MATCH") {
  console.warn("Possible list match: review before proceeding");
  for (const match of screening.data.results[0].matches.slice(0, 3)) {
    console.log("  " + match.listName + ": " + match.matchedName + " (score " + match.matchScore + ")");
  }
} else {
  console.log("Watchlist screening: no match");
}

async function verifyFFL(fflNumber: string) {
  // Step 1: is the number on the ATF listing?
  const v = await get("/v1/firearms/ffl/verify/" + fflNumber);
  if (!v.valid) {
    return { valid: false, reason: "Not on the ATF listing (or not a valid FFL number)" };
  }
  const ffl = v.record;

  // Step 2: screen the licensee
  const holder = ffl.businessName || ffl.licenseName;
  const screening = await fetch(API + "/v1/compliance/restricted-party-screening", {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({ parties: [{ name: holder, country: "US" }] }),
  }).then((r) => r.json());

  if (screening.data.overallResult === "POTENTIAL_MATCH") {
    return { valid: false, reason: "Possible watchlist match: review required", ffl, screeningResults: screening.data };
  }

  return { valid: true, ffl, screeningResults: screening.data, verifiedAt: new Date().toISOString() };
}

// Usage
const result = await verifyFFL(fflNumber);
if (result.valid) {
  console.log("FFL verified");
} else {
  console.error("FFL not accepted:", result.reason);
}