@parseapi/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,553 @@
+/**
+ * Response types for the parseAPI public API.
+ * Shapes are append-only upstream, so these only ever grow.
+ * Every field inside a deep object is optional and nullable: the API ships
+ * `deep: {}` when deep was requested but is not unlocked on the plan.
+ */
+/** The `deep` key is omitted unless the request asked for it. */
+type Deep<T> = Partial<{
+    [K in keyof T]: T[K] | null;
+}>;
+interface IpDeep {
+    state: string;
+    city: string;
+    registry: string;
+    datacenter: boolean;
+    relay: boolean;
+    tor: boolean;
+    provider: string;
+}
+interface Ip {
+    ip: string;
+    country: string | null;
+    country_name: string | null;
+    continent: string | null;
+    asn: string | null;
+    asn_name: string | null;
+    deep?: Deep<IpDeep>;
+}
+interface Continent {
+    continent: string;
+    name: string;
+    region: string;
+    subregion: string;
+    population: number | null;
+    area: number | null;
+    emoji: string;
+}
+interface ContinentCountryItem {
+    country: string;
+    name: string;
+}
+interface ContinentCountries {
+    continent: string;
+    countries: ContinentCountryItem[];
+}
+interface Country {
+    country: string;
+    iso3: string;
+    numeric: number;
+    name: string;
+    full_name: string | null;
+    local_name: string | null;
+    demonym: string | null;
+    capital: string | null;
+    continent: string;
+    region: string | null;
+    subregion: string | null;
+    population: number | null;
+    area: number | null;
+    currency: string | null;
+    currency_name: string | null;
+    currency_symbol: string | null;
+    tld: string | null;
+    emoji: string | null;
+    languages: string[];
+    borders: string[];
+}
+interface CountryStateItem {
+    state: string;
+    name: string;
+    type: string | null;
+}
+interface CountryStates {
+    country: string;
+    states: CountryStateItem[];
+}
+interface State {
+    state: string;
+    name: string;
+    local_name: string | null;
+    type: string | null;
+    country: string;
+    country_name: string | null;
+    latitude: number | null;
+    longitude: number | null;
+    population: number | null;
+    area: number | null;
+    timezone: string | null;
+}
+interface StateDistrictItem {
+    district: string;
+    name: string;
+    type: string | null;
+}
+interface StateDistricts {
+    state: string;
+    state_name: string | null;
+    country: string;
+    country_name: string | null;
+    districts: StateDistrictItem[];
+}
+interface District {
+    district: string;
+    name: string;
+    type: string | null;
+    state: string | null;
+    state_name: string | null;
+    country: string;
+    country_name: string | null;
+    latitude: number | null;
+    longitude: number | null;
+    population: number | null;
+    land_area: number | null;
+    water_area: number | null;
+}
+interface City {
+    name: string;
+    local_name: string | null;
+    state: string | null;
+    state_name: string | null;
+    country: string;
+    latitude: number | null;
+    longitude: number | null;
+    population: number | null;
+    timezone: string | null;
+    /** Minted parse id (`city_` + 12 chars). Stable pin via `/city/id/{id}`. */
+    id: string;
+}
+/** Nearest-city lookups add the distance from the query point. */
+interface CityNearest extends City {
+    distance: number;
+    distance_mi: number;
+}
+interface CitySearch {
+    q: string;
+    country?: string;
+    state?: string;
+    cities: City[];
+}
+interface Postal {
+    postal: string;
+    city: string | null;
+    city_local: string | null;
+    district: string | null;
+    district_name: string | null;
+    district_name_local: string | null;
+    state: string | null;
+    state_name: string | null;
+    state_name_local: string | null;
+    country: string;
+    latitude: number | null;
+    longitude: number | null;
+    elevation: number | null;
+    elevation_ft: number | null;
+    population: number | null;
+    timezone: string | null;
+    currency: string | null;
+    neighbors: string[];
+}
+interface PostalNearbyItem {
+    postal: string;
+    city: string | null;
+    state: string | null;
+    country: string;
+    distance: number;
+    distance_mi: number;
+}
+interface PostalNearby {
+    postal: string;
+    country: string;
+    radius: number;
+    unit: string;
+    nearby: PostalNearbyItem[];
+}
+interface PostalDistanceEnd {
+    postal: string;
+    city: string | null;
+}
+interface PostalDistance {
+    country: string;
+    from: PostalDistanceEnd;
+    to: PostalDistanceEnd;
+    distance: number;
+    distance_mi: number;
+}
+interface EmailDeep {
+    deliverable: boolean;
+    catchall: boolean;
+}
+interface Email {
+    email: string;
+    valid: boolean;
+    domain: string | null;
+    domain_valid: boolean | null;
+    role: boolean;
+    disposable: boolean;
+    deep?: Deep<EmailDeep>;
+}
+interface PhoneDeep {
+    type: 'mobile' | 'landline' | 'toll_free' | 'unknown';
+    region: string;
+}
+interface Phone {
+    valid: boolean;
+    e164: string | null;
+    country: string | null;
+    national: string | null;
+    international: string | null;
+    deep?: Deep<PhoneDeep>;
+}
+interface MxRecord {
+    priority: number;
+    host: string;
+}
+interface DomainRegistration {
+    registered: boolean;
+    created: string | null;
+    updated: string | null;
+    expires: string | null;
+    registrar: string | null;
+    status: string[];
+    dnssec: boolean;
+}
+interface DomainDeep {
+    a: string[];
+    aaaa: string[];
+    ns: string[];
+    mx: MxRecord[];
+    txt: string[];
+    provider: string;
+    registration: DomainRegistration;
+}
+interface Domain {
+    domain: string;
+    available: boolean;
+    deep?: Deep<DomainDeep>;
+}
+interface Mx {
+    domain: string;
+    mx: MxRecord[];
+}
+interface UseragentDeviceDeep {
+    type: string | null;
+    brand: string | null;
+    model: string | null;
+    cpu: string | null;
+    touchscreen: boolean | null;
+}
+interface UseragentOsDeep {
+    name: string | null;
+    version: string | null;
+    platform: string | null;
+}
+interface UseragentBrowserBrand {
+    brand: string;
+    version: string;
+}
+interface UseragentBrowserDeep {
+    name: string | null;
+    version: string | null;
+    type: string | null;
+    brands?: UseragentBrowserBrand[];
+}
+interface UseragentEngineDeep {
+    name: string | null;
+    version: string | null;
+}
+interface UseragentDeep {
+    device: UseragentDeviceDeep;
+    os: UseragentOsDeep;
+    browser: UseragentBrowserDeep;
+    engine: UseragentEngineDeep;
+    headless: boolean;
+    bot?: Record<string, unknown>;
+    ai?: boolean;
+}
+interface Useragent {
+    useragent: string;
+    device: string | null;
+    os: string | null;
+    browser: string | null;
+    bot: boolean;
+    mobile: boolean;
+    deep?: Deep<UseragentDeep>;
+}
+interface Currency {
+    currency: string;
+    numeric: number | null;
+    name: string;
+    name_plural: string | null;
+    symbol: string | null;
+    symbol_native: string | null;
+    digits: number | null;
+    countries: string[];
+}
+/** One language by BCP 47 shortest code (en) or ISO 639-3 (eng). Codes are lowercase. */
+interface Language {
+    language: string;
+    iso3: string | null;
+    name: string;
+    local_name: string | null;
+    script: string | null;
+    direction: 'ltr' | 'rtl' | string;
+    countries: string[];
+}
+interface CurrencyRate {
+    base: string;
+    quote: string;
+    rate: number;
+    date: string;
+    source?: string;
+}
+interface TimezoneNextDst {
+    at: string;
+    dst: boolean;
+    offset: string;
+    abbreviation: string;
+}
+interface Timezone {
+    timezone: string;
+    name: string | null;
+    abbreviation: string;
+    offset: string;
+    offset_minutes: number;
+    dst: boolean;
+    next_dst: TimezoneNextDst | null;
+}
+interface Holiday {
+    date: string;
+    name: string;
+    local_name: string | null;
+    /** 'public' for an official day off, 'observance' for cultural days. */
+    type: string;
+    regions: string[] | null;
+    substitute: boolean;
+}
+interface HolidayYear {
+    country: string;
+    year: number;
+    holidays: Holiday[];
+}
+interface HolidayDate {
+    country: string;
+    date: string;
+    holiday: Holiday | null;
+}
+interface Elevation {
+    latitude: number;
+    longitude: number;
+    elevation: number | null;
+    elevation_ft: number | null;
+    resolution: number | null;
+}
+interface PointDeep {
+    city: CityNearest;
+    timezone: Timezone;
+}
+interface Point {
+    latitude: number;
+    longitude: number;
+    country: string | null;
+    country_name: string | null;
+    state: string | null;
+    state_name: string | null;
+    district: string | null;
+    district_name: string | null;
+    elevation: number | null;
+    elevation_ft: number | null;
+    resolution: number | null;
+    deep?: Deep<PointDeep>;
+}
+interface WeatherForecastPeriod {
+    name: string;
+    start: string | null;
+    end: string | null;
+    daytime: boolean | null;
+    temperature: number | null;
+    temperature_f: number | null;
+    precipitation_chance: number | null;
+    wind_speed: number | null;
+    wind_speed_mph: number | null;
+    wind_direction: number | null;
+    condition: string | null;
+    condition_name: string | null;
+    condition_emoji: string | null;
+}
+interface WeatherAlert {
+    event: string;
+    severity: string | null;
+    urgency: string | null;
+    headline: string | null;
+    onset: string | null;
+    expires: string | null;
+}
+interface WeatherDeep {
+    forecast: WeatherForecastPeriod[];
+    alerts: WeatherAlert[];
+}
+interface Weather {
+    latitude: number;
+    longitude: number;
+    temperature: number | null;
+    temperature_f: number | null;
+    feels_like: number | null;
+    feels_like_f: number | null;
+    dewpoint: number | null;
+    dewpoint_f: number | null;
+    humidity: number | null;
+    wind_speed: number | null;
+    wind_speed_mph: number | null;
+    wind_gust: number | null;
+    wind_gust_mph: number | null;
+    wind_direction: number | null;
+    pressure: number | null;
+    pressure_inhg: number | null;
+    visibility: number | null;
+    visibility_mi: number | null;
+    condition: string | null;
+    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;
+    deep?: Deep<WeatherDeep>;
+}
+interface EmojiSkin {
+    emoji: string;
+    tone: string;
+    unicode: string | null;
+    hex: string | null;
+}
+interface Emoji {
+    emoji: string;
+    name: string;
+    shortcodes: string[];
+    codepoints: string[];
+    hex: string;
+    category: string | null;
+    status: string | null;
+    version: string | null;
+    keywords: string[];
+    skins: EmojiSkin[];
+}
+interface EmojiSearch {
+    q: string;
+    emojis: Emoji[];
+}
+
+/** Every non-2xx response from the API. Branch on `code`, never on `message`. */
+declare class ParseAPIError extends Error {
+    /** HTTP status */
+    readonly status: number;
+    /** Machine-readable error code, e.g. 'not_found', 'invalid_api_key', 'rate_limited' */
+    readonly code: string;
+    /** Link to the docs section for this error */
+    readonly docs: string | null;
+    /** Send this if you contact support */
+    readonly requestId: string | null;
+    constructor(status: number, code: string, message: string, docs: string | null, requestId: string | null);
+}
+interface ParseAPIOptions {
+    /** Override https://api.parseapi.com (tests, canaries). Also read from PARSEAPI_BASE_URL. */
+    baseUrl?: string;
+    /** Per-attempt timeout in milliseconds. Default 10000. */
+    timeoutMs?: number;
+    /** Retries after the first attempt on network errors / 429 / 5xx. Default 2, 0 disables. */
+    retries?: number;
+    /** Custom fetch implementation (instrumentation, proxies). */
+    fetch?: typeof fetch;
+}
+interface DeepOption {
+    /** Request the nested deep object. Paid on most endpoints. */
+    deep?: boolean;
+}
+declare function parseAPI(apiKey?: string, options?: ParseAPIOptions): {
+    ip: ((ip: string, opts?: DeepOption) => Promise<Ip>) & {
+        self: (opts?: DeepOption) => Promise<Ip>;
+    };
+    continent: ((code: string) => Promise<Continent>) & {
+        countries: (code: string) => Promise<ContinentCountries>;
+    };
+    country: ((code: string) => Promise<Country>) & {
+        states: (code: string) => Promise<CountryStates>;
+    };
+    state: ((code: string, opts: {
+        country: string;
+    }) => Promise<State>) & {
+        districts: (code: string, opts: {
+            country: string;
+        }) => Promise<StateDistricts>;
+    };
+    district: (code: string, opts?: {
+        country?: string;
+    }) => Promise<District>;
+    city: ((name: string, opts?: {
+        country?: string;
+        state?: string;
+    }) => Promise<City>) & {
+        id: (id: string) => Promise<City>;
+        search: (q: string, opts?: {
+            country?: string;
+            state?: string;
+            limit?: number;
+        }) => Promise<CitySearch>;
+        nearest: (lat: number, lon: number) => Promise<CityNearest>;
+    };
+    postal: ((code: string, opts: {
+        country: string;
+    }) => Promise<Postal>) & {
+        nearby: (code: string, opts: {
+            country: string;
+            radius?: number;
+            unit?: "km" | "mi";
+        }) => Promise<PostalNearby>;
+        distance: (from: string, to: string, opts: {
+            country: string;
+        }) => Promise<PostalDistance>;
+    };
+    email: (email: string, opts?: DeepOption) => Promise<Email>;
+    phone: (number: string, opts?: {
+        country?: string;
+    } & DeepOption) => Promise<Phone>;
+    domain: (domain: string, opts?: DeepOption) => Promise<Domain>;
+    mx: (domain: string) => Promise<Mx>;
+    useragent: (ua: string, opts?: DeepOption) => Promise<Useragent>;
+    currency: ((code: string) => Promise<Currency>) & {
+        rate: (base: string, quote: string) => Promise<CurrencyRate>;
+    };
+    language: (code: string) => Promise<Language>;
+    timezone: (id: string, opts?: {
+        at?: string;
+    }) => Promise<Timezone>;
+    holiday: ((country: string, opts?: {
+        year?: number;
+    }) => Promise<HolidayYear>) & {
+        date: (country: string, date: string) => Promise<HolidayDate>;
+    };
+    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>;
+    emoji: ((emoji: string) => Promise<Emoji>) & {
+        search: (q: string, opts?: {
+            limit?: number;
+        }) => Promise<EmojiSearch>;
+    };
+};
+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 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 };