@parseapi/sdk 0.4.0 → 1.0.0

package/README.md

@@ -17,11 +17,13 @@ Get a key at [parseapi.com](https://parseapi.com). The client also reads `PARSEA
 
 ## API versions
 
-Choose your team's API version in [Dashboard → API version](https://parseapi.com/dashboard/versions). One setting applies to every key, including new and replacement keys. Existing teams keep `1.0.0`; new teams start on `2.0.0`. Keep the same keys and lookup URLs. Installing or upgrading the package does not change the team's setting.
+Version 1.0.0 explicitly selects the API contract supported by this SDK. It sends `Parse-Version: 2.0.0` on every lookup so responses match the API contract supported by the package. Your key and the team's saved default stay the same.
 
-Published SDK `0.3.2` matches API `1.0.0`. The examples and response types in this source tree target API `2.0.0`, including changes that are not in `0.3.2`. Use a package release documented for your team's version. These types do not model every historical response; moving to `2.0.0` may require updating code that reads renamed, moved or removed fields.
+Upgrade the dependency in staging, review the [release notes](https://parseapi.com/docs/releases), and test the application before deploying the same code and dependency version to production. Commit your dependency lockfile so the tested package travels with your deployment. Future major SDK upgrades can select a newer API contract.
 
-Test the target contract in a separate development team before changing your production team's version. A change applies to every integration in that team. See [API versions and migration](https://parseapi.com/docs/versioning).
+Previously published SDKs keep their existing behavior and use the team's default. Requests without `Parse-Version` also use that default, managed in [Dashboard API version](https://parseapi.com/dashboard/versions). Keep it unchanged while older applications depend on it. Rolling back to an SDK without a version header restores the team default, so rollback only restores the old contract when that default has stayed unchanged.
+
+The package owns its supported API version. For direct HTTP integrations, an explicit `Parse-Version` header selects a supported contract. See [API versions and migration](https://parseapi.com/docs/versioning).
 
 ## Weather from a postal code
 
@@ -43,6 +45,23 @@ Pass `country` when a postal code or national phone number needs disambiguation.
 
 Results are plain data. Pass a returned code or coordinate to another operation when the task needs it. Check nullable values before composing the next call.
 
+Name paid deep includes flat `short`, `directory`, and `initials` fields beside `gender` and `salutation`. `name_locale` selects CLDR formatting rules and defaults to `en`. It changes formatting only. Country remains gender context, and unavailable formatting is null. Older responses may omit these fields.
+
+## Display language
+
+This source candidate accepts an optional per-request `lang` on supported
+operations. It requires the matching API localization release and data.
+
+```ts
+const country = await parse.country('DE', { lang: 'fr' });
+// country: 'DE', name: 'Allemagne', name_local: 'Deutschland'
+```
+
+Only supported display fields change. Missing translations keep their source
+names. IDs, native-name fields, numeric facts, Date input `format`, and Measure
+input `locale` retain their meaning. Omitting `lang` preserves the existing
+behavior and does not inherit a previous request's choice.
+
 ## Calls
 
 One method per endpoint, named after the route.
@@ -87,6 +106,7 @@ await parse.currency.rate('USD', 'EUR');
 await parse.language('en');
 await parse.name('BILLY OSHALL');
 await parse.name('Andrea', { country: 'IT', deep: true });
+await parse.name('Robert James Smith', { deep: true, name_locale: 'en' });
 await parse.time(); // UTC now
 await parse.time('America/New_York');
 await parse.time('America/New_York', { at: '2026-09-05T15:00:00', to: 'Asia/Tokyo' });
@@ -144,7 +164,7 @@ const place = await parse.postal('28202', { country: 'US', deep: true });
 const propertyTax = place.deep?.property_tax;
 ```
 
-Read `population_period` alongside `population`: a reporting year (`YYYY`) or period (`YYYY-YYYY`), null when unknown or unverifiable. Keep missing or null values unknown and preserve a known zero. These fields belong to full place profiles. State district lists include each district's population and period. Postal nearby and distance detail remains metropolitan associations only. Continent population and its period remain in core.
+Read `population_period` alongside `population`: a reporting year (`YYYY`) or period (`YYYY-YYYY`), null when unknown or unverifiable. Keep missing or null values unknown and preserve a known zero. These fields belong to full place profiles. State district lists include each district's population and period. Postal nearby and distance detail remains metropolitan associations only. Continent population stays in core; Continent has no `population_period` field.
 
 Point returns the timezone ID with the core location. Its optional deep detail adds terrain and compact nearest-city context on every plan. A nearest city is null when none is within 200 km.
 

package/dist/index.cjs

@@ -24,7 +24,8 @@ __export(index_exports, {
   parseAPI: () => parseAPI
 });
 module.exports = __toCommonJS(index_exports);
-var VERSION = "0.4.0";
+var VERSION = "1.0.0";
+var API_VERSION = "2.0.0";
 var DEFAULT_BASE_URL = "https://api.parseapi.com";
 var DEFAULT_TIMEOUT_MS = 1e4;
 var DEFAULT_RETRIES = 2;
@@ -114,6 +115,7 @@ function parseAPI(apiKey, options = {}) {
     validateTimeout(attemptTimeout);
     validateRetries(retries);
     const url = new URL(baseUrl + path);
+    if (controls.lang !== void 0) url.searchParams.set("lang", controls.lang);
     for (const [name, value] of Object.entries(query ?? {})) {
       if (value !== void 0) url.searchParams.set(name, String(value));
     }
@@ -129,7 +131,7 @@ function parseAPI(apiKey, options = {}) {
         try {
           res = await doFetch(url, {
             redirect: "manual",
-            headers: { "X-API-Key": key, "User-Agent": `parseapi-node/${VERSION}`, ...headers },
+            headers: { "X-API-Key": key, "User-Agent": `parseapi-node/${VERSION}`, ...headers, "Parse-Version": API_VERSION },
             signal: controller.signal
           });
         } catch (error) {
@@ -314,7 +316,7 @@ function parseAPI(apiKey, options = {}) {
       }
     ),
     language: (code, opts) => request(`/language/${enc(code)}`, deepQuery(opts), void 0, opts),
-    name: (name, opts) => request(`/name/${enc(name)}`, { country: opts?.country, ...deepQuery(opts) }, void 0, opts),
+    name: (name, opts) => request(`/name/${enc(name)}`, { country: opts?.country, ...deepQuery(opts), name_locale: opts?.name_locale }, void 0, opts),
     /** Current local time, UTC by default. With to, offsetless at is source wall time. */
     time: Object.assign(
       (timezone, opts) => request(timezone === void 0 ? "/time" : `/time/${enc(timezone)}`, { at: opts?.at, to: opts?.to, ...deepQuery(opts) }, void 0, opts),

package/dist/index.d.cts

@@ -250,14 +250,16 @@ interface PostalDistance {
     distance_mi: number;
 }
 interface EmailDeep {
-    deliverable: boolean;
-    catchall: boolean;
+    deliverable: boolean | null;
+    catchall: boolean | null;
 }
 interface Email {
     email: string;
     didyoumean: string | null;
     valid: boolean;
+    free: boolean;
     domain: string | null;
+    domain_type: 'academic' | 'government' | 'military' | null;
     domain_valid: boolean | null;
     role: boolean;
     disposable: boolean;
@@ -519,7 +521,10 @@ interface Bin {
     prefix: string | null;
     country: string | null;
     issuer: string | null;
+    /** Network key (visa, amex) or co-branded combination. */
     brand: string | null;
+    /** Display name for brand (American Express). */
+    brand_name: string | null;
     type: string | null;
     prepaid: boolean | null;
     deep?: Record<string, never>;
@@ -988,6 +993,16 @@ interface CountryDeep {
     /** Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable. */
     population_period?: string | null;
     area: number | null;
+    /** Land area in km2. */
+    land_area?: number | null;
+    /** Water area in km2. */
+    water_area?: number | null;
+    /** Coastline length in km. Zero is a known landlocked coastline. */
+    coastline?: number | null;
+    /** Mean elevation in metres above sea level. */
+    elevation?: number | null;
+    lowest_point?: CountryElevationPoint | null;
+    highest_point?: CountryElevationPoint | null;
     tld: string | null;
     /** Levy name, such as VAT, GST or sales tax. Null when unknown or not applicable. */
     tax?: string | null;
@@ -1013,6 +1028,11 @@ interface CountryDeep {
     fifa: string | null;
     plate: string | null;
 }
+interface CountryElevationPoint {
+    name: string | null;
+    /** Elevation in metres above sea level. Values below sea level are negative. */
+    elevation: number;
+}
 interface StateDeep {
     population: number | null;
     /** Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable. */
@@ -1129,12 +1149,14 @@ interface LanguageDeep {
     countries: string[];
 }
 interface NameDeep {
-    /** Name membership is independent of gender. */
-    known: boolean;
-    /** Associated countries, not the person's nationality. */
-    countries: string[];
     gender: 'male' | 'female' | null;
     salutation: 'Mr' | 'Ms' | null;
+    /** Compact name using CLDR formatting rules. */
+    short?: string | null;
+    /** Name formatted for a directory listing. */
+    directory?: string | null;
+    /** Name initials using CLDR formatting rules. */
+    initials?: string | null;
 }
 interface TimezoneDeep {
     name: string | null;
@@ -1233,6 +1255,10 @@ declare class ParseAPIError extends Error {
     readonly requestId: string | null;
     constructor(status: number, code: string, message: string, docs: string | null, requestId: string | null);
 }
+/** Optional output language for supported display fields. Input parsing stays unchanged. */
+interface LanguageOption {
+    lang?: string;
+}
 interface RequestOptions {
     /** Cancel this call, including any retry wait. */
     signal?: AbortSignal;
@@ -1252,36 +1278,36 @@ interface ParseAPIOptions {
     fetch?: typeof fetch;
 }
 /** IP enrichment is included with a paid plan. `deep` does not use a separate check meter. */
-type IpOptions = DeepOption & RequestOptions;
-type IpSelfOptions = DeepOption & RequestOptions;
-type ContinentOptions = RequestOptions;
-type ContinentCountriesOptions = RequestOptions;
+type IpOptions = LanguageOption & DeepOption & RequestOptions;
+type IpSelfOptions = LanguageOption & DeepOption & RequestOptions;
+type ContinentOptions = LanguageOption & RequestOptions;
+type ContinentCountriesOptions = LanguageOption & RequestOptions;
 type BlocOptions = RequestOptions;
-type BlocCountriesOptions = RequestOptions;
-type CountryOptions = DeepOption & RequestOptions;
-type CountryStatesOptions = RequestOptions;
-type StateOptions = {
+type BlocCountriesOptions = LanguageOption & RequestOptions;
+type CountryOptions = LanguageOption & DeepOption & RequestOptions;
+type CountryStatesOptions = LanguageOption & RequestOptions;
+type StateOptions = LanguageOption & {
     country?: string;
 } & DeepOption & RequestOptions;
-type StateDistrictsOptions = {
+type StateDistrictsOptions = LanguageOption & {
     country?: string;
 } & DeepOption & RequestOptions;
-type DistrictOptions = {
+type DistrictOptions = LanguageOption & {
     country?: string;
     state?: string;
 } & DeepOption & RequestOptions;
-type CityOptions = {
+type CityOptions = LanguageOption & {
     country?: string;
     state?: string;
 } & DeepOption & RequestOptions;
-type CityIdOptions = DeepOption & RequestOptions;
-type CitySearchOptions = {
+type CityIdOptions = LanguageOption & DeepOption & RequestOptions;
+type CitySearchOptions = LanguageOption & {
     country?: string;
     state?: string;
     limit?: number;
 } & DeepOption & RequestOptions;
-type CityNearestOptions = DeepOption & RequestOptions;
-type CityNearbyOptions = {
+type CityNearestOptions = LanguageOption & DeepOption & RequestOptions;
+type CityNearbyOptions = LanguageOption & {
     radius?: number;
     unit?: 'km' | 'mi';
     country?: string;
@@ -1289,15 +1315,15 @@ type CityNearbyOptions = {
     limit?: number;
 } & DeepOption & RequestOptions;
 /** Pass country when known. Codes shared by multiple countries need it. */
-type PostalOptions = {
+type PostalOptions = LanguageOption & {
     country?: string;
 } & DeepOption & RequestOptions;
-type PostalNearbyOptions = {
+type PostalNearbyOptions = LanguageOption & {
     country?: string;
     radius?: number;
     unit?: 'km' | 'mi';
 } & DeepOption & RequestOptions;
-type PostalDistanceOptions = {
+type PostalDistanceOptions = LanguageOption & {
     country?: string;
 } & DeepOption & RequestOptions;
 type AddressOptions = {
@@ -1316,7 +1342,7 @@ type AddressSearchOptions = {
     /** Actual end-user IP as an optional locality hint for server-side calls. */
     ip?: string;
 } & RequestOptions;
-type CompanyOptions = {
+type CompanyOptions = LanguageOption & {
     country?: string;
 } & DeepOption & RequestOptions;
 /** `deep: true` requests a metered deliverability check. No automatic retries by default. */
@@ -1329,7 +1355,7 @@ type VatOptions = {
 type IbanOptions = {
     country?: string;
 } & DeepOption & RequestOptions;
-type NpiOptions = DeepOption & RequestOptions;
+type NpiOptions = LanguageOption & DeepOption & RequestOptions;
 /** Country resolves national-number ambiguity. Deep adds numbering-plan geography on every plan. */
 type PhoneOptions = {
     country?: string;
@@ -1346,7 +1372,7 @@ type HlrOptions = {
     country?: string;
 } & DeepOption & RequestOptions;
 type DomainOptions = DeepOption & RequestOptions;
-type AsnOptions = RequestOptions;
+type AsnOptions = LanguageOption & RequestOptions;
 type MacOptions = RequestOptions;
 /** Card-prefix reference lookup. Deep returns an empty object on every plan. */
 type BinOptions = DeepOption & RequestOptions;
@@ -1356,7 +1382,7 @@ type MeasureOptions = {
     locale?: string;
     system?: 'us' | 'imperial';
 } & RequestOptions;
-type MeasureUnitsOptions = {
+type MeasureUnitsOptions = LanguageOption & {
     query?: string;
     type?: string;
     unit?: string;
@@ -1380,36 +1406,38 @@ type TariffOptions = {
     origin?: string;
 } & DeepOption & RequestOptions;
 type TariffSearchOptions = RequestOptions;
-type CurrencyOptions = DeepOption & RequestOptions;
+type CurrencyOptions = LanguageOption & DeepOption & RequestOptions;
 type CurrencyRateOptions = {
     date?: string;
     amount?: number;
 } & RequestOptions;
-type LanguageOptions = DeepOption & RequestOptions;
-/** Country is an ISO2 context for paid deep name evidence. */
+type LanguageOptions = LanguageOption & DeepOption & RequestOptions;
+/** Country scopes paid deep gender evidence. Name locale selects formatting rules without changing parsing. */
 type NameOptions = {
     country?: string;
+    /** CLDR name-formatting locale, such as en or ja. Defaults to en. */
+    name_locale?: string;
 } & DeepOption & RequestOptions;
-type TimeOptions = {
+type TimeOptions = LanguageOption & {
     at?: string;
     to?: string;
 } & DeepOption & RequestOptions;
-type TimeAtOptions = {
+type TimeAtOptions = LanguageOption & {
     at?: string;
     to?: string;
 } & DeepOption & RequestOptions;
-type TimezoneOptions = {
+type TimezoneOptions = LanguageOption & {
     at?: string;
     to?: string;
 } & DeepOption & RequestOptions;
-type TimezoneAtOptions = {
+type TimezoneAtOptions = LanguageOption & {
     at?: string;
 } & DeepOption & RequestOptions;
-type DateOptions = {
+type DateOptions = LanguageOption & {
     format?: 'mdy' | 'dmy';
     to?: string;
 } & DeepOption & RequestOptions;
-type DateTodayOptions = {
+type DateTodayOptions = LanguageOption & {
     to?: string;
 } & DeepOption & RequestOptions;
 type HolidayOptions = {
@@ -1418,14 +1446,14 @@ type HolidayOptions = {
 type HolidayDateOptions = RequestOptions;
 type ElevationOptions = RequestOptions;
 /** Resolve the country, state, district and timezone at coordinates. Deep adds terrain and compact nearest-city context on every plan. The timezone ID stays in core. The nearest city is null when none is within 200 km. */
-type PointOptions = DeepOption & RequestOptions;
+type PointOptions = LanguageOption & DeepOption & RequestOptions;
 /** Get current conditions in metric and imperial units. Paid deep adds specialist current measurements, forecasts and related detail. With deep, date selects a past UTC day (YYYY-MM-DD) in deep.history alongside current conditions. Date alone does not request history. */
 type WeatherOptions = DeepOption & {
     /** Past UTC day, YYYY-MM-DD. Requires paid deep and populates deep.history alongside current. */
     date?: string;
 } & RequestOptions;
-type EmojiOptions = DeepOption & RequestOptions;
-type EmojiSearchOptions = {
+type EmojiOptions = LanguageOption & DeepOption & RequestOptions;
+type EmojiSearchOptions = LanguageOption & {
     limit?: number;
 } & DeepOption & RequestOptions;
 interface DeepOption {
@@ -1538,4 +1566,4 @@ declare function parseAPI(apiKey?: string, options?: ParseAPIOptions): {
 };
 type ParseAPIClient = ReturnType<typeof parseAPI>;
 
-export { type Address, type AddressOptions, type AddressSearch, type AddressSearchOptions, type AddressSuggestion, type Asn, type AsnOptions, type Bin, type BinOptions, type Bloc, type BlocCountries, type BlocCountriesOptions, type BlocCountryItem, type BlocOptions, type Caller, type CallerOptions, type Carrier, type CarrierDeep, type CarrierOptions, type City, type CityDeep, type CityIdOptions, type CityNearby, type CityNearbyOptions, type CityNearest, type CityNearestOptions, type CityOptions, type CitySearch, type CitySearchOptions, type Company, type CompanyCountry, type CompanyDeep, type CompanyOptions, type Continent, type ContinentCountries, type ContinentCountriesOptions, type ContinentCountryItem, type ContinentOptions, type Country, type CountryDeep, type CountryEmergency, type CountryOptions, type CountryStateItem, type CountryStates, type CountryStatesOptions, type Currency, type CurrencyDeep, type CurrencyOptions, type CurrencyRate, type CurrencyRateOptions, type DateInfo, type DateInfoDeep, type DateOptions, type DateTodayOptions, type Deep, type District, type DistrictDeep, type DistrictOptions, type Dns, type DnsOptions, type DnsRecord, type Domain, type DomainDeep, type DomainOptions, type DomainRegistration, type Elevation, type ElevationOptions, type Email, type EmailDeep, type EmailOptions, type Emoji, type EmojiDeep, type EmojiOptions, type EmojiSearch, type EmojiSearchOptions, type EmojiSkin, type Hlr, type HlrDeep, type HlrOptions, type Holiday, type HolidayDate, type HolidayDateOptions, type HolidayOptions, type HolidayYear, type Iban, type IbanDeep, type IbanOptions, type Ip, type IpDeep, type IpOptions, type IpSelfOptions, type Language, type LanguageDeep, type LanguageOptions, type Mac, type MacOptions, type Measure, type MeasureChoice, type MeasureOptions, type MeasureUnit, type MeasureUnits, type MeasureUnitsOptions, type Mx, type MxOptions, type MxRecord, type Naics, type NaicsChild, type NaicsCorrection, type NaicsDeep, type NaicsExclusion, type NaicsMatch, type NaicsOptions, type NaicsSearch, type NaicsSearchItem, type NaicsSearchOptions, type Name, type NameDeep, type NameOptions, type Npi, type NpiDeep, type NpiEnrollment, type NpiOptions, type ParseAPIClient, ParseAPIError, type ParseAPIOptions, type Phone, type PhoneDeep, type PhoneOptions, type Point, type PointCity, type PointDeep, type PointOptions, type Postal, type PostalDeep, type PostalDistance, type PostalDistanceEnd, type PostalDistanceOptions, type PostalMetro, type PostalMetrosDeep, type PostalNearby, type PostalNearbyItem, type PostalNearbyOptions, type PostalOptions, type PropertyTax, type RequestOptions, type State, type StateDeep, type StateDistrictDeep, type StateDistrictItem, type StateDistricts, type StateDistrictsOptions, type StateOptions, type Tariff, type TariffDeep, type TariffMeasure, type TariffOptions, type TariffSearch, type TariffSearchHit, type TariffSearchOptions, type Time, type TimeAtOptions, type TimeOptions, type Timezone, type TimezoneAtOptions, type TimezoneConversionTarget, type TimezoneConversionTargetDeep, type TimezoneDeep, type TimezoneNextDst, type TimezoneOptions, type Useragent, type UseragentBrowserBrand, type UseragentBrowserDeep, type UseragentDeep, type UseragentDeviceDeep, type UseragentEngineDeep, type UseragentOptions, type UseragentOsDeep, type Vat, type VatAddress, type VatDeep, type VatOptions, type Vin, type VinDeep, type VinOptions, type VinRecall, type Weather, type WeatherAir, type WeatherAlert, type WeatherCurrent, type WeatherCurrentDeep, type WeatherDay, type WeatherDeep, type WeatherForecastPeriod, type WeatherHistory, type WeatherHour, type WeatherMinute, type WeatherOptions, type WeatherStation, parseAPI };
+export { type Address, type AddressOptions, type AddressSearch, type AddressSearchOptions, type AddressSuggestion, type Asn, type AsnOptions, type Bin, type BinOptions, type Bloc, type BlocCountries, type BlocCountriesOptions, type BlocCountryItem, type BlocOptions, type Caller, type CallerOptions, type Carrier, type CarrierDeep, type CarrierOptions, type City, type CityDeep, type CityIdOptions, type CityNearby, type CityNearbyOptions, type CityNearest, type CityNearestOptions, type CityOptions, type CitySearch, type CitySearchOptions, type Company, type CompanyCountry, type CompanyDeep, type CompanyOptions, type Continent, type ContinentCountries, type ContinentCountriesOptions, type ContinentCountryItem, type ContinentOptions, type Country, type CountryDeep, type CountryElevationPoint, type CountryEmergency, type CountryOptions, type CountryStateItem, type CountryStates, type CountryStatesOptions, type Currency, type CurrencyDeep, type CurrencyOptions, type CurrencyRate, type CurrencyRateOptions, type DateInfo, type DateInfoDeep, type DateOptions, type DateTodayOptions, type Deep, type District, type DistrictDeep, type DistrictOptions, type Dns, type DnsOptions, type DnsRecord, type Domain, type DomainDeep, type DomainOptions, type DomainRegistration, type Elevation, type ElevationOptions, type Email, type EmailDeep, type EmailOptions, type Emoji, type EmojiDeep, type EmojiOptions, type EmojiSearch, type EmojiSearchOptions, type EmojiSkin, type Hlr, type HlrDeep, type HlrOptions, type Holiday, type HolidayDate, type HolidayDateOptions, type HolidayOptions, type HolidayYear, type Iban, type IbanDeep, type IbanOptions, type Ip, type IpDeep, type IpOptions, type IpSelfOptions, type Language, type LanguageDeep, type LanguageOption, type LanguageOptions, type Mac, type MacOptions, type Measure, type MeasureChoice, type MeasureOptions, type MeasureUnit, type MeasureUnits, type MeasureUnitsOptions, type Mx, type MxOptions, type MxRecord, type Naics, type NaicsChild, type NaicsCorrection, type NaicsDeep, type NaicsExclusion, type NaicsMatch, type NaicsOptions, type NaicsSearch, type NaicsSearchItem, type NaicsSearchOptions, type Name, type NameDeep, type NameOptions, type Npi, type NpiDeep, type NpiEnrollment, type NpiOptions, type ParseAPIClient, ParseAPIError, type ParseAPIOptions, type Phone, type PhoneDeep, type PhoneOptions, type Point, type PointCity, type PointDeep, type PointOptions, type Postal, type PostalDeep, type PostalDistance, type PostalDistanceEnd, type PostalDistanceOptions, type PostalMetro, type PostalMetrosDeep, type PostalNearby, type PostalNearbyItem, type PostalNearbyOptions, type PostalOptions, type PropertyTax, type RequestOptions, type State, type StateDeep, type StateDistrictDeep, type StateDistrictItem, type StateDistricts, type StateDistrictsOptions, type StateOptions, type Tariff, type TariffDeep, type TariffMeasure, type TariffOptions, type TariffSearch, type TariffSearchHit, type TariffSearchOptions, type Time, type TimeAtOptions, type TimeOptions, type Timezone, type TimezoneAtOptions, type TimezoneConversionTarget, type TimezoneConversionTargetDeep, type TimezoneDeep, type TimezoneNextDst, type TimezoneOptions, type Useragent, type UseragentBrowserBrand, type UseragentBrowserDeep, type UseragentDeep, type UseragentDeviceDeep, type UseragentEngineDeep, type UseragentOptions, type UseragentOsDeep, type Vat, type VatAddress, type VatDeep, type VatOptions, type Vin, type VinDeep, type VinOptions, type VinRecall, type Weather, type WeatherAir, type WeatherAlert, type WeatherCurrent, type WeatherCurrentDeep, type WeatherDay, type WeatherDeep, type WeatherForecastPeriod, type WeatherHistory, type WeatherHour, type WeatherMinute, type WeatherOptions, type WeatherStation, parseAPI };

package/dist/index.d.ts

@@ -250,14 +250,16 @@ interface PostalDistance {
     distance_mi: number;
 }
 interface EmailDeep {
-    deliverable: boolean;
-    catchall: boolean;
+    deliverable: boolean | null;
+    catchall: boolean | null;
 }
 interface Email {
     email: string;
     didyoumean: string | null;
     valid: boolean;
+    free: boolean;
     domain: string | null;
+    domain_type: 'academic' | 'government' | 'military' | null;
     domain_valid: boolean | null;
     role: boolean;
     disposable: boolean;
@@ -519,7 +521,10 @@ interface Bin {
     prefix: string | null;
     country: string | null;
     issuer: string | null;
+    /** Network key (visa, amex) or co-branded combination. */
     brand: string | null;
+    /** Display name for brand (American Express). */
+    brand_name: string | null;
     type: string | null;
     prepaid: boolean | null;
     deep?: Record<string, never>;
@@ -988,6 +993,16 @@ interface CountryDeep {
     /** Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable. */
     population_period?: string | null;
     area: number | null;
+    /** Land area in km2. */
+    land_area?: number | null;
+    /** Water area in km2. */
+    water_area?: number | null;
+    /** Coastline length in km. Zero is a known landlocked coastline. */
+    coastline?: number | null;
+    /** Mean elevation in metres above sea level. */
+    elevation?: number | null;
+    lowest_point?: CountryElevationPoint | null;
+    highest_point?: CountryElevationPoint | null;
     tld: string | null;
     /** Levy name, such as VAT, GST or sales tax. Null when unknown or not applicable. */
     tax?: string | null;
@@ -1013,6 +1028,11 @@ interface CountryDeep {
     fifa: string | null;
     plate: string | null;
 }
+interface CountryElevationPoint {
+    name: string | null;
+    /** Elevation in metres above sea level. Values below sea level are negative. */
+    elevation: number;
+}
 interface StateDeep {
     population: number | null;
     /** Reporting year or period for population (YYYY or YYYY-YYYY). Null when unknown or unverifiable. */
@@ -1129,12 +1149,14 @@ interface LanguageDeep {
     countries: string[];
 }
 interface NameDeep {
-    /** Name membership is independent of gender. */
-    known: boolean;
-    /** Associated countries, not the person's nationality. */
-    countries: string[];
     gender: 'male' | 'female' | null;
     salutation: 'Mr' | 'Ms' | null;
+    /** Compact name using CLDR formatting rules. */
+    short?: string | null;
+    /** Name formatted for a directory listing. */
+    directory?: string | null;
+    /** Name initials using CLDR formatting rules. */
+    initials?: string | null;
 }
 interface TimezoneDeep {
     name: string | null;
@@ -1233,6 +1255,10 @@ declare class ParseAPIError extends Error {
     readonly requestId: string | null;
     constructor(status: number, code: string, message: string, docs: string | null, requestId: string | null);
 }
+/** Optional output language for supported display fields. Input parsing stays unchanged. */
+interface LanguageOption {
+    lang?: string;
+}
 interface RequestOptions {
     /** Cancel this call, including any retry wait. */
     signal?: AbortSignal;
@@ -1252,36 +1278,36 @@ interface ParseAPIOptions {
     fetch?: typeof fetch;
 }
 /** IP enrichment is included with a paid plan. `deep` does not use a separate check meter. */
-type IpOptions = DeepOption & RequestOptions;
-type IpSelfOptions = DeepOption & RequestOptions;
-type ContinentOptions = RequestOptions;
-type ContinentCountriesOptions = RequestOptions;
+type IpOptions = LanguageOption & DeepOption & RequestOptions;
+type IpSelfOptions = LanguageOption & DeepOption & RequestOptions;
+type ContinentOptions = LanguageOption & RequestOptions;
+type ContinentCountriesOptions = LanguageOption & RequestOptions;
 type BlocOptions = RequestOptions;
-type BlocCountriesOptions = RequestOptions;
-type CountryOptions = DeepOption & RequestOptions;
-type CountryStatesOptions = RequestOptions;
-type StateOptions = {
+type BlocCountriesOptions = LanguageOption & RequestOptions;
+type CountryOptions = LanguageOption & DeepOption & RequestOptions;
+type CountryStatesOptions = LanguageOption & RequestOptions;
+type StateOptions = LanguageOption & {
     country?: string;
 } & DeepOption & RequestOptions;
-type StateDistrictsOptions = {
+type StateDistrictsOptions = LanguageOption & {
     country?: string;
 } & DeepOption & RequestOptions;
-type DistrictOptions = {
+type DistrictOptions = LanguageOption & {
     country?: string;
     state?: string;
 } & DeepOption & RequestOptions;
-type CityOptions = {
+type CityOptions = LanguageOption & {
     country?: string;
     state?: string;
 } & DeepOption & RequestOptions;
-type CityIdOptions = DeepOption & RequestOptions;
-type CitySearchOptions = {
+type CityIdOptions = LanguageOption & DeepOption & RequestOptions;
+type CitySearchOptions = LanguageOption & {
     country?: string;
     state?: string;
     limit?: number;
 } & DeepOption & RequestOptions;
-type CityNearestOptions = DeepOption & RequestOptions;
-type CityNearbyOptions = {
+type CityNearestOptions = LanguageOption & DeepOption & RequestOptions;
+type CityNearbyOptions = LanguageOption & {
     radius?: number;
     unit?: 'km' | 'mi';
     country?: string;
@@ -1289,15 +1315,15 @@ type CityNearbyOptions = {
     limit?: number;
 } & DeepOption & RequestOptions;
 /** Pass country when known. Codes shared by multiple countries need it. */
-type PostalOptions = {
+type PostalOptions = LanguageOption & {
     country?: string;
 } & DeepOption & RequestOptions;
-type PostalNearbyOptions = {
+type PostalNearbyOptions = LanguageOption & {
     country?: string;
     radius?: number;
     unit?: 'km' | 'mi';
 } & DeepOption & RequestOptions;
-type PostalDistanceOptions = {
+type PostalDistanceOptions = LanguageOption & {
     country?: string;
 } & DeepOption & RequestOptions;
 type AddressOptions = {
@@ -1316,7 +1342,7 @@ type AddressSearchOptions = {
     /** Actual end-user IP as an optional locality hint for server-side calls. */
     ip?: string;
 } & RequestOptions;
-type CompanyOptions = {
+type CompanyOptions = LanguageOption & {
     country?: string;
 } & DeepOption & RequestOptions;
 /** `deep: true` requests a metered deliverability check. No automatic retries by default. */
@@ -1329,7 +1355,7 @@ type VatOptions = {
 type IbanOptions = {
     country?: string;
 } & DeepOption & RequestOptions;
-type NpiOptions = DeepOption & RequestOptions;
+type NpiOptions = LanguageOption & DeepOption & RequestOptions;
 /** Country resolves national-number ambiguity. Deep adds numbering-plan geography on every plan. */
 type PhoneOptions = {
     country?: string;
@@ -1346,7 +1372,7 @@ type HlrOptions = {
     country?: string;
 } & DeepOption & RequestOptions;
 type DomainOptions = DeepOption & RequestOptions;
-type AsnOptions = RequestOptions;
+type AsnOptions = LanguageOption & RequestOptions;
 type MacOptions = RequestOptions;
 /** Card-prefix reference lookup. Deep returns an empty object on every plan. */
 type BinOptions = DeepOption & RequestOptions;
@@ -1356,7 +1382,7 @@ type MeasureOptions = {
     locale?: string;
     system?: 'us' | 'imperial';
 } & RequestOptions;
-type MeasureUnitsOptions = {
+type MeasureUnitsOptions = LanguageOption & {
     query?: string;
     type?: string;
     unit?: string;
@@ -1380,36 +1406,38 @@ type TariffOptions = {
     origin?: string;
 } & DeepOption & RequestOptions;
 type TariffSearchOptions = RequestOptions;
-type CurrencyOptions = DeepOption & RequestOptions;
+type CurrencyOptions = LanguageOption & DeepOption & RequestOptions;
 type CurrencyRateOptions = {
     date?: string;
     amount?: number;
 } & RequestOptions;
-type LanguageOptions = DeepOption & RequestOptions;
-/** Country is an ISO2 context for paid deep name evidence. */
+type LanguageOptions = LanguageOption & DeepOption & RequestOptions;
+/** Country scopes paid deep gender evidence. Name locale selects formatting rules without changing parsing. */
 type NameOptions = {
     country?: string;
+    /** CLDR name-formatting locale, such as en or ja. Defaults to en. */
+    name_locale?: string;
 } & DeepOption & RequestOptions;
-type TimeOptions = {
+type TimeOptions = LanguageOption & {
     at?: string;
     to?: string;
 } & DeepOption & RequestOptions;
-type TimeAtOptions = {
+type TimeAtOptions = LanguageOption & {
     at?: string;
     to?: string;
 } & DeepOption & RequestOptions;
-type TimezoneOptions = {
+type TimezoneOptions = LanguageOption & {
     at?: string;
     to?: string;
 } & DeepOption & RequestOptions;
-type TimezoneAtOptions = {
+type TimezoneAtOptions = LanguageOption & {
     at?: string;
 } & DeepOption & RequestOptions;
-type DateOptions = {
+type DateOptions = LanguageOption & {
     format?: 'mdy' | 'dmy';
     to?: string;
 } & DeepOption & RequestOptions;
-type DateTodayOptions = {
+type DateTodayOptions = LanguageOption & {
     to?: string;
 } & DeepOption & RequestOptions;
 type HolidayOptions = {
@@ -1418,14 +1446,14 @@ type HolidayOptions = {
 type HolidayDateOptions = RequestOptions;
 type ElevationOptions = RequestOptions;
 /** Resolve the country, state, district and timezone at coordinates. Deep adds terrain and compact nearest-city context on every plan. The timezone ID stays in core. The nearest city is null when none is within 200 km. */
-type PointOptions = DeepOption & RequestOptions;
+type PointOptions = LanguageOption & DeepOption & RequestOptions;
 /** Get current conditions in metric and imperial units. Paid deep adds specialist current measurements, forecasts and related detail. With deep, date selects a past UTC day (YYYY-MM-DD) in deep.history alongside current conditions. Date alone does not request history. */
 type WeatherOptions = DeepOption & {
     /** Past UTC day, YYYY-MM-DD. Requires paid deep and populates deep.history alongside current. */
     date?: string;
 } & RequestOptions;
-type EmojiOptions = DeepOption & RequestOptions;
-type EmojiSearchOptions = {
+type EmojiOptions = LanguageOption & DeepOption & RequestOptions;
+type EmojiSearchOptions = LanguageOption & {
     limit?: number;
 } & DeepOption & RequestOptions;
 interface DeepOption {
@@ -1538,4 +1566,4 @@ declare function parseAPI(apiKey?: string, options?: ParseAPIOptions): {
 };
 type ParseAPIClient = ReturnType<typeof parseAPI>;
 
-export { type Address, type AddressOptions, type AddressSearch, type AddressSearchOptions, type AddressSuggestion, type Asn, type AsnOptions, type Bin, type BinOptions, type Bloc, type BlocCountries, type BlocCountriesOptions, type BlocCountryItem, type BlocOptions, type Caller, type CallerOptions, type Carrier, type CarrierDeep, type CarrierOptions, type City, type CityDeep, type CityIdOptions, type CityNearby, type CityNearbyOptions, type CityNearest, type CityNearestOptions, type CityOptions, type CitySearch, type CitySearchOptions, type Company, type CompanyCountry, type CompanyDeep, type CompanyOptions, type Continent, type ContinentCountries, type ContinentCountriesOptions, type ContinentCountryItem, type ContinentOptions, type Country, type CountryDeep, type CountryEmergency, type CountryOptions, type CountryStateItem, type CountryStates, type CountryStatesOptions, type Currency, type CurrencyDeep, type CurrencyOptions, type CurrencyRate, type CurrencyRateOptions, type DateInfo, type DateInfoDeep, type DateOptions, type DateTodayOptions, type Deep, type District, type DistrictDeep, type DistrictOptions, type Dns, type DnsOptions, type DnsRecord, type Domain, type DomainDeep, type DomainOptions, type DomainRegistration, type Elevation, type ElevationOptions, type Email, type EmailDeep, type EmailOptions, type Emoji, type EmojiDeep, type EmojiOptions, type EmojiSearch, type EmojiSearchOptions, type EmojiSkin, type Hlr, type HlrDeep, type HlrOptions, type Holiday, type HolidayDate, type HolidayDateOptions, type HolidayOptions, type HolidayYear, type Iban, type IbanDeep, type IbanOptions, type Ip, type IpDeep, type IpOptions, type IpSelfOptions, type Language, type LanguageDeep, type LanguageOptions, type Mac, type MacOptions, type Measure, type MeasureChoice, type MeasureOptions, type MeasureUnit, type MeasureUnits, type MeasureUnitsOptions, type Mx, type MxOptions, type MxRecord, type Naics, type NaicsChild, type NaicsCorrection, type NaicsDeep, type NaicsExclusion, type NaicsMatch, type NaicsOptions, type NaicsSearch, type NaicsSearchItem, type NaicsSearchOptions, type Name, type NameDeep, type NameOptions, type Npi, type NpiDeep, type NpiEnrollment, type NpiOptions, type ParseAPIClient, ParseAPIError, type ParseAPIOptions, type Phone, type PhoneDeep, type PhoneOptions, type Point, type PointCity, type PointDeep, type PointOptions, type Postal, type PostalDeep, type PostalDistance, type PostalDistanceEnd, type PostalDistanceOptions, type PostalMetro, type PostalMetrosDeep, type PostalNearby, type PostalNearbyItem, type PostalNearbyOptions, type PostalOptions, type PropertyTax, type RequestOptions, type State, type StateDeep, type StateDistrictDeep, type StateDistrictItem, type StateDistricts, type StateDistrictsOptions, type StateOptions, type Tariff, type TariffDeep, type TariffMeasure, type TariffOptions, type TariffSearch, type TariffSearchHit, type TariffSearchOptions, type Time, type TimeAtOptions, type TimeOptions, type Timezone, type TimezoneAtOptions, type TimezoneConversionTarget, type TimezoneConversionTargetDeep, type TimezoneDeep, type TimezoneNextDst, type TimezoneOptions, type Useragent, type UseragentBrowserBrand, type UseragentBrowserDeep, type UseragentDeep, type UseragentDeviceDeep, type UseragentEngineDeep, type UseragentOptions, type UseragentOsDeep, type Vat, type VatAddress, type VatDeep, type VatOptions, type Vin, type VinDeep, type VinOptions, type VinRecall, type Weather, type WeatherAir, type WeatherAlert, type WeatherCurrent, type WeatherCurrentDeep, type WeatherDay, type WeatherDeep, type WeatherForecastPeriod, type WeatherHistory, type WeatherHour, type WeatherMinute, type WeatherOptions, type WeatherStation, parseAPI };
+export { type Address, type AddressOptions, type AddressSearch, type AddressSearchOptions, type AddressSuggestion, type Asn, type AsnOptions, type Bin, type BinOptions, type Bloc, type BlocCountries, type BlocCountriesOptions, type BlocCountryItem, type BlocOptions, type Caller, type CallerOptions, type Carrier, type CarrierDeep, type CarrierOptions, type City, type CityDeep, type CityIdOptions, type CityNearby, type CityNearbyOptions, type CityNearest, type CityNearestOptions, type CityOptions, type CitySearch, type CitySearchOptions, type Company, type CompanyCountry, type CompanyDeep, type CompanyOptions, type Continent, type ContinentCountries, type ContinentCountriesOptions, type ContinentCountryItem, type ContinentOptions, type Country, type CountryDeep, type CountryElevationPoint, type CountryEmergency, type CountryOptions, type CountryStateItem, type CountryStates, type CountryStatesOptions, type Currency, type CurrencyDeep, type CurrencyOptions, type CurrencyRate, type CurrencyRateOptions, type DateInfo, type DateInfoDeep, type DateOptions, type DateTodayOptions, type Deep, type District, type DistrictDeep, type DistrictOptions, type Dns, type DnsOptions, type DnsRecord, type Domain, type DomainDeep, type DomainOptions, type DomainRegistration, type Elevation, type ElevationOptions, type Email, type EmailDeep, type EmailOptions, type Emoji, type EmojiDeep, type EmojiOptions, type EmojiSearch, type EmojiSearchOptions, type EmojiSkin, type Hlr, type HlrDeep, type HlrOptions, type Holiday, type HolidayDate, type HolidayDateOptions, type HolidayOptions, type HolidayYear, type Iban, type IbanDeep, type IbanOptions, type Ip, type IpDeep, type IpOptions, type IpSelfOptions, type Language, type LanguageDeep, type LanguageOption, type LanguageOptions, type Mac, type MacOptions, type Measure, type MeasureChoice, type MeasureOptions, type MeasureUnit, type MeasureUnits, type MeasureUnitsOptions, type Mx, type MxOptions, type MxRecord, type Naics, type NaicsChild, type NaicsCorrection, type NaicsDeep, type NaicsExclusion, type NaicsMatch, type NaicsOptions, type NaicsSearch, type NaicsSearchItem, type NaicsSearchOptions, type Name, type NameDeep, type NameOptions, type Npi, type NpiDeep, type NpiEnrollment, type NpiOptions, type ParseAPIClient, ParseAPIError, type ParseAPIOptions, type Phone, type PhoneDeep, type PhoneOptions, type Point, type PointCity, type PointDeep, type PointOptions, type Postal, type PostalDeep, type PostalDistance, type PostalDistanceEnd, type PostalDistanceOptions, type PostalMetro, type PostalMetrosDeep, type PostalNearby, type PostalNearbyItem, type PostalNearbyOptions, type PostalOptions, type PropertyTax, type RequestOptions, type State, type StateDeep, type StateDistrictDeep, type StateDistrictItem, type StateDistricts, type StateDistrictsOptions, type StateOptions, type Tariff, type TariffDeep, type TariffMeasure, type TariffOptions, type TariffSearch, type TariffSearchHit, type TariffSearchOptions, type Time, type TimeAtOptions, type TimeOptions, type Timezone, type TimezoneAtOptions, type TimezoneConversionTarget, type TimezoneConversionTargetDeep, type TimezoneDeep, type TimezoneNextDst, type TimezoneOptions, type Useragent, type UseragentBrowserBrand, type UseragentBrowserDeep, type UseragentDeep, type UseragentDeviceDeep, type UseragentEngineDeep, type UseragentOptions, type UseragentOsDeep, type Vat, type VatAddress, type VatDeep, type VatOptions, type Vin, type VinDeep, type VinOptions, type VinRecall, type Weather, type WeatherAir, type WeatherAlert, type WeatherCurrent, type WeatherCurrentDeep, type WeatherDay, type WeatherDeep, type WeatherForecastPeriod, type WeatherHistory, type WeatherHour, type WeatherMinute, type WeatherOptions, type WeatherStation, parseAPI };

package/dist/index.js

@@ -1,5 +1,6 @@
 // src/index.ts
-var VERSION = "0.4.0";
+var VERSION = "1.0.0";
+var API_VERSION = "2.0.0";
 var DEFAULT_BASE_URL = "https://api.parseapi.com";
 var DEFAULT_TIMEOUT_MS = 1e4;
 var DEFAULT_RETRIES = 2;
@@ -89,6 +90,7 @@ function parseAPI(apiKey, options = {}) {
     validateTimeout(attemptTimeout);
     validateRetries(retries);
     const url = new URL(baseUrl + path);
+    if (controls.lang !== void 0) url.searchParams.set("lang", controls.lang);
     for (const [name, value] of Object.entries(query ?? {})) {
       if (value !== void 0) url.searchParams.set(name, String(value));
     }
@@ -104,7 +106,7 @@ function parseAPI(apiKey, options = {}) {
         try {
           res = await doFetch(url, {
             redirect: "manual",
-            headers: { "X-API-Key": key, "User-Agent": `parseapi-node/${VERSION}`, ...headers },
+            headers: { "X-API-Key": key, "User-Agent": `parseapi-node/${VERSION}`, ...headers, "Parse-Version": API_VERSION },
             signal: controller.signal
           });
         } catch (error) {
@@ -289,7 +291,7 @@ function parseAPI(apiKey, options = {}) {
       }
     ),
     language: (code, opts) => request(`/language/${enc(code)}`, deepQuery(opts), void 0, opts),
-    name: (name, opts) => request(`/name/${enc(name)}`, { country: opts?.country, ...deepQuery(opts) }, void 0, opts),
+    name: (name, opts) => request(`/name/${enc(name)}`, { country: opts?.country, ...deepQuery(opts), name_locale: opts?.name_locale }, void 0, opts),
     /** Current local time, UTC by default. With to, offsetless at is source wall time. */
     time: Object.assign(
       (timezone, opts) => request(timezone === void 0 ? "/time" : `/time/${enc(timezone)}`, { at: opts?.at, to: opts?.to, ...deepQuery(opts) }, void 0, opts),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@parseapi/sdk",
-	"version": "0.4.0",
+	"version": "1.0.0",
 	"description": "Official ParseAPI client for Node and TypeScript. One key, minimal JSON, fast.",
 	"keywords": [
 		"parseapi",