NAIC

bowmark.providers.naic.searchCompanies(query: naicCompanyQuery, limit?: number): Promise<naicRow[]>
bowmark.providers.naic.getComplaintIndex(cocode: string | number): Promise<naicComplaintIndexReport>
bowmark.providers.naic.listStateDepartments(query?: naicStateDepartmentQuery): Promise<naicStateDepartmentRow[]>
bowmark.providers.naic.getCompanyProfile(cocode: string | number): Promise<naicCompanyProfile>
bowmark.providers.naic.getLicensing(cocode: string | number): Promise<naicLicensingReport>

interface naicCompanyQuery {
  name?: string        // case-insensitive SUBSTRING of the company name
  homeState?: string   // 2-letter state the company is HEADQUARTERED in — not licensure
}

interface naicRow {
  cocode: string              // NAIC company code — the key every CIS report is addressed by
  name: string                // full legal entity name
  shortName: string           // the register's own abbreviated statutory name
  address: string | null      // HQ address as printed, newlines collapsed
  homeState: string | null    // 2-letter state of the HQ address — NOT where it may sell
  phone: string | null
  website: string | null      // absolute https URL
  licensedStates: string[]    // where it IS licensed, per the regulators; [] = "no licensed states"
  reportCategories: string[]  // which CIS reports exist for it — NOT the lines it writes
  reportUrl: string           // this company's CIS report page
}

interface naicStateDepartmentQuery {
  jurisdiction?: string  // NAIC's own name ("Texas", case-insensitive) or the 2-letter code ("TX")
}

interface naicStateDepartmentRow {
  jurisdiction: string             // "Alabama", "Puerto Rico" — 56 of them, NAIC's own count
  jurisdictionCode: string | null  // 2-letter code, from the site's own address record
  department: string | null        // department name as the register records it; null when it records none
  regulator: string | null         // the sitting regulator; NULL when the post is vacant
  regulatorTitle: string | null    // "Commissioner" / "Director" / "Superintendent"
  website: string | null
  email: string | null
  officeHours: string | null
  phones: naicPhone[]              // every published number, with the department's own label
  mainPhone: string | null         // the number the department flags as primary
  consumerHotline: string | null   // DERIVED from the labels; null when none names consumers or toll-free
  addresses: naicAddress[]
  complaintUrl: string | null      // where a complaint is ACTUALLY filed — the department's own intake page
  agentLookupUrl: string | null    // this jurisdiction's producer licence lookup
  contactUrl: string               // the NAIC page for this jurisdiction
}

interface naicComplaintIndexReport {
  cocode: string
  complaintIndex: number | null          // 1.0 is the NATIONAL baseline; 2.23 ≈ twice the expected complaints. null ≠ 0
  nationalComplaintIndex: number | null  // the baseline NAIC prints alongside it — 1 on every company measured
  comparison: "above" | "below" | null   // NAIC's OWN verdict against that baseline, not one we compute
  hasReport: boolean                     // false = NAIC publishes no complaint record — NOT "no such company"
  totalComplaints: number                // sum of byCode
  byCode: naicComplaintCode[]            // per coverage line, largest first
  reportUrl: string                      // the CIS report page a human can read
}

interface naicComplaintCode {
  codeName: string       // "Private Passenger", "Liability" — NOT unique without coverageType
  coverageType: string   // "Auto", "Homeowners", "Life", "Accident and Health"
  code: string           // NAIC's numeric complaint code, e.g. "105" — the stable key
  complaints: number     // closed-confirmed complaints under this code
}

interface naicCompanyProfile {
  cocode: string
  name: string | null                  // the register's abbreviated statutory name
  statementType: string | null         // "Property/Casualty" | "Life" | "Health" | ... — the regulator's classification
  financialYear: number | null         // the statement year EVERY figure below is as of; carriers can differ
  groupCode: string | null             // NAIC's holding-group id, shared by every affiliate; null = files alone
  groupName: string | null             // who actually owns it ("BERKSHIRE HATHAWAY GRP")
  stateOfDomicile: string | null       // the state whose regulator supervises it — usually NOT its HQ state
  commencedBusinessDate: string | null // ISO date first authorized to transact business
  fein: string | null
  address: string | null
  website: string | null
  phone: string | null
  assets: number | null             // total admitted assets, US dollars, as of financialYear; null is not 0
  liabilities: number | null
  capitalAndSurplus: number | null  // assets - liabilities: the cushion behind the promises
  netIncomeByYear: naicAnnualFigure[]      // most recent first; amounts can be negative
  topLinesOfBusiness: naicLineOfBusiness[] // what it actually SELLS, by direct premium, largest first
  complaintCountByYear: naicAnnualFigure[] // raw COUNTS, not the index — see getComplaintIndex
  hasReport: boolean                   // false = NAIC publishes no financial report — NOT "no such company"
  reportUrl: string
}

interface naicLicensingReport {
  cocode: string
  name: string | null              // the register's abbreviated statutory name; null = no report
  states: naicStateLicense[]       // ALL 56 jurisdictions, alphabetical — the negatives included
  licensedStates: string[]         // 2-letter codes it IS licensed in; [] is a real answer
  insuranceTypes: string[]         // every line licensed ANYWHERE — not a per-state statement
  hasReport: boolean               // false = NAIC publishes no licensing report — NOT "no such company"
  reportUrl: string
}

interface naicStateLicense {
  state: string            // 2-letter jurisdiction code — 50 states + DC + PR/GU/VI/MP/AS
  jurisdiction: string     // NAIC's own full name ("Alaska", "U.S. Virgin Islands")
  licensed: boolean        // may it write business here at all
  status: string           // the report's OWN label, verbatim: "LICENSED" | "NOT LICENSED"
  insuranceTypes: string[] // lines licensed in THIS jurisdiction; [] when not licensed
}

interface naicAnnualFigure { year: number; amount: number | null }

interface naicLineOfBusiness {
  line: string                    // NAIC's line name, TRUNCATED to 50 chars by the site — match by prefix
  directPremium: number | null
}

interface naicPhone { label: string | null; number: string; primary: boolean }

interface naicAddress {
  label: string | null       // "Street", "Main", "Mailing Address for Agent Licensing"
  type: string | null        // the site's own classification — "street" or "mailing"
  organization: string | null
  lines: string[]
  city: string | null
  state: string | null
  postalCode: string | null
  country: string | null
  primary: boolean
}