@parseapi/sdk 1.6.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.6.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.
 
@@ -246,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.6.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(

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. */
@@ -1637,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;

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. */
@@ -1637,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;

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-var VERSION = "1.6.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(

package/package.json

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