Ford

bowmark.providers.ford.findDealers({ near, radiusMiles?, limit? }): Promise<fordDealerSearch>
bowmark.providers.ford.listNameplates({ match? }): Promise<fordNameplateDirectory>
bowmark.providers.ford.getOffers(args: { nameplate: string; postalCode: string; year?: number }): Promise<fordOffers>
bowmark.providers.ford.getVehicle(vin: string): Promise<fordVehicle | null>
bowmark.providers.ford.getRecalls(vin: string): Promise<fordVehicleRecalls | null>

interface fordDayHours {
  /** 24-hour "HH:MM", local to the dealer. */
  open: string;
  close: string;
}

/** What the locator says about one day. The three cases are DISTINCT: a window,
 * the literal "closed" when Ford flags the day shut, and null when Ford
 * publishes nothing. A null is UNKNOWN, not closed — about one dealer in a
 * hundred publishes no hours at all. */
type fordDayEntry = fordDayHours | "closed" | null;

type fordHours = Record<
  "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday",
  fordDayEntry
>;

interface fordDealerAddress {
  street: string;
  street2: string | null;
  city: string;
  state: string;
  /** ZIP, usually ZIP+4 as Ford stores it ("48126-3227"). */
  postalCode: string;
  country: string;
}

interface fordDealer {
  /** Ford's own dealer identifier ("P&A code"), e.g. "07128" — the key every
   * other Ford surface joins on, including the inventory API's per-vehicle
   * dealer record. */
  paCode: string;
  name: string;
  /** Ford's own classification; this function returns only "Dealer". */
  dealerType: string | null;
  address: fordDealerAddress;
  phone: string | null;
  fax: string | null;
  email: string | null;
  latitude: number | null;
  longitude: number | null;
  /** Straight-line miles from the centre of the searched ZIP. Nearest first. */
  distanceMiles: number | null;
  distanceKm: number | null;
  /** The dealer's own website. */
  url: string | null;
  /** Ford's canonical slug, e.g. "mi/dearborn/village-ford-inc". */
  urlKey: string | null;
  hoursUrl: string | null;
  serviceAppointmentUrl: string | null;
  inventoryNewUrl: string | null;
  inventoryUsedUrl: string | null;
  fordCertified: boolean;
  /** Ford's own capability flags, verbatim — "EV Certified Dealers", "Pickup and
   * Delivery", "Dealers That Sell Tires", "National fleet Pricing". */
  specialties: string[];
  salesHours: fordHours;
  serviceHours: fordHours;
}

interface fordDealerSearch {
  /** The ZIP that was searched. */
  postalCode: string;
  radiusMiles: number;
  /** Nearest first, and strictly inside radiusMiles. Ford discloses no total, so
   * a full list cannot be told from a truncated one except by raising limit. */
  dealers: fordDealer[];
}

interface fordNameplate {
  /** What every other Ford inventory endpoint takes as its `nameplate`
   * parameter, e.g. "f150", "mach-e", "superduty-commercial". */
  slug: string;
  /** Ford's marketing name, verbatim and therefore carrying its trademark
   * glyphs — "F-150®", "Mustang Mach-E®". null when Ford publishes none. */
  displayName: string | null;
  /** Ford's own conversational spellings, verbatim — so they carry ®/™ too.
   * Match against matchKeys instead. */
  aliases: string[];
  /** Ford's segment: "car", "suv" or "truck" as measured. */
  bodyStyle: string | null;
  /** Model years this nameplate can be searched for. */
  years: number[];
  /** Trim names as inventory search spells them ("Dark Horse™", "XLT Cargo Van"). */
  trims: string[];
  /** Every normalized form this row answers to — slug, display name and each
   * alias, lowercased with ®/™, spaces, hyphens and dots removed. Match your
   * user's words against THESE: Ford's own aliases for the F-150 are
   * "f-150®"/"f150®"/"f 150®", so a literal comparison against a user's "F-150"
   * matches nothing. */
  matchKeys: string[];
}

interface fordNameplateDirectory {
  /** The normalized form of your `match`, or null if you asked for everything. */
  match: string | null;
  /** Ford's own order. With a `match`, the rows answering to it: normally one,
   * legitimately more (both "superduty" and "superduty-commercial" are called
   * "Super Duty®"), and empty when Ford has no such model. */
  nameplates: fordNameplate[];
}

interface fordOfferProgram {
  id: string;
  name: string;
  /** Ford's own program type, verbatim — "Cash", "APR", and whatever else
   * Ford introduces. */
  type: string;
  /** Whole USD, negative for a discount. null when this program is not a
   * flat-amount one. */
  amount: number | null;
  /** null when this program is not a financing offer. Ford sends one term or
   * several (e.g. 36/48/60/72/84-month options on the same program). */
  aprTerms: { apr: number; termMonths: number }[] | null;
  startDate: string | null;
  endDate: string | null;
  disclaimer: string | null;
  /** Ford's own machine code, e.g. "PC_STANDALONE_APR", "DEALER_CASH". */
  programType: string | null;
  /** "Retail" (public), "Private" (military/loyalty/first-responder —
   * eligibility this function cannot itself verify), "Campaign", or
   * whatever else Ford uses. */
  category: string | null;
  /** True when Ford Motor Credit finances the program. */
  financeCompany: boolean;
  /** Ford's own flag for "eligibility depends on something beyond make/model/
   * ZIP" (military status, trade-in, loyalty). */
  conditional: boolean;
}

interface fordTrimOffers {
  trim: string;
  programs: fordOfferProgram[];
}

interface fordOffers {
  /** The inventory slug this was resolved from, e.g. "f150". */
  nameplate: string;
  modelYear: number;
  /** The ZIP that was searched — incentives are regional. */
  postalCode: string;
  /** Ford's own dealer-region code for that ZIP (e.g. "F48B"), when it sends
   * one. Opaque outside Ford. */
  region: string | null;
  trims: fordTrimOffers[];
}

interface fordVehicleImage {
  url: string;
  /** "primary", "exterior" or "interior" — search results carry "primary"
   * only; this endpoint returns the full set. */
  role: string;
  width: number | null;
  height: number | null;
}

interface fordVehiclePricing {
  msrp: number;
  /** null when Ford has no net figure for this vehicle. */
  netPriceAfterIncentives: number | null;
  currency: string;
  /** Ford's own required legal text — show it alongside any displayed price. */
  disclaimer: string;
}

interface fordVehicleAvailability {
  /** "in_stock", "in_transit", or a new value Ford introduces. */
  status: string;
  asOf: string;
}

interface fordVehicleDealer {
  name: string;
  city: string;
  state: string;
  distanceMiles: number;
  phone: string | null;
  address: string | null;
  websiteUrl: string | null;
}

interface fordVehicleOptionPackage {
  name: string;
  /** null when Ford prices the package into the vehicle's MSRP rather than
   * itemizing it. */
  msrp: number | null;
}

interface fordVehicle {
  vin: string;
  /** The slug `listNameplates` returns, e.g. "f150", "explorer". */
  nameplate: string;
  displayName: string;
  year: number;
  trim: string;
  bodyStyle: string | null;
  powertrain: string | null;
  drivetrain: string | null;
  exteriorColor: string | null;
  pricing: fordVehiclePricing;
  availability: fordVehicleAvailability;
  dealer: fordVehicleDealer;
  images: fordVehicleImage[];
  /** Canonical detail page — link every vehicle mention here. */
  vdpUrl: string;
  optionPackages: fordVehicleOptionPackage[];
}

interface fordRecallRecord {
  /** Ford's own campaign identifier, e.g. "23S37", "26S48". */
  campaignNumber: string | null;
  title: string | null;
  /** Issue date as Ford stores it. */
  issueDate: string | null;
  description: string | null;
  safetyRisk: string | null;
  remedy: string | null;
  status: string | null;
  /** True when this is a Field Service Action / Customer Satisfaction Program
   *  (an FSA, NOT a regulator-mandated recall). */
  isCustomerSatisfactionProgram: boolean;
}

interface fordVehicleRecalls {
  vin: string;
  vehicle: {
    year: string | null;
    make: string | null;
    model: string | null;
    bodyStyle: string | null;
    fuelType: string | null;
  };
  recalls: fordRecallRecord[];
  customerSatisfactionPrograms: fordRecallRecord[];
  counts: {
    recallsCount: number;
    cspCount: number;
    totalFsaCount: number;
  };
  /** True when the page acknowledges an empty result for this VIN (no
   *  recalls, no FSAs) rather than an error. Ford's own empty-state copy. */
  noRecalls: boolean;
  /** True when the upstream recall service failed to answer — the page
   *  surfaces its own API-error message in that case. */
  apiError: boolean;
  warnings: string[];
}