State Farm

bowmark.providers.statefarm.findAgent(query: StatefarmAgentQuery, limit?: number): Promise<StatefarmAgent[]>
bowmark.providers.statefarm.getLifeQuote(query: StatefarmLifeQuoteQuery): Promise<StatefarmLifeQuote[]>
bowmark.providers.statefarm.getRentersQuote(query: StatefarmRentersQuoteQuery | string): Promise<StatefarmRentersQuote>
bowmark.providers.statefarm.getBusinessQuote(query: StatefarmBusinessQuoteQuery): Promise<StatefarmBusinessQuote>

interface statefarmRow {
  /** US ZIP code — State Farm rates and routes every one of these functions by it. */
  zip: string;
}

/** One State Farm agency office, as the directory publishes it. A null means the
 * directory published nothing for that field — never that parsing failed. */
interface StatefarmAgent {
  name: string;
  url: string;
  /** The 11-char associate id at the tail of the agent's URL slug — the site's own
   * office key, stable across a name change. Null when the slug carries none. */
  officeId: string | null;
  street: string | null;
  /** The city as the DIRECTORY spells it, which is not always what you passed. */
  city: string | null;
  state: string | null;
  /** The office's OWN five-digit ZIP — frequently not the ZIP you searched, since
   * a city page spans every ZIP in the city. ALWAYS five digits: the directory
   * publishes ZIP+4 on most offices (136 of 195 measured) and this is normalized
   * so `zip === "60656"` is a comparison that works. */
  zip: string | null;
  /** The full ZIP+4 as published ("62704-1375"), or null where the directory
   * stated only five digits. */
  zipPlus4: string | null;
  /** Ten digits, no punctuation, exactly as published. */
  phone: string | null;
  description: string | null;
}

interface StatefarmAgentQuery {
  /** City name ("Oklahoma City") or State Farm's own slug ("oklahoma-city").
   * Slugifying is idempotent, so the slug always works — the escape hatch for the
   * cities State Farm indexes under an abbreviation ("corona-dl-mar"). */
  city: string;
  /** Two-letter state code, e.g. "IL". */
  state: string;
  /** Optional filter on each office's OWN ZIP. Throws (naming the ZIPs the city
   * really has) rather than returning [] when nothing matches. */
  zip?: string;
}

/** What getLifeQuote takes. Every field is an axis of State Farm's own rate
 * table — there is deliberately no name, email, phone or street address, because
 * the rating endpoint does not ask for them and supplying them would turn a rate
 * lookup into a sales lead. */
interface StatefarmLifeQuoteQuery {
  /** Date of birth, "MM-DD-YYYY" (ISO "YYYY-MM-DD" is accepted too). THIS is
   * what the engine rates on, not an age — holding the app's own age field at 35
   * and moving only the DOB moved the 20-year $500k premium from $27.84 to
   * $52.64 to $225.34 a month. */
  dob: string;
  /** "Male" or "Female" — the only two values the rate table carries. */
  sex: "Male" | "Female";
  /** Self-rated health band: "best" | "better" | "good" | "okay". The
   * applicant's own assessment feeding an INDICATIVE rate, not underwriting. */
  health: "best" | "better" | "good" | "okay";
  /** Death benefit in whole dollars, e.g. 500000. */
  coverageAmount: number;
  /** Term in years — 10, 20 or 30, the three State Farm publishes here. */
  termYears: 10 | 20 | 30;
  /** Height, feet part (4-7). Required — build is rated, and an empty height
   * makes the engine return nothing rather than assume one. */
  heightFeet: number;
  /** Height, inches part (0-11). */
  heightInches: number;
  /** Weight in pounds. Required and MATERIALLY rated: on the measured baseline
   * 5'10" at 175 lb is $27.84/mo and the same person at 260 lb is $46.99/mo. */
  weightPounds: number;
  /** Two-letter US state. Required by the flow, but measured across IL/CA/NY/FL
   * it does not move the premium by a cent, so quoting one risk in four states
   * returns four identical tables. */
  state: string;
  /** When the applicant last used tobacco. OMIT for never. Recency is rated, not
   * just yes/no: for a 35-year-old male, best band, $500k/20yr — never $27.84/mo,
   * last used this year $87.44, one year ago $36.09, three years ago $27.84. */
  tobaccoLastUsed?: { month: number; year: number };
}

/** One priced row of State Farm's term rate table. */
interface StatefarmLifeQuote {
  termYears: number;
  coverageAmount: number;
  /** Monthly premium for the base policy alone, in dollars. */
  monthlyPremium: number;
  /** Annual premium for the base policy. NOT monthlyPremium * 12 — paying
   * annually is cheaper and both numbers come from the engine. */
  annualPremium: number;
  /** Monthly premium including every rider the engine attached. Null when it
   * returned no total — never silently equal to monthlyPremium. */
  monthlyPremiumWithRiders: number | null;
  annualPremiumWithRiders: number | null;
  /** State Farm's internal rate class. Opaque, but it is the field that MOVES
   * when tobacco or health changes, so it cross-checks that a differing premium
   * came from the risk. */
  rateClass: number | null;
  productType: string | null;
  productKindCode: string | null;
  productId: string | null;
  /** True on the row matching the coverage and term you asked for — the engine
   * always returns the whole table around the request. */
  requested: boolean;
}

/** What getRentersQuote takes. A bare ZIP string is accepted too. There is
 * deliberately no name, date of birth, address or coverage amount: State Farm
 * publishes this estimate off the ZIP alone, and supplying an identity would
 * turn a price lookup into a sales lead. */
interface StatefarmRentersQuoteQuery {
  /** Five-digit US ZIP. */
  zip: string;
}

/** State Farm's own published monthly renters estimate for one ZIP. A null means
 * State Farm published nothing for that field — never that parsing failed. */
interface StatefarmRentersQuote {
  zip: string;
  /** The city State Farm resolved the ZIP to — its spelling, not the caller's. */
  city: string | null;
  state: string | null;
  /** Low and high ends of the monthly estimate, in whole US dollars. */
  monthlyPremiumLow: number;
  monthlyPremiumHigh: number;
  /** The range exactly as State Farm publishes it, e.g. "9 - 16". */
  monthlyPremiumRange: string;
  currency: "USD";
  /** State Farm's own statement of what this number is and is not — returned
   * because a price without it invites being read as a binding offer. */
  priceDisclaimer: string | null;
  /** The policy start window the flow offers for this ZIP, "MM-DD-YYYY". */
  effectiveDateEarliest: string | null;
  effectiveDateLatest: string | null;
}

/** What getBusinessQuote takes. Every field here is a RATING input State Farm's
 * engine refuses to price without, which is why almost nothing has a default: a
 * defaulted square footage or receipts figure returns a real premium for a
 * business that does not exist — a confident wrong answer rather than a missing
 * one. */
interface StatefarmBusinessQuoteQuery {
  /** The CALLER's own identity. Required and never defaulted — the engine gates
   * every price behind it, so a commercial quote cannot be anonymous the way
   * `getRentersQuote` and `getLifeQuote` can. */
  identity: QuoteIdentity;
  businessName: string;
  /** One of the 82 trade classifications State Farm rates online, e.g.
   * "AccountingServices". Anything else is a SOFT kickout to an agent. */
  businessDescription: string;
  organizationType: string;          // e.g. "Limited Liability Company"
  yearBusinessStarted: string;       // four-digit year
  addressLine1: string;
  addressLine2?: string;
  city: string;
  /** The full state NAME as the engine's own allowed values spell it
   * ("Illinois", not "IL"). */
  state: string;
  postalCode: string;                // five digits; the engine normalises to ZIP+4
  /** "tenant", "owneroccupant" or "businresidence". `owneroccupant` is a soft kickout. */
  occupancy: string;
  annualReceipts: string;            // gross, whole dollars
  squareFeet: string;                // occupied floor area of the location
  yearBuilt: string;
  businessPersonalPropertyLimit: string; // whole dollars
  numberOfEmployees: string;
  numberOfOfficersDirectors: string;
  /** Tenant improvements and betterments, whole dollars. Defaults to "0" —
   * unlike the fields above, "none" is the ordinary answer for a tenant and is a
   * real answer rather than an absent one. */
  tenantImprovementsAmount?: string;
  /** UNDERWRITING FACTS, with no defaults on purpose: State Farm treats two of
   * them as a HARD kickout — a loss in the past five years, or an existing State
   * Farm business policy, is a business it will NOT quote online. Answering them
   * on the caller's behalf hands back a price premised on facts nobody supplied. */
  hasPriorLossesInFiveYears: boolean;
  hasExistingStateFarmBusinessPolicy: boolean;
  hadInsuranceCancelledOrDeniedInThreeYears: boolean;
  /** The caller's acknowledgement of State Farm's privacy disclosure, which its
   * form requires before it will rate. It is theirs to give, so it is theirs to
   * pass — this function will not tick it for them. */
  acknowledgesPrivacyDisclosure: boolean;
  /** Policy start, "MM-DD-YYYY". Defaults to seven days out — a scheduling
   * choice rather than a fact about the business, and the engine rejects a date
   * in the past. */
  effectiveDate?: string;
}

/** Who the quote is for, exactly as they would type it into the carrier's own
 * form. Never defaulted, never read from the environment, never held by us. */
interface QuoteIdentity {
  firstName: string;
  lastName: string;
  /** ISO `YYYY-MM-DD`. Carriers rate on the DATE, never on an age you computed. */
  dob: string;
  email: string;
  /** E.164 preferred. */
  phone: string;
}

/** One State Farm Business Owners Policy price. A null means State Farm
 * published nothing for that field — a failed parse THROWS. */
interface StatefarmBusinessQuote {
  quoteId: string;
  transactionNumber: string | null;
  status: string;                    // "QUOTED" when a price came back
  /** State Farm's assumed monthly instalment. */
  monthlyPremium: number | null;
  /** The whole 12-month policy — the comparable figure. */
  fullTermPremium: number | null;
  baseDeductible: number | null;     // the policy-level deductible the price assumes
  effectiveDate: string | null;
  /** Named discounts and charges, SIGNED — negative is a discount. */
  adjustments: StatefarmBusinessAdjustment[];
  /** Every coverage in the bundle, whether or not it is switched on. */
  coverages: StatefarmBusinessCoverage[];
  /** State Farm's own words for what this number is. A price, not an offer. */
  disclaimer: string;
}

interface StatefarmBusinessAdjustment {
  description: string;
  category: string;
  amount: number;
}

interface StatefarmBusinessCoverage {
  name: string;
  category: string;
  selected: boolean;
  required: boolean;
}

// What would a business owners policy cost for my accounting practice?
const quote = await bowmark.providers.statefarm.getBusinessQuote({
  identity: { firstName: "Jordan", lastName: "Avery", dob: "1985-06-15",
    email: "jordan.avery@getyourz.app", phone: "+12015550147" },
  businessName: "Avery Consulting", businessDescription: "AccountingServices",
  organizationType: "Limited Liability Company", yearBusinessStarted: "2015",
  addressLine1: "1 W Old State Capitol Plz", city: "Springfield",
  state: "Illinois", postalCode: "62701", occupancy: "tenant",
  annualReceipts: "250000", squareFeet: "2000", yearBuilt: "1998",
  businessPersonalPropertyLimit: "25000", numberOfEmployees: "3",
  numberOfOfficersDirectors: "1", hasPriorLossesInFiveYears: false,
  hasExistingStateFarmBusinessPolicy: false,
  hadInsuranceCancelledOrDeniedInThreeYears: false,
  acknowledgesPrivacyDisclosure: true,
});
return `$${quote.monthlyPremium}/mo ($${quote.fullTermPremium}/yr), ${quote.baseDeductible} deductible`;

// Why is it that price, and what am I actually covered for?
const quote = await bowmark.providers.statefarm.getBusinessQuote(query);
return {
  discounts: quote.adjustments.map((a) => `${a.description}: $${a.amount}`),
  covered: quote.coverages.filter((c) => c.selected).map((c) => c.name),
  disclaimer: quote.disclaimer,
};