@parseapi/sdk 0.1.2 → 0.2.0

package/dist/index.d.cts

@@ -46,6 +46,22 @@ interface ContinentCountries {
     continent: string;
     countries: ContinentCountryItem[];
 }
+interface Bloc {
+    bloc: string;
+    name: string;
+    /** Current member count. An entity fact, not a list-length field. */
+    members: number;
+}
+interface BlocCountryItem {
+    country: string;
+    name: string;
+    emoji?: string | null;
+    calling_code?: string | null;
+}
+interface BlocCountries {
+    bloc: string;
+    countries: BlocCountryItem[];
+}
 interface Country {
     country: string;
     iso3: string;
@@ -70,6 +86,8 @@ interface Country {
     emoji: string | null;
     languages: string[];
     borders: string[];
+    /** Bloc memberships (EU, SCHENGEN, NATO, ...). Empty when none. */
+    blocs: string[];
 }
 interface CountryStateItem {
     state: string;
@@ -90,8 +108,16 @@ interface State {
     latitude: number | null;
     longitude: number | null;
     population: number | null;
+    /** Total area in km2. */
     area: number | null;
     timezone: string | null;
+    timezones: string[];
+    iso_3166_2: string | null;
+    fips: string | null;
+    capital: string | null;
+    area_codes: string[];
+    tax: string | null;
+    tax_rate: number | null;
 }
 interface StateDistrictItem {
     district: string;
@@ -116,18 +142,39 @@ interface District {
     latitude: number | null;
     longitude: number | null;
     population: number | null;
+    /** Total area in km2 (land + water, or the official total). */
+    area: number | null;
+    /** Land area in km2. Null when the source publishes total only. */
     land_area: number | null;
+    /** Water area in km2. Null when the source publishes total only. */
     water_area: number | null;
+    seat: string | null;
+    timezone: string | null;
+    timezones: string[];
 }
 interface City {
     name: string;
     local_name: string | null;
+    type: string | null;
+    /** What this city is the capital of: country, state, or null. */
+    capital_of: 'country' | 'state' | null;
     state: string | null;
     state_name: string | null;
+    district: string | null;
+    district_name: string | null;
     country: string;
+    country_name: string | null;
     latitude: number | null;
     longitude: number | null;
+    elevation: number | null;
+    elevation_ft: number | null;
     population: number | null;
+    /** Total area in km2 (land + water, or the official total). */
+    area: number | null;
+    /** Land area in km2. Null when the source publishes total only. */
+    land_area: number | null;
+    /** Water area in km2. Null when the source publishes total only. */
+    water_area: number | null;
     timezone: string | null;
     /** Minted parse id (`city_` + 12 chars). Stable pin via `/city/id/{id}`. */
     id: string;
@@ -143,6 +190,14 @@ interface CitySearch {
     state?: string;
     cities: City[];
 }
+interface CityNearby {
+    city: string;
+    state: string | null;
+    country: string;
+    radius: number;
+    unit: string;
+    nearby: CityNearest[];
+}
 interface Postal {
     postal: string;
     city: string | null;
@@ -154,11 +209,18 @@ interface Postal {
     state_name: string | null;
     state_name_local: string | null;
     country: string;
+    country_name: string | null;
     latitude: number | null;
     longitude: number | null;
     elevation: number | null;
     elevation_ft: number | null;
     population: number | null;
+    /** Total area in km2. Null when the source has no water split. */
+    area: number | null;
+    /** Land area in km2. Null where the source has none. */
+    land_area: number | null;
+    /** Water area in km2. Null where the source has none. */
+    water_area: number | null;
     timezone: string | null;
     currency: string | null;
     neighbors: string[];
@@ -203,22 +265,230 @@ interface Email {
     disposable: boolean;
     deep?: Deep<EmailDeep>;
 }
-interface PhoneDeep {
-    type: 'mobile' | 'landline' | 'voip' | 'toll_free' | 'unknown';
-    carrier: string | null;
-    /** Carrier is a known burner number app. Null when carrier is unknown. */
-    burner: boolean | null;
+interface VatAddress {
+    street: string | null;
+    city: string | null;
+    postal: string | null;
+    country: string | null;
+}
+interface VatDeep {
+    registered: boolean | null;
+    name: string | null;
+    address: VatAddress | null;
+    consultation: string | null;
+    /** Registry timestamp of this check, ISO. */
+    consulted_at: string | null;
+}
+interface Vat {
+    vat: string | null;
+    valid: boolean;
+    country: string | null;
+    from?: string;
+    deep?: Deep<VatDeep>;
+}
+interface Iban {
+    iban: string | null;
+    valid: boolean;
+    country: string | null;
+    /** Print form in groups of four, for display. Null when invalid. */
+    formatted: string | null;
+    /** Two check digits as a string, keeping a leading zero. */
+    checksum: string | null;
+    /** Bank identifier parsed from the number, not a name. */
+    bank: string | null;
+    /** Branch identifier when that country has one. */
+    branch: string | null;
+    account: string | null;
+}
+interface Npi {
+    /** Normalized 10-digit NPI. Invalid input still echoes the fold. */
+    npi: string | null;
+    valid: boolean;
+    /** Exists in the CMS NPPES registry. */
+    registered: boolean | null;
+    active: boolean | null;
+    /** On the OIG exclusion list. */
+    excluded: boolean | null;
+    /** individual or organization. */
+    type: string | null;
+    name: string | null;
+    first: string | null;
+    last: string | null;
+    credential: string | null;
+    specialty: string | null;
+    /** NUCC taxonomy code. */
+    taxonomy: string | null;
+    address: string | null;
     city: string | null;
     state: string | null;
     state_name: string | null;
+    postal: string | null;
+    country: string | null;
+    phone: string | null;
+    deep?: Deep<NpiDeep>;
+}
+interface NpiEnrollment {
+    /** part_a, part_b, practitioner, dme, order_refer, mdpp. Null when the code is unknown. */
+    type: string | null;
+    specialty: string | null;
+    state: string | null;
+}
+interface NpiDeep {
+    /** In the published Medicare FFS enrollment extract. */
+    medicare?: boolean | null;
+    /** On the CMS opt-out affidavit list. Matched by NPI only. */
+    opt_out?: boolean | null;
+    /** Enrollment rows. [] when medicare is false. */
+    enrollments?: NpiEnrollment[] | null;
+}
+interface HtsMeasure {
+    /** Chapter 99 heading, dotted (9903.01.24). */
+    heading: string;
+    /** The measure text verbatim. */
+    description: string;
+    /** The rate string verbatim ("The duty provided in the applicable subheading + 10%"). */
+    rate: string | null;
+    /** Effective from, ISO YYYY-MM-DD. Null when the schedule states none. */
+    from: string | null;
+    /** Expires, ISO YYYY-MM-DD. Null when open-ended. */
+    until: string | null;
+}
+interface HtsDeep {
+    /** The origin country the measures were resolved for. */
+    origin?: string | null;
+    /** Composed ad valorem percent. Null when the components do not compose cleanly. */
+    effective_rate?: number | null;
+    /** Every Chapter 99 tariff measure that applies to this code from this origin. */
+    measures?: HtsMeasure[] | null;
+}
+interface Hts {
+    /** Normalized code with dots (8471.30.01.00). */
+    hts: string;
+    /** The schedule line verbatim. */
+    description: string;
+    /** Parent descriptions from the schedule outline, outermost first. */
+    lineage: string[];
+    /** Units of quantity (No., kg). */
+    units: string[];
+    /** Column 1 general rate, verbatim. */
+    general: string | null;
+    /** Column 1 special rate, verbatim. */
+    special: string | null;
+    /** Column 2 rate, verbatim. */
+    other: string | null;
+    /** The official release that answered (2026HTSRev17). */
+    revision: string;
+    deep?: Deep<HtsDeep>;
+}
+interface HtsSearchHit {
+    hts: string;
+    description: string;
+    general: string | null;
+}
+interface HtsSearch {
+    q: string;
+    revision: string;
+    /** Up to 20 tariff lines, best match first. */
+    lines: HtsSearchHit[];
+}
+interface VinRecall {
+    /** Government campaign number. */
+    campaign: string;
+    /** Report date, ISO YYYY-MM-DD. */
+    date: string | null;
+    component: string | null;
+    /** The filed summary verbatim. */
+    summary: string | null;
+}
+interface VinDeep {
+    /** Open recall campaigns for the decoded vehicle. [] when none, null when the registry did not answer. */
+    recalls?: VinRecall[] | null;
+}
+interface Vin {
+    /** Normalized VIN, uppercase, no spaces. Invalid input still echoes the fold. */
+    vin: string | null;
+    valid: boolean;
+    year: number | null;
+    make: string | null;
+    model: string | null;
+    trim: string | null;
+    series: string | null;
+    /** Body style (sedan, coupe, suv, pickup). */
+    body: string | null;
+    /** Vehicle type (passenger car, truck, motorcycle, bus, trailer). */
+    type: string | null;
+    doors: number | null;
+    cylinders: number | null;
+    /** Engine displacement in liters. */
+    displacement: number | null;
+    fuel: string | null;
+    horsepower: number | null;
+    /** fwd, rwd, awd, 4wd. */
+    drive: string | null;
+    /** automatic, manual, cvt. */
+    transmission: string | null;
+    manufacturer: string | null;
+    plant_city: string | null;
+    plant_state: string | null;
+    plant_country: string | null;
+    /** Gross vehicle weight rating class as filed. */
+    gvwr: string | null;
+    deep?: Deep<VinDeep>;
 }
 interface Phone {
     phone: string | null;
     valid: boolean;
     country: string | null;
+    /** What the numbering plan can see. Never voip (that is the carrier field's word). Null when invalid. */
+    type: 'mobile' | 'landline' | 'toll_free' | 'unknown' | null;
+    /** NPA-derived state code (US/CA). */
+    state: string | null;
+    state_name: string | null;
     national: string | null;
     international: string | null;
-    deep?: Deep<PhoneDeep>;
+    /** Always empty. The metered proves are their own endpoints: carrier, caller, hlr. */
+    deep?: Record<string, never>;
+}
+interface Carrier {
+    phone: string | null;
+    valid: boolean;
+    country: string | null;
+    /** The network's word, including voip. Null when invalid. */
+    type: 'mobile' | 'landline' | 'voip' | 'toll_free' | 'unknown' | null;
+    /** Current carrier display name. Null when the probe had no answer. */
+    carrier: string | null;
+    /** Carrier is a known burner number app. Null when carrier is unknown. */
+    burner: boolean | null;
+    /** Issuing rate-center city. */
+    city: string | null;
+    state: string | null;
+    state_name: string | null;
+}
+interface Caller {
+    phone: string | null;
+    valid: boolean;
+    country: string | null;
+    /** CNAM record verbatim (all-caps telco artifact). Null when no record, outside NANP, or invalid. */
+    caller: string | null;
+}
+interface Hlr {
+    phone: string | null;
+    valid: boolean;
+    country: string | null;
+    /** Assigned to a subscriber. Null when invalid. */
+    live: boolean | null;
+    /** Handset reachable right now. Null means unconfirmed, never no. */
+    connected: boolean | null;
+    /** The six network extras fill on live HLR dips only. Null elsewhere (NANP, failover). */
+    roaming: boolean | null;
+    roaming_network: string | null;
+    /** ISO2, uppercase. */
+    roaming_country: string | null;
+    /** Current serving network name. */
+    network: string | null;
+    original_network: string | null;
+    mcc: string | null;
+    mnc: string | null;
 }
 interface MxRecord {
     priority: number;
@@ -332,6 +602,10 @@ interface CurrencyRate {
     quote: string;
     rate: number;
     date: string;
+    /** With amount= only: echo of the amount asked. */
+    amount?: number;
+    /** With amount= only: amount times rate, rounded to the quote currency minor-unit digits. */
+    converted?: number;
     source?: string;
 }
 interface TimezoneNextDst {
@@ -350,6 +624,49 @@ interface Timezone {
     offset_minutes: number | null;
     dst: boolean | null;
     next_dst: TimezoneNextDst | null;
+    /** With to= only: the resolved wall time in the from zone, ISO with its UTC offset. */
+    at?: string;
+    /** With to= only: the other zone at the same instant. to.at is the converted time. */
+    to?: TimezoneConversionTarget;
+}
+/** The other side of a timezone conversion. `at` is the converted wall time. */
+interface TimezoneConversionTarget {
+    timezone: string;
+    name: string | null;
+    abbreviation: string | null;
+    offset: string;
+    offset_minutes: number;
+    dst: boolean;
+    at: string;
+}
+/**
+ * Calendar facts for one date. Junk or ambiguous input returns valid: false,
+ * never an error. `to` and `days` appear only when a to= date was passed.
+ */
+interface DateInfo {
+    date: string;
+    valid: boolean;
+    year: number | null;
+    month: number | null;
+    month_name: string | null;
+    day: number | null;
+    /** ISO weekday, Monday 1 to Sunday 7. */
+    weekday: number | null;
+    weekday_name: string | null;
+    /** ISO 8601 week number. */
+    week: number | null;
+    /** The year that ISO week belongs to. Differs from year around January 1. */
+    week_year: number | null;
+    day_of_year: number | null;
+    quarter: number | null;
+    leap: boolean | null;
+    days_in_month: number | null;
+    /** Unix time at midnight UTC of that date, seconds. */
+    unix: number | null;
+    /** With to= only: the other date, normalized ISO. */
+    to?: string;
+    /** With to= only: signed days to the other date. Future positive. */
+    days?: number | null;
 }
 interface Holiday {
     date: string;
@@ -418,13 +735,79 @@ interface WeatherAlert {
     onset: string | null;
     expires: string | null;
 }
+interface WeatherHour {
+    at: string | null;
+    daytime: boolean | null;
+    temperature: number | null;
+    temperature_f: number | null;
+    feels_like: number | null;
+    feels_like_f: number | null;
+    humidity: number | null;
+    precipitation_chance: number | null;
+    wind_speed: number | null;
+    wind_speed_mph: number | null;
+    wind_gust: number | null;
+    wind_gust_mph: number | null;
+    wind_direction: number | null;
+    condition: string | null;
+    condition_name: string | null;
+    condition_emoji: string | null;
+}
+interface WeatherMinute {
+    at: string;
+    precipitation: number | null;
+    precipitation_in: number | null;
+    type: string | null;
+}
+interface WeatherDay {
+    date: string;
+    high: number | null;
+    high_f: number | null;
+    low: number | null;
+    low_f: number | null;
+    precipitation_chance: number | null;
+    condition: string | null;
+    condition_name: string | null;
+    condition_emoji: string | null;
+    sunrise: string | null;
+    sunset: string | null;
+    moon_phase: string | null;
+    moon_phase_name: string | null;
+    moon_phase_emoji: string | null;
+}
+interface WeatherAir {
+    aqi: number | null;
+    aqi_name: string | null;
+    pm2_5: number | null;
+    pm10: number | null;
+}
+interface WeatherHistory {
+    date: string;
+    high: number | null;
+    high_f: number | null;
+    low: number | null;
+    low_f: number | null;
+    precipitation: number | null;
+    precipitation_in: number | null;
+    wind_max: number | null;
+    wind_max_mph: number | null;
+    sunrise: string | null;
+    sunset: string | null;
+    moon_phase: string | null;
+    moon_phase_name: string | null;
+    moon_phase_emoji: string | null;
+}
 interface WeatherDeep {
-    forecast: WeatherForecastPeriod[];
-    alerts: WeatherAlert[];
+    forecast: WeatherForecastPeriod[] | null;
+    alerts: WeatherAlert[] | null;
+    minutes: WeatherMinute[] | null;
+    hours: WeatherHour[] | null;
+    days: WeatherDay[] | null;
+    air: WeatherAir | null;
+    /** Only present when the call carried ?date=. */
+    history?: WeatherHistory | null;
 }
-interface Weather {
-    latitude: number;
-    longitude: number;
+interface WeatherCurrent {
     temperature: number | null;
     temperature_f: number | null;
     feels_like: number | null;
@@ -445,12 +828,23 @@ interface Weather {
     condition_name: string | null;
     condition_emoji: string | null;
     observed_at: string | null;
-    station: string;
-    station_name: string | null;
-    station_distance: number;
-    station_distance_mi: number;
-    source: string;
-    source_name: string | null;
+}
+interface WeatherStation {
+    id: string;
+    name: string | null;
+    distance: number | null;
+    distance_mi: number | null;
+}
+interface WeatherSource {
+    id: string;
+    name: string | null;
+}
+interface Weather {
+    latitude: number;
+    longitude: number;
+    current: WeatherCurrent;
+    station: WeatherStation | null;
+    source: WeatherSource;
     deep?: Deep<WeatherDeep>;
 }
 interface EmojiSkin {
@@ -509,18 +903,22 @@ declare function parseAPI(apiKey?: string, options?: ParseAPIOptions): {
     continent: ((code: string) => Promise<Continent>) & {
         countries: (code: string) => Promise<ContinentCountries>;
     };
+    bloc: ((code: string) => Promise<Bloc>) & {
+        countries: (code: string) => Promise<BlocCountries>;
+    };
     country: ((code: string) => Promise<Country>) & {
         states: (code: string) => Promise<CountryStates>;
     };
-    state: ((code: string, opts: {
-        country: string;
+    state: ((code: string, opts?: {
+        country?: string;
     }) => Promise<State>) & {
-        districts: (code: string, opts: {
-            country: string;
+        districts: (code: string, opts?: {
+            country?: string;
         }) => Promise<StateDistricts>;
     };
     district: (code: string, opts?: {
         country?: string;
+        state?: string;
     }) => Promise<District>;
     city: ((name: string, opts?: {
         country?: string;
@@ -533,39 +931,81 @@ declare function parseAPI(apiKey?: string, options?: ParseAPIOptions): {
             limit?: number;
         }) => Promise<CitySearch>;
         nearest: (lat: number, lon: number) => Promise<CityNearest>;
+        nearby: (name: string, opts?: {
+            radius?: number;
+            unit?: "km" | "mi";
+            country?: string;
+            state?: string;
+            limit?: number;
+        }) => Promise<CityNearby>;
     };
-    postal: ((code: string, opts: {
-        country: string;
+    postal: ((code: string, opts?: {
+        country?: string;
     }) => Promise<Postal>) & {
-        nearby: (code: string, opts: {
-            country: string;
+        nearby: (code: string, opts?: {
+            country?: string;
             radius?: number;
             unit?: "km" | "mi";
         }) => Promise<PostalNearby>;
-        distance: (from: string, to: string, opts: {
-            country: string;
+        distance: (from: string, to: string, opts?: {
+            country?: string;
         }) => Promise<PostalDistance>;
     };
     email: (email: string, opts?: DeepOption) => Promise<Email>;
+    vat: (number: string, opts?: {
+        country?: string;
+        from?: string;
+    } & DeepOption) => Promise<Vat>;
+    iban: (iban: string, opts?: {
+        country?: string;
+    }) => Promise<Iban>;
+    npi: (npi: string, opts?: DeepOption) => Promise<Npi>;
     phone: (number: string, opts?: {
         country?: string;
     } & DeepOption) => Promise<Phone>;
+    carrier: (number: string, opts?: {
+        country?: string;
+    }) => Promise<Carrier>;
+    caller: (number: string, opts?: {
+        country?: string;
+    }) => Promise<Caller>;
+    hlr: (number: string, opts?: {
+        country?: string;
+    }) => Promise<Hlr>;
     domain: (domain: string, opts?: DeepOption) => Promise<Domain>;
     mx: (domain: string) => Promise<Mx>;
     useragent: (ua: string, opts?: DeepOption) => Promise<Useragent>;
+    vin: (vin: string, opts?: DeepOption) => Promise<Vin>;
+    hts: ((code: string, opts?: {
+        origin?: string;
+    } & DeepOption) => Promise<Hts>) & {
+        search: (q: string) => Promise<HtsSearch>;
+    };
     currency: ((code: string) => Promise<Currency>) & {
-        rate: (base: string, quote: string) => Promise<CurrencyRate>;
+        rate: (base: string, quote: string, opts?: {
+            date?: string;
+            amount?: number;
+        }) => Promise<CurrencyRate>;
     };
     language: (code: string) => Promise<Language>;
     name: (name: string) => Promise<Name>;
     timezone: {
         (id: string, opts?: {
             at?: string;
+            to?: string;
         }): Promise<Timezone>;
         (lat: number, lon: number, opts?: {
             at?: string;
         }): Promise<Timezone>;
     };
+    date: ((date: string, opts?: {
+        format?: "mdy" | "dmy";
+        to?: string;
+    }) => Promise<DateInfo>) & {
+        today: (opts?: {
+            to?: string;
+        }) => Promise<DateInfo>;
+    };
     holiday: ((country: string, opts?: {
         year?: number;
     }) => Promise<HolidayYear>) & {
@@ -573,7 +1013,9 @@ declare function parseAPI(apiKey?: string, options?: ParseAPIOptions): {
     };
     elevation: (lat: number, lon: number) => Promise<Elevation>;
     point: (lat: number, lon: number, opts?: DeepOption) => Promise<Point>;
-    weather: (lat: number, lon: number, opts?: DeepOption) => Promise<Weather>;
+    weather: (lat: number, lon: number, opts?: DeepOption & {
+        date?: string;
+    }) => Promise<Weather>;
     emoji: ((emoji: string) => Promise<Emoji>) & {
         search: (q: string, opts?: {
             limit?: number;
@@ -582,4 +1024,4 @@ declare function parseAPI(apiKey?: string, options?: ParseAPIOptions): {
 };
 type ParseAPIClient = ReturnType<typeof parseAPI>;
 
-export { type City, type CityNearest, type CitySearch, type Continent, type ContinentCountries, type ContinentCountryItem, type Country, type CountryStateItem, type CountryStates, type Currency, type CurrencyRate, type Deep, type District, type Domain, type DomainDeep, type DomainRegistration, type Elevation, type Email, type EmailDeep, type Emoji, type EmojiSearch, type EmojiSkin, type Holiday, type HolidayDate, type HolidayYear, type Ip, type IpDeep, type Language, type Mx, type MxRecord, type Name, type ParseAPIClient, ParseAPIError, type ParseAPIOptions, type Phone, type PhoneDeep, type Point, type PointDeep, type Postal, type PostalDistance, type PostalDistanceEnd, type PostalNearby, type PostalNearbyItem, type State, type StateDistrictItem, type StateDistricts, type Timezone, type TimezoneNextDst, type Useragent, type UseragentBrowserBrand, type UseragentBrowserDeep, type UseragentDeep, type UseragentDeviceDeep, type UseragentEngineDeep, type UseragentOsDeep, type Weather, type WeatherAlert, type WeatherDeep, type WeatherForecastPeriod, parseAPI };
+export { type Bloc, type BlocCountries, type BlocCountryItem, type Caller, type Carrier, type City, type CityNearby, type CityNearest, type CitySearch, type Continent, type ContinentCountries, type ContinentCountryItem, type Country, type CountryStateItem, type CountryStates, type Currency, type CurrencyRate, type DateInfo, type Deep, type District, type Domain, type DomainDeep, type DomainRegistration, type Elevation, type Email, type EmailDeep, type Emoji, type EmojiSearch, type EmojiSkin, type Hlr, type Holiday, type HolidayDate, type HolidayYear, type Hts, type HtsDeep, type HtsMeasure, type HtsSearch, type HtsSearchHit, type Iban, type Ip, type IpDeep, type Language, type Mx, type MxRecord, type Name, type Npi, type NpiDeep, type NpiEnrollment, type ParseAPIClient, ParseAPIError, type ParseAPIOptions, type Phone, type Point, type PointDeep, type Postal, type PostalDistance, type PostalDistanceEnd, type PostalNearby, type PostalNearbyItem, type State, type StateDistrictItem, type StateDistricts, type Timezone, type TimezoneConversionTarget, type TimezoneNextDst, type Useragent, type UseragentBrowserBrand, type UseragentBrowserDeep, type UseragentDeep, type UseragentDeviceDeep, type UseragentEngineDeep, type UseragentOsDeep, type Vat, type VatAddress, type VatDeep, type Vin, type VinDeep, type VinRecall, type Weather, type WeatherAir, type WeatherAlert, type WeatherCurrent, type WeatherDay, type WeatherDeep, type WeatherForecastPeriod, type WeatherHistory, type WeatherHour, type WeatherMinute, type WeatherSource, type WeatherStation, parseAPI };