@parseapi/sdk 1.5.0 → 1.7.0

package/README.md

@@ -17,7 +17,7 @@ Get a key at [parseapi.com](https://parseapi.com). The client also reads `PARSEA
 
 ## API versions
 
-Version 1.5.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.
+Version 1.7.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.
 
 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.
 
@@ -166,7 +166,51 @@ DNS uses pooled requests on every plan. Omit `type` to check A, AAAA, CNAME, MX,
 
 ## Time
 
-`time` returns local ISO `at` with its UTC offset and integer Unix seconds in `unix`. The core `offset` preserves exact precision. Optional `deep.offset_seconds` gives the numeric offset, while `deep.offset_minutes` gives whole minutes. Historical offsets and ISO times can include offset seconds. Omitted `at` means now. With `to`, an offsetless `at` is source wall time. Otherwise it is UTC. Include an offset for repeated local times around a clock change. Current time and conversion use pooled requests on every plan. Coordinate clock fields can be null when the timezone is unknown. Existing `timezone` methods remain supported.
+`time` returns local ISO `at` with its UTC offset and integer Unix seconds in `unix`. The core `offset` preserves exact precision. Optional `deep.offset_seconds` gives the numeric offset, while `deep.offset_minutes` gives whole minutes. Historical offsets and ISO times can include offset seconds. Omitted `at` means now. With `to` or `targets`, an offsetless `at` is source wall time. Otherwise it is UTC. Include an offset for repeated local times around a clock change. Current time and conversion use pooled requests on every plan. Coordinate clock fields can be null when the timezone is unknown. Existing `timezone` methods remain supported.
+
+For an offsetless `at` with `to` or `targets`, choose how to handle a clock change with `disambiguation`. It applies to named-zone and coordinate Time calls.
+
+| Value | Repeated time | Skipped time |
+| --- | --- | --- |
+| `compatible` (default) | Earlier occurrence | Shift forward by the clock change |
+| `earlier` | Earlier occurrence | Shift backward by the clock change |
+| `later` | Later occurrence | Shift forward by the clock change |
+| `reject` | `400 ambiguous_time` | `400 nonexistent_time` |
+
+An explicit UTC offset selects an instant directly. For example, `2026-11-01T01:30:00-04:00` and `2026-11-01T01:30:00-05:00` identify the two New York occurrences. A valid `disambiguation` value has no effect on explicit instants, current-time requests or lookups without `to` or `targets`. For user-entered appointment times, start with `reject`. Handle `ambiguous_time` or `nonexistent_time` by collecting an explicit offset or an earlier/later choice from the user. Other malformed input still uses `invalid_request`.
+
+```ts
+const result = await parse.time('America/New_York', {
+  at: '2026-11-01T01:30:00', to: 'UTC', disambiguation: 'later',
+});
+console.log(result.to?.at); // 2026-11-01T06:30:00+00:00
+```
+
+Canonical Time `deep` includes the pinned rule edition in `deep.timezone_database_version` and source-wall resolution in `deep.resolution`. Resolution records `kind` (`unique`, `overlap` or `gap`), the selected policy, signed `adjustment_seconds`, and chronological alternatives with exact `at`, Unix seconds and UTC offset. Unique times have an empty alternatives list. Explicit instants, current time and lookups without conversion have null resolution. Destination detail stays compact.
+
+Search serving IANA IDs by city or region, or omit the query to list all (Go and Rust use an empty string). Discovery returns `timezone_database_version` and sorted `timezones`. No search matches returns `timezones: []`.
+
+Pass `targets` to convert one instant to 1-10 zones in a single pooled request. The native list preserves order and duplicates. Use `targets` instead of `to`. The response adds `targets`, with optional detail inside each target. Unknown source coordinates return `targets: null`. An unknown destination rejects the whole request with `not_found`. Omission keeps the original response shape.
+
+```ts
+const zones = await parse.time.zones('New York');
+const result = await parse.time('UTC', {
+  at: '2026-09-24T12:00:00Z', targets: ['America/New_York', 'Asia/Tokyo'],
+});
+console.log(zones.timezones, result.targets);
+```
+
+### Location inputs and timezone filters
+
+`parse.time(undefined, { iata: 'JFK', deep: true })` and `parse.time.zones(undefined, { country: 'US', dst: false, observes_dst: true, details: true })`.
+
+Choose one explicit location input: IP, exact city name or stable city ID, country, IATA airport, ICAO airport, port UN/LOCODE, or address. Country and state can narrow a city or address. State requires country. Address lookup requires US country context and a strict address-point match. Port lookup covers the reviewed port subset, not every assigned UN/LOCODE. IP lookup always uses the supplied IP.
+
+Location calls add `location` with `status`, `candidates`, `truncated`, `source` and the typed input. Check `status` before using the clock: ambiguous or missing locations retain null time fields. Candidate coordinates and IDs can also be null. A country with multiple timezones does not silently choose one. Named-zone and coordinate calls retain their existing signatures.
+
+Timezone discovery accepts country, IANA area, exact signed offset, abbreviation, DST-at-instant and observes-DST-during-year filters. `at` selects the common instant, `sort` selects timezone or offset order, and `details` adds `zones` rows plus the evaluation `at`. The default `timezones` list stays compact. False DST filters are sent explicitly. An abbreviation returns candidate zones rather than choosing one. Observes-DST uses the UTC calendar year containing `at`.
+
+Source deep adds `standard_offset`, `standard_offset_seconds`, signed `dst_offset_seconds` and `season`. Seasonal adjustments can be negative. `season` describes the current DST-flag interval, or the next within 400 days, with actual before/after transition facts and signed `change_seconds`. Unknown boundaries remain null. These fields are optional and nullable, and destination deep stays compact.
 
 ## Measurements
 
@@ -202,6 +246,12 @@ await parse.weather(40.7128, -74.006, { deep: true, date: '2026-08-15' });
 
 Tariff starts with the general schedule line. Paid deep adds units and the special and other schedule columns. An optional origin then resolves country-specific measures. The three calls below show those successive choices. Without origin, schedule detail is still returned and origin-dependent fields are null. A null effective rate is not a zero rate.
 
+Tariff lookup and search accept an optional `edition` fingerprint and `date` (`YYYY-MM-DD`). The edition pins exact immutable source bytes. A date is accepted only when verified source coverage exists. An edition without a date returns undated schedule context (`date: null`). Default requests use today. Paid detail exposes an open-string `reason` when `effective_rate` is null, including `incomplete_coverage`. A null rate never means zero. Explicit selections fail with `tariff_selection_mismatch` if an older server ignores the requested scope.
+
+Origin means where the goods originate, not where they ship from. The effective rate covers matched stored schedule measures only. It is not complete duty or landed cost.
+
+Codes contain 4, 6, 8 or 10 ASCII digits; dots and whitespace are optional. Search returns up to 20 description matches with parent `lineage` so a result named "Other" has context. Search is not product classification. In deep, `measures: null` means origin-dependent measures were not resolved. `measures: []` means the resolved lookup found none.
+
 ```ts
 await parse.tariff('8471.30.01.00');
 await parse.tariff('8471.30.01.00', { deep: true });

package/dist/index.cjs

@@ -24,7 +24,7 @@ __export(index_exports, {
   parseAPI: () => parseAPI
 });
 module.exports = __toCommonJS(index_exports);
-var VERSION = "1.5.0";
+var VERSION = "1.7.0";
 var API_VERSION = "2.0.0";
 var DEFAULT_BASE_URL = "https://api.parseapi.com";
 var DEFAULT_TIMEOUT_MS = 1e4;
@@ -49,6 +49,12 @@ var ParseAPIError = class extends Error {
     this.requestId = requestId;
   }
 };
+function tariffSelection(result, opts) {
+  if ((opts?.edition !== void 0 || opts?.date !== void 0) && (typeof result.edition !== "string" || result.edition.length !== 64 || !/^[a-f0-9]{64}$/.test(result.edition) || opts.edition !== void 0 && result.edition !== opts.edition || (opts.date !== void 0 ? result.date !== opts.date : result.date != null))) {
+    throw new ParseAPIError(0, "tariff_selection_mismatch", "Tariff response did not confirm the requested edition/date. The server may not support this selection.", null, null);
+  }
+  return result;
+}
 function env(name) {
   return typeof process !== "undefined" ? process.env?.[name] : void 0;
 }
@@ -317,9 +323,9 @@ function parseAPI(apiKey, options = {}) {
     ),
     /** Look up the general US duty schedule line. Paid deep adds units and the special and other schedule columns. Add origin with deep to resolve country-specific measures. Without origin, schedule detail remains available and origin-dependent fields are null. A null effective rate is not a zero rate. */
     tariff: Object.assign(
-      (code, opts) => request(`/tariff/${enc(code)}`, { origin: opts?.origin, ...deepQuery(opts) }, void 0, opts),
+      (code, opts) => request(`/tariff/${enc(code)}`, { origin: opts?.origin, edition: opts?.edition, date: opts?.date, ...deepQuery(opts) }, void 0, opts).then((result) => tariffSelection(result, opts)),
       {
-        search: (query, opts) => request("/tariff", { q: query }, void 0, opts)
+        search: (query, opts) => request("/tariff", { q: query, edition: opts?.edition, date: opts?.date }, void 0, opts).then((result) => tariffSelection(result, opts))
       }
     ),
     currency: Object.assign(
@@ -333,11 +339,13 @@ 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), name_locale: opts?.name_locale }, void 0, opts),
-    /** Current local time, UTC by default. With to, offsetless at is source wall time. */
+    /** Current local time, UTC by default. With to or targets, 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),
+      (timezone, opts) => request(timePath(timezone), { ...timeSource(timezone, opts), at: opts?.at, to: opts?.to, targets: timeTargets(opts?.targets, opts?.to), disambiguation: opts?.disambiguation, ...deepQuery(opts) }, void 0, opts),
       {
-        at: (lat, lon, opts) => request("/time", { lat, lon, at: opts?.at, to: opts?.to, ...deepQuery(opts) }, void 0, opts)
+        /** Search serving timezone IDs. Omit query to list all. */
+        zones: (query, opts) => request("/time/zones", { q: query, country: opts?.country, area: opts?.area, offset: opts?.offset, abbreviation: opts?.abbreviation, dst: opts?.dst === void 0 ? void 0 : String(opts.dst), observes_dst: opts?.observes_dst === void 0 ? void 0 : String(opts.observes_dst), at: opts?.at, details: opts?.details, sort: opts?.sort }, void 0, opts),
+        at: (lat, lon, opts) => request("/time", { lat, lon, at: opts?.at, to: opts?.to, targets: timeTargets(opts?.targets, opts?.to), disambiguation: opts?.disambiguation, ...deepQuery(opts) }, void 0, opts)
       }
     ),
     timezone: Object.assign(
@@ -379,6 +387,24 @@ function parseAPI(apiKey, options = {}) {
     )
   };
 }
+function timeSource(timezone, options = {}) {
+  const values = { ip: options.ip, city: options.city, country: options.country, state: options.state, iata: options.iata, icao: options.icao, unlocode: options.unlocode, address: options.address };
+  const primary = [options.ip, options.city, options.iata, options.icao, options.unlocode, options.address].filter((value) => value !== void 0);
+  const present = Object.values(values).some((value) => value !== void 0);
+  if (Object.values(values).some((value) => value !== void 0 && (typeof value !== "string" || !value.trim())) || timezone !== void 0 && present || primary.length > 1 || options.country !== void 0 && primary.length > 0 && options.city === void 0 && options.address === void 0 || options.state !== void 0 && (options.city === void 0 && options.address === void 0 || options.country === void 0) || options.address !== void 0 && options.country === void 0) throw new TypeError("Pass one Time source, using country only with city or address and state only with city or address and country.");
+  return values;
+}
+function timePath(timezone) {
+  if (timezone !== void 0 && ["zones", "help"].includes(timezone.trim().toLowerCase())) throw new TypeError("Time source must be an IANA timezone ID. Use timezone discovery to list IDs.");
+  return timezone === void 0 ? "/time" : `/time/${encodeURIComponent(timezone)}`;
+}
+function timeTargets(targets, to) {
+  if (targets === void 0) return void 0;
+  if (to !== void 0 || !Array.isArray(targets) || targets.length < 1 || targets.length > 10 || Array.from(targets).some((zone) => typeof zone !== "string" || !zone.trim() || zone.includes(","))) {
+    throw new TypeError("Time targets requires 1 to 10 timezone IDs and cannot be combined with to.");
+  }
+  return targets.join(",");
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ParseAPIError,

package/dist/index.d.cts

@@ -377,11 +377,13 @@ interface TariffMeasure {
     conditional?: boolean | null;
 }
 interface TariffDeep {
+    /** Open-string explanation when effective_rate is null. */
+    reason?: string | null;
     /** The origin country the measures were resolved for. */
     origin?: string | null;
-    /** Composed ad valorem percent. Null when the components do not compose cleanly. */
+    /** Composed ad valorem percent for matched stored measures only, not complete duty or landed cost. 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. */
+    /** Matching stored Chapter 99 schedule measures for this code and goods origin. */
     measures?: TariffMeasure[] | null;
     /** Units of quantity (No., kg). */
     units: string[];
@@ -391,6 +393,10 @@ interface TariffDeep {
     other: string | null;
 }
 interface Tariff {
+    /** Exact immutable edition. Older servers may omit it. */
+    edition?: string;
+    /** Answering date, or null for an undated edition query. */
+    date?: string | null;
     /** Normalized code with dots (8471.30.01.00). */
     hts: string;
     /** The schedule line verbatim. */
@@ -407,8 +413,14 @@ interface TariffSearchHit {
     hts: string;
     description: string;
     general: string | null;
+    /** Parent descriptions, outermost first. Older responses may omit this context. */
+    lineage?: string[] | null;
 }
 interface TariffSearch {
+    /** Exact immutable edition. Older servers may omit it. */
+    edition?: string;
+    /** Answering date, or null for an undated edition query. */
+    date?: string | null;
     q: string;
     revision: string;
     /** Up to 20 tariff lines, best match first. */
@@ -695,8 +707,47 @@ interface Timezone {
     to?: TimezoneConversionTarget | null;
     deep?: Deep<TimezoneDeep>;
 }
-/** Current time and timezone facts. Null clock fields mean the coordinates did not resolve. */
+/** Current time and timezone facts. Unresolved or ambiguous sources keep clock fields null. */
 interface Time extends Timezone {
+    /** Present only for explicit location selectors. Ambiguous or missing results retain null clock fields. */
+    location?: TimeLocation;
+    /** With targets only. Order and duplicates are preserved. Null means the source timezone is unresolved. */
+    targets?: TimezoneConversionTarget[] | null;
+}
+/** Serving timezone identifiers and their pinned rule edition. */
+interface TimeZones {
+    timezone_database_version: string;
+    timezones: string[];
+    /** Present with details=true. The one instant used for all rows. */
+    at?: string;
+    zones?: TimeZoneEntry[];
+}
+interface TimeZoneEntry {
+    timezone: string;
+    countries: string[];
+    area: string | null;
+    abbreviation: string;
+    offset: string;
+    offset_seconds: number;
+    dst: boolean;
+    observes_dst: boolean;
+}
+interface TimeTransitionState {
+    at?: string | null;
+    offset?: string | null;
+    offset_seconds?: number | null;
+    abbreviation?: string | null;
+    dst?: boolean | null;
+}
+interface TimeTransition {
+    at?: string | null;
+    before?: TimeTransitionState | null;
+    after?: TimeTransitionState | null;
+    change_seconds?: number | null;
+}
+interface TimeSeason {
+    start?: TimeTransition | null;
+    end?: TimeTransition | null;
 }
 /** The other side of a timezone conversion. `at` is the converted wall time. */
 interface TimezoneConversionTarget {
@@ -1208,7 +1259,31 @@ interface NameDeep {
     /** Name initials using CLDR formatting rules. */
     initials?: string | null;
 }
+/** How an offsetless source wall time selected an instant. */
+interface TimeResolution {
+    kind?: string | null;
+    policy?: string | null;
+    /** Signed wall-clock adjustment. Zero for unique and overlapping times. */
+    adjustment_seconds?: number | null;
+    /** Chronological alternatives. Empty means the wall time is unique. */
+    alternatives?: TimeResolutionAlternative[] | null;
+}
+interface TimeResolutionAlternative {
+    at?: string | null;
+    unix?: number | null;
+    offset?: string | null;
+}
 interface TimezoneDeep {
+    /** Rule-defined standard offset. Seasonal changes may be negative. */
+    standard_offset?: string | null;
+    standard_offset_seconds?: number | null;
+    dst_offset_seconds?: number | null;
+    /** Current DST-flag interval, or the next within 400 days. */
+    season?: TimeSeason | null;
+    /** Pinned rules used by canonical Time. */
+    timezone_database_version?: string | null;
+    /** Null when no offsetless conversion was resolved. */
+    resolution?: TimeResolution | null;
     name: string | null;
     /** Whole minutes, truncated toward zero for historical second offsets. */
     offset_minutes: number | null;
@@ -1292,6 +1367,26 @@ interface PropertyTax {
     /** Reporting period, YYYY-YYYY. Monetary amounts use the final year of this period. */
     period: string;
 }
+interface TimeLocationInput {
+    type: string;
+    value: string;
+}
+interface TimeLocationCandidate {
+    id: string | null;
+    name: string | null;
+    country: string | null;
+    state: string | null;
+    timezone: string | null;
+    latitude: number | null;
+    longitude: number | null;
+}
+interface TimeLocation {
+    input: TimeLocationInput;
+    status: string;
+    candidates: TimeLocationCandidate[];
+    truncated: boolean;
+    source: string;
+}
 
 /** A proposed task contains operation counts, never lookup inputs. */
 interface PreflightOperation {
@@ -1554,8 +1649,15 @@ type NaicsSearchOptions = {
 type TariffOptions = {
     /** Origin country (ISO2). With paid deep, resolves country-specific measures. */
     origin?: string;
+    /** Exact immutable edition fingerprint. */
+    edition?: string;
+    /** YYYY-MM-DD, accepted only with verified source coverage. */
+    date?: string;
 } & DeepOption & RequestOptions;
-type TariffSearchOptions = RequestOptions;
+type TariffSearchOptions = {
+    edition?: string;
+    date?: string;
+} & RequestOptions;
 type CurrencyOptions = LanguageOption & DeepOption & RequestOptions;
 type CurrencyRateOptions = {
     date?: string;
@@ -1568,14 +1670,50 @@ type NameOptions = {
     /** CLDR name-formatting locale, such as en or ja. Defaults to en. */
     name_locale?: string;
 } & DeepOption & RequestOptions;
+/** Local time or same-instant conversion. Optional reference detail is pooled on every plan. */
 type TimeOptions = LanguageOption & {
+    ip?: string;
+    city?: string;
+    country?: string;
+    state?: string;
+    iata?: string;
+    icao?: string;
+    unlocode?: string;
+    address?: string;
+    /** ISO timestamp. With to or targets, an offsetless value is source wall time. Otherwise it is UTC. */
     at?: string;
+    /** Destination IANA timezone. The target has the same unix instant. */
     to?: string;
+    /** One to ten destination IDs, preserving order and duplicates. Use instead of to. */
+    targets?: readonly string[];
+    /** Offsetless conversion clock changes: compatible (default), earlier, later, or reject. Explicit offsets select the instant directly. */
+    disambiguation?: 'compatible' | 'earlier' | 'later' | 'reject';
 } & DeepOption & RequestOptions;
+/** Local time or same-instant conversion. Optional reference detail is pooled on every plan. */
 type TimeAtOptions = LanguageOption & {
+    /** ISO timestamp. With to or targets, an offsetless value is source wall time. Otherwise it is UTC. */
     at?: string;
+    /** Destination IANA timezone. The target has the same unix instant. */
     to?: string;
+    /** One to ten destination IDs, preserving order and duplicates. Use instead of to. */
+    targets?: readonly string[];
+    /** Offsetless conversion clock changes: compatible (default), earlier, later, or reject. Explicit offsets select the instant directly. */
+    disambiguation?: 'compatible' | 'earlier' | 'later' | 'reject';
 } & DeepOption & RequestOptions;
+/** Filter supported identifiers at one instant. Abbreviations return candidates, never an inferred zone. */
+type TimeZonesOptions = {
+    country?: string;
+    area?: string;
+    /** Exact signed UTC offset, such as +05:45 or +00:09:21. */
+    offset?: string;
+    abbreviation?: string;
+    dst?: boolean;
+    /** Whether a DST-flagged state occurs in the UTC calendar year containing at. */
+    observes_dst?: boolean;
+    at?: string;
+    details?: boolean;
+    sort?: 'timezone' | 'offset';
+} & RequestOptions;
 type TimezoneOptions = LanguageOption & {
     at?: string;
     to?: string;
@@ -1696,8 +1834,10 @@ declare function parseAPI(apiKey?: string, options?: ParseAPIOptions): {
     };
     language: (code: string, opts?: LanguageOptions) => Promise<Language>;
     name: (name: string, opts?: NameOptions) => Promise<Name>;
-    /** Current local time, UTC by default. With to, offsetless at is source wall time. */
+    /** Current local time, UTC by default. With to or targets, offsetless at is source wall time. */
     time: ((timezone?: string, opts?: TimeOptions) => Promise<Time>) & {
+        /** Search serving timezone IDs. Omit query to list all. */
+        zones: (query?: string, opts?: TimeZonesOptions) => Promise<TimeZones>;
         at: (lat: number, lon: number, opts?: TimeAtOptions) => Promise<Time>;
     };
     timezone: ((id: string, opts?: TimezoneOptions) => Promise<Timezone>) & {
@@ -1725,4 +1865,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 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 ElevationLocations, 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 PostalLocality, type PostalMetro, type PostalMetrosDeep, type PostalNearby, type PostalNearbyItem, type PostalNearbyOptions, type PostalOptions, type Preflight, type PreflightCost, type PreflightEmailCapacity, type PreflightOperation, type PreflightOperationEstimate, type PreflightPooledCapacity, type PreflightSpendCapacity, type PreflightTask, type PropertyTax, type RequestOptions, type Stack, type StackOptions, type StackTechnology, 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 ElevationLocations, 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 PostalLocality, type PostalMetro, type PostalMetrosDeep, type PostalNearby, type PostalNearbyItem, type PostalNearbyOptions, type PostalOptions, type Preflight, type PreflightCost, type PreflightEmailCapacity, type PreflightOperation, type PreflightOperationEstimate, type PreflightPooledCapacity, type PreflightSpendCapacity, type PreflightTask, type PropertyTax, type RequestOptions, type Stack, type StackOptions, type StackTechnology, 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 TimeLocation, type TimeLocationCandidate, type TimeLocationInput, type TimeOptions, type TimeResolution, type TimeResolutionAlternative, type TimeSeason, type TimeTransition, type TimeTransitionState, type TimeZoneEntry, type TimeZones, type TimeZonesOptions, 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

@@ -377,11 +377,13 @@ interface TariffMeasure {
     conditional?: boolean | null;
 }
 interface TariffDeep {
+    /** Open-string explanation when effective_rate is null. */
+    reason?: string | null;
     /** The origin country the measures were resolved for. */
     origin?: string | null;
-    /** Composed ad valorem percent. Null when the components do not compose cleanly. */
+    /** Composed ad valorem percent for matched stored measures only, not complete duty or landed cost. 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. */
+    /** Matching stored Chapter 99 schedule measures for this code and goods origin. */
     measures?: TariffMeasure[] | null;
     /** Units of quantity (No., kg). */
     units: string[];
@@ -391,6 +393,10 @@ interface TariffDeep {
     other: string | null;
 }
 interface Tariff {
+    /** Exact immutable edition. Older servers may omit it. */
+    edition?: string;
+    /** Answering date, or null for an undated edition query. */
+    date?: string | null;
     /** Normalized code with dots (8471.30.01.00). */
     hts: string;
     /** The schedule line verbatim. */
@@ -407,8 +413,14 @@ interface TariffSearchHit {
     hts: string;
     description: string;
     general: string | null;
+    /** Parent descriptions, outermost first. Older responses may omit this context. */
+    lineage?: string[] | null;
 }
 interface TariffSearch {
+    /** Exact immutable edition. Older servers may omit it. */
+    edition?: string;
+    /** Answering date, or null for an undated edition query. */
+    date?: string | null;
     q: string;
     revision: string;
     /** Up to 20 tariff lines, best match first. */
@@ -695,8 +707,47 @@ interface Timezone {
     to?: TimezoneConversionTarget | null;
     deep?: Deep<TimezoneDeep>;
 }
-/** Current time and timezone facts. Null clock fields mean the coordinates did not resolve. */
+/** Current time and timezone facts. Unresolved or ambiguous sources keep clock fields null. */
 interface Time extends Timezone {
+    /** Present only for explicit location selectors. Ambiguous or missing results retain null clock fields. */
+    location?: TimeLocation;
+    /** With targets only. Order and duplicates are preserved. Null means the source timezone is unresolved. */
+    targets?: TimezoneConversionTarget[] | null;
+}
+/** Serving timezone identifiers and their pinned rule edition. */
+interface TimeZones {
+    timezone_database_version: string;
+    timezones: string[];
+    /** Present with details=true. The one instant used for all rows. */
+    at?: string;
+    zones?: TimeZoneEntry[];
+}
+interface TimeZoneEntry {
+    timezone: string;
+    countries: string[];
+    area: string | null;
+    abbreviation: string;
+    offset: string;
+    offset_seconds: number;
+    dst: boolean;
+    observes_dst: boolean;
+}
+interface TimeTransitionState {
+    at?: string | null;
+    offset?: string | null;
+    offset_seconds?: number | null;
+    abbreviation?: string | null;
+    dst?: boolean | null;
+}
+interface TimeTransition {
+    at?: string | null;
+    before?: TimeTransitionState | null;
+    after?: TimeTransitionState | null;
+    change_seconds?: number | null;
+}
+interface TimeSeason {
+    start?: TimeTransition | null;
+    end?: TimeTransition | null;
 }
 /** The other side of a timezone conversion. `at` is the converted wall time. */
 interface TimezoneConversionTarget {
@@ -1208,7 +1259,31 @@ interface NameDeep {
     /** Name initials using CLDR formatting rules. */
     initials?: string | null;
 }
+/** How an offsetless source wall time selected an instant. */
+interface TimeResolution {
+    kind?: string | null;
+    policy?: string | null;
+    /** Signed wall-clock adjustment. Zero for unique and overlapping times. */
+    adjustment_seconds?: number | null;
+    /** Chronological alternatives. Empty means the wall time is unique. */
+    alternatives?: TimeResolutionAlternative[] | null;
+}
+interface TimeResolutionAlternative {
+    at?: string | null;
+    unix?: number | null;
+    offset?: string | null;
+}
 interface TimezoneDeep {
+    /** Rule-defined standard offset. Seasonal changes may be negative. */
+    standard_offset?: string | null;
+    standard_offset_seconds?: number | null;
+    dst_offset_seconds?: number | null;
+    /** Current DST-flag interval, or the next within 400 days. */
+    season?: TimeSeason | null;
+    /** Pinned rules used by canonical Time. */
+    timezone_database_version?: string | null;
+    /** Null when no offsetless conversion was resolved. */
+    resolution?: TimeResolution | null;
     name: string | null;
     /** Whole minutes, truncated toward zero for historical second offsets. */
     offset_minutes: number | null;
@@ -1292,6 +1367,26 @@ interface PropertyTax {
     /** Reporting period, YYYY-YYYY. Monetary amounts use the final year of this period. */
     period: string;
 }
+interface TimeLocationInput {
+    type: string;
+    value: string;
+}
+interface TimeLocationCandidate {
+    id: string | null;
+    name: string | null;
+    country: string | null;
+    state: string | null;
+    timezone: string | null;
+    latitude: number | null;
+    longitude: number | null;
+}
+interface TimeLocation {
+    input: TimeLocationInput;
+    status: string;
+    candidates: TimeLocationCandidate[];
+    truncated: boolean;
+    source: string;
+}
 
 /** A proposed task contains operation counts, never lookup inputs. */
 interface PreflightOperation {
@@ -1554,8 +1649,15 @@ type NaicsSearchOptions = {
 type TariffOptions = {
     /** Origin country (ISO2). With paid deep, resolves country-specific measures. */
     origin?: string;
+    /** Exact immutable edition fingerprint. */
+    edition?: string;
+    /** YYYY-MM-DD, accepted only with verified source coverage. */
+    date?: string;
 } & DeepOption & RequestOptions;
-type TariffSearchOptions = RequestOptions;
+type TariffSearchOptions = {
+    edition?: string;
+    date?: string;
+} & RequestOptions;
 type CurrencyOptions = LanguageOption & DeepOption & RequestOptions;
 type CurrencyRateOptions = {
     date?: string;
@@ -1568,14 +1670,50 @@ type NameOptions = {
     /** CLDR name-formatting locale, such as en or ja. Defaults to en. */
     name_locale?: string;
 } & DeepOption & RequestOptions;
+/** Local time or same-instant conversion. Optional reference detail is pooled on every plan. */
 type TimeOptions = LanguageOption & {
+    ip?: string;
+    city?: string;
+    country?: string;
+    state?: string;
+    iata?: string;
+    icao?: string;
+    unlocode?: string;
+    address?: string;
+    /** ISO timestamp. With to or targets, an offsetless value is source wall time. Otherwise it is UTC. */
     at?: string;
+    /** Destination IANA timezone. The target has the same unix instant. */
     to?: string;
+    /** One to ten destination IDs, preserving order and duplicates. Use instead of to. */
+    targets?: readonly string[];
+    /** Offsetless conversion clock changes: compatible (default), earlier, later, or reject. Explicit offsets select the instant directly. */
+    disambiguation?: 'compatible' | 'earlier' | 'later' | 'reject';
 } & DeepOption & RequestOptions;
+/** Local time or same-instant conversion. Optional reference detail is pooled on every plan. */
 type TimeAtOptions = LanguageOption & {
+    /** ISO timestamp. With to or targets, an offsetless value is source wall time. Otherwise it is UTC. */
     at?: string;
+    /** Destination IANA timezone. The target has the same unix instant. */
     to?: string;
+    /** One to ten destination IDs, preserving order and duplicates. Use instead of to. */
+    targets?: readonly string[];
+    /** Offsetless conversion clock changes: compatible (default), earlier, later, or reject. Explicit offsets select the instant directly. */
+    disambiguation?: 'compatible' | 'earlier' | 'later' | 'reject';
 } & DeepOption & RequestOptions;
+/** Filter supported identifiers at one instant. Abbreviations return candidates, never an inferred zone. */
+type TimeZonesOptions = {
+    country?: string;
+    area?: string;
+    /** Exact signed UTC offset, such as +05:45 or +00:09:21. */
+    offset?: string;
+    abbreviation?: string;
+    dst?: boolean;
+    /** Whether a DST-flagged state occurs in the UTC calendar year containing at. */
+    observes_dst?: boolean;
+    at?: string;
+    details?: boolean;
+    sort?: 'timezone' | 'offset';
+} & RequestOptions;
 type TimezoneOptions = LanguageOption & {
     at?: string;
     to?: string;
@@ -1696,8 +1834,10 @@ declare function parseAPI(apiKey?: string, options?: ParseAPIOptions): {
     };
     language: (code: string, opts?: LanguageOptions) => Promise<Language>;
     name: (name: string, opts?: NameOptions) => Promise<Name>;
-    /** Current local time, UTC by default. With to, offsetless at is source wall time. */
+    /** Current local time, UTC by default. With to or targets, offsetless at is source wall time. */
     time: ((timezone?: string, opts?: TimeOptions) => Promise<Time>) & {
+        /** Search serving timezone IDs. Omit query to list all. */
+        zones: (query?: string, opts?: TimeZonesOptions) => Promise<TimeZones>;
         at: (lat: number, lon: number, opts?: TimeAtOptions) => Promise<Time>;
     };
     timezone: ((id: string, opts?: TimezoneOptions) => Promise<Timezone>) & {
@@ -1725,4 +1865,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 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 ElevationLocations, 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 PostalLocality, type PostalMetro, type PostalMetrosDeep, type PostalNearby, type PostalNearbyItem, type PostalNearbyOptions, type PostalOptions, type Preflight, type PreflightCost, type PreflightEmailCapacity, type PreflightOperation, type PreflightOperationEstimate, type PreflightPooledCapacity, type PreflightSpendCapacity, type PreflightTask, type PropertyTax, type RequestOptions, type Stack, type StackOptions, type StackTechnology, 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 ElevationLocations, 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 PostalLocality, type PostalMetro, type PostalMetrosDeep, type PostalNearby, type PostalNearbyItem, type PostalNearbyOptions, type PostalOptions, type Preflight, type PreflightCost, type PreflightEmailCapacity, type PreflightOperation, type PreflightOperationEstimate, type PreflightPooledCapacity, type PreflightSpendCapacity, type PreflightTask, type PropertyTax, type RequestOptions, type Stack, type StackOptions, type StackTechnology, 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 TimeLocation, type TimeLocationCandidate, type TimeLocationInput, type TimeOptions, type TimeResolution, type TimeResolutionAlternative, type TimeSeason, type TimeTransition, type TimeTransitionState, type TimeZoneEntry, type TimeZones, type TimeZonesOptions, 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,5 @@
 // src/index.ts
-var VERSION = "1.5.0";
+var VERSION = "1.7.0";
 var API_VERSION = "2.0.0";
 var DEFAULT_BASE_URL = "https://api.parseapi.com";
 var DEFAULT_TIMEOUT_MS = 1e4;
@@ -24,6 +24,12 @@ var ParseAPIError = class extends Error {
     this.requestId = requestId;
   }
 };
+function tariffSelection(result, opts) {
+  if ((opts?.edition !== void 0 || opts?.date !== void 0) && (typeof result.edition !== "string" || result.edition.length !== 64 || !/^[a-f0-9]{64}$/.test(result.edition) || opts.edition !== void 0 && result.edition !== opts.edition || (opts.date !== void 0 ? result.date !== opts.date : result.date != null))) {
+    throw new ParseAPIError(0, "tariff_selection_mismatch", "Tariff response did not confirm the requested edition/date. The server may not support this selection.", null, null);
+  }
+  return result;
+}
 function env(name) {
   return typeof process !== "undefined" ? process.env?.[name] : void 0;
 }
@@ -292,9 +298,9 @@ function parseAPI(apiKey, options = {}) {
     ),
     /** Look up the general US duty schedule line. Paid deep adds units and the special and other schedule columns. Add origin with deep to resolve country-specific measures. Without origin, schedule detail remains available and origin-dependent fields are null. A null effective rate is not a zero rate. */
     tariff: Object.assign(
-      (code, opts) => request(`/tariff/${enc(code)}`, { origin: opts?.origin, ...deepQuery(opts) }, void 0, opts),
+      (code, opts) => request(`/tariff/${enc(code)}`, { origin: opts?.origin, edition: opts?.edition, date: opts?.date, ...deepQuery(opts) }, void 0, opts).then((result) => tariffSelection(result, opts)),
       {
-        search: (query, opts) => request("/tariff", { q: query }, void 0, opts)
+        search: (query, opts) => request("/tariff", { q: query, edition: opts?.edition, date: opts?.date }, void 0, opts).then((result) => tariffSelection(result, opts))
       }
     ),
     currency: Object.assign(
@@ -308,11 +314,13 @@ 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), name_locale: opts?.name_locale }, void 0, opts),
-    /** Current local time, UTC by default. With to, offsetless at is source wall time. */
+    /** Current local time, UTC by default. With to or targets, 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),
+      (timezone, opts) => request(timePath(timezone), { ...timeSource(timezone, opts), at: opts?.at, to: opts?.to, targets: timeTargets(opts?.targets, opts?.to), disambiguation: opts?.disambiguation, ...deepQuery(opts) }, void 0, opts),
       {
-        at: (lat, lon, opts) => request("/time", { lat, lon, at: opts?.at, to: opts?.to, ...deepQuery(opts) }, void 0, opts)
+        /** Search serving timezone IDs. Omit query to list all. */
+        zones: (query, opts) => request("/time/zones", { q: query, country: opts?.country, area: opts?.area, offset: opts?.offset, abbreviation: opts?.abbreviation, dst: opts?.dst === void 0 ? void 0 : String(opts.dst), observes_dst: opts?.observes_dst === void 0 ? void 0 : String(opts.observes_dst), at: opts?.at, details: opts?.details, sort: opts?.sort }, void 0, opts),
+        at: (lat, lon, opts) => request("/time", { lat, lon, at: opts?.at, to: opts?.to, targets: timeTargets(opts?.targets, opts?.to), disambiguation: opts?.disambiguation, ...deepQuery(opts) }, void 0, opts)
       }
     ),
     timezone: Object.assign(
@@ -354,6 +362,24 @@ function parseAPI(apiKey, options = {}) {
     )
   };
 }
+function timeSource(timezone, options = {}) {
+  const values = { ip: options.ip, city: options.city, country: options.country, state: options.state, iata: options.iata, icao: options.icao, unlocode: options.unlocode, address: options.address };
+  const primary = [options.ip, options.city, options.iata, options.icao, options.unlocode, options.address].filter((value) => value !== void 0);
+  const present = Object.values(values).some((value) => value !== void 0);
+  if (Object.values(values).some((value) => value !== void 0 && (typeof value !== "string" || !value.trim())) || timezone !== void 0 && present || primary.length > 1 || options.country !== void 0 && primary.length > 0 && options.city === void 0 && options.address === void 0 || options.state !== void 0 && (options.city === void 0 && options.address === void 0 || options.country === void 0) || options.address !== void 0 && options.country === void 0) throw new TypeError("Pass one Time source, using country only with city or address and state only with city or address and country.");
+  return values;
+}
+function timePath(timezone) {
+  if (timezone !== void 0 && ["zones", "help"].includes(timezone.trim().toLowerCase())) throw new TypeError("Time source must be an IANA timezone ID. Use timezone discovery to list IDs.");
+  return timezone === void 0 ? "/time" : `/time/${encodeURIComponent(timezone)}`;
+}
+function timeTargets(targets, to) {
+  if (targets === void 0) return void 0;
+  if (to !== void 0 || !Array.isArray(targets) || targets.length < 1 || targets.length > 10 || Array.from(targets).some((zone) => typeof zone !== "string" || !zone.trim() || zone.includes(","))) {
+    throw new TypeError("Time targets requires 1 to 10 timezone IDs and cannot be combined with to.");
+  }
+  return targets.join(",");
+}
 export {
   ParseAPIError,
   parseAPI

package/package.json

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