@parseapi/sdk 1.6.0 → 1.8.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.
 
@@ -87,9 +87,9 @@ await parse.ip('8.8.8.8');
 await parse.ip.self();
 await parse.email('hello@gmail.com');
 await parse.vat('DE136695976');
-await parse.iban('DE89370400440532013000');
-await parse.bin('424242');
-await parse.npi('1881018208');
+await parse.bank('DE89370400440532013000');
+await parse.card('424242');
+await parse.provider('1881018208');
 await parse.phone('+14155552671');
 await parse.carrier('+14155552671');
 await parse.caller('+14155552671');
@@ -143,16 +143,18 @@ await parse.mx('example.com');
 await parse.dns('example.com');
 await parse.dns('_dmarc.example.com', { type: 'TXT' });
 await parse.useragent(uaString);
-await parse.vin('1HGCM82633A004352');
-await parse.naics('541511');
-await parse.naics.search('coffee shop', { limit: 5 });
+await parse.vehicle('1HGCM82633A004352');
+await parse.industry('541511');
+await parse.industry.search('coffee shop', { limit: 5 });
 await parse.tariff('8471.30.01.00');
 await parse.tariff.search('sunglasses');
 await parse.emoji('rocket');
 await parse.emoji.search('fire');
 ```
 
-NAICS paid deep records include classification `deep.exclusions`, each with a description and linked codes. Generic exclusions can have no linked codes. Omitted or null exclusions in older responses remain unknown. Search results also include `match`: the matched `field` (`name`, `term` or `naics`) and `text`, plus `corrections` with `from` and `to` tokens for typo fallback. Corrections are empty for exact, plural and prefix matches. Direct code lookups omit `match`. Older responses may omit it.
+The existing NAICS lookup and search methods remain available as compatibility names for Industry.
+
+Industry paid deep records include classification `deep.exclusions`, each with a description and linked codes. Generic exclusions can have no linked codes. Omitted or null exclusions in older responses remain unknown. Search results also include `match`: the matched `field` (`name`, `term` or `naics`) and `text`, plus `corrections` with `from` and `to` tokens for typo fallback. Corrections are empty for exact, plural and prefix matches. Direct code lookups omit `match`. Older responses may omit it.
 
 Responses are typed, plain JSON data. `country.states('US')` requests the states directly; it does not fetch a country first. Optional arguments go in the final options object, so new options can be added without changing your existing calls.
 
@@ -246,6 +248,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 });
@@ -256,6 +264,32 @@ Address search uses context from the form: prefer postal, or city and state. An
 
 HLR reports status at the last check. `live` means assigned and `connected` means reachable at that check. Cached results may be returned. Null means unconfirmed. Deep diagnostics stay within the same metered lookup.
 
+Bank returns core `checks` for input, country, length, structure, checksum and national rules, plus an `issues` list. States are `passed`, `failed`, `not_checked` or `not_supported`. Unsupported national checking is not a failure. `valid` covers the implemented format and checksum rules, not account existence, ownership or payment reachability. Directory names and BICs may be null independently. Older responses may omit `checks` and `issues`, and future states and issue codes remain strings. Pass the original input unchanged so the API can report invalid characters. Deep `account` remains the BBAN remainder.
+
+Bank inputs use `POST /bank` JSON bodies, keeping IBAN and account values out of request URLs. Pass original strings; the server owns normalization and validation. Avoid logging request bodies. IBAN deep can include `directory` with the immutable `edition`, resolved `country` and actual `match` grain (`bank`, `branch`, `prefix` or `none`); it is absent if no directory lookup ran. A match does not prove complete country coverage or payment reachability.
+
+Use country requirements to build supported input fields. US ACH has an explicit helper with no deep option. It checks the routing format/ABA checksum and account-field syntax; `account_checksum` is `not_supported`. It preserves account characters and leading zeros. A nullable bank name is routing-directory identity, not account existence, ownership or ACH eligibility. The examples below are synthetic test inputs, not payment instructions.
+
+```ts
+await parse.bankRequirements('US', { format: 'us_ach' });
+await parse.bankUsAch({ routing: '011000015', account: '0001234567' });
+```
+
+## Provider lookup
+
+```ts
+const provider = await parse.provider('1881018208');
+const profile = await parse.provider('1881018208', { deep: true });
+```
+
+Pass the original NPI as a string. `valid` checks its format and checksum; `registered` means a match in the stored NPPES snapshot. `active` reflects recorded NPI deactivation, not licensure. `excluded` is an NPI-only OIG LEIE match; `false` is not a complete exclusion clearance. These directory facts do not verify credentials, current practice contact or payment eligibility.
+
+Invalid input returns `valid: false` with unknown provider fields. A checksum-valid number missing from the snapshot returns `registered: false`; unavailable storage remains an API error. Preserve `null` as unknown.
+
+The default pooled lookup includes provider identity, specialty and practice contact where held. Paid `deep` adds `deactivated_at`, `medicare`, `opt_out` and `enrollments` from stored source files, with no separate check meter or live verification. `enrollments: null` means unavailable; `[]` means no enrollment rows are returned. The API omits unrequested `deep` and returns `{}` when requested on Free.
+
+Paid Deep also returns `taxonomies` in published order, with taxonomy code, specialty label, primary flag and provider-reported license number/state, plus `enumerated_at`, `updated_at` and `reactivated_at` record dates. Reported licenses are not verified licenses. Null lists mean unavailable; empty lists mean the edition contains no entries. Core `sources` is available on every plan: NPPES, LEIE, PECOS and opt-out each have nullable edition metadata (`edition`, `published_at`, `through`, `imported_at`). Provider record dates are separate from source publication and completed import dates. Older responses may omit these additions. Edition details remain null until a verified source is served.
+
 ## Deep
 
 Choose enrichment for the question you need answered.
@@ -266,10 +300,11 @@ Choose enrichment for the question you need answered.
 | Domain | Registration dates, registrar, status and DNSSEC, included with a paid plan. Use `dns` for DNS records and `mx` for mail routing. |
 | Email | A metered mailbox check with deliverability, catch-all, status, reason and address hints, using included email checks or enabled on-demand usage. |
 | VAT | A metered registry check where supported, using included VAT checks or enabled on-demand usage. |
-| Phone, Time, Date, Currency, Language, Emoji, IBAN, Point | Optional detail in the same pooled request on every plan. |
+| Phone, Time, Date, Currency, Language, Emoji, Bank, Point | Optional detail in the same pooled request on every plan. |
 | Country, State, District, City, Postal | The place profile on paid plans, including demographic and tax facts where held. |
-| Name, NAICS | Name evidence or the industry definition profile on paid plans. |
-| VIN, NPI, Tariff, Company | The complete product detail bag on paid plans. |
+| Name, Industry | Name evidence or the industry definition profile on paid plans. |
+| NPI | Deactivation date, Medicare enrollment, opt-out and enrollment rows from stored sources on paid plans. Exclusion evidence stays core. |
+| Vehicle, Tariff, Company | The complete product detail bag on paid plans. |
 | Weather | Specialist current measurements and the existing forecast, alert, air and history bag on paid plans. |
 | Carrier, HLR | Optional diagnostic detail within the same metered core unit, including Free allowance units. No second gate or additional check. |
 
@@ -325,16 +360,40 @@ Ordinary lookups retry network failures, 429, and 500/502/503/504 responses twic
 
 An explicit `retries` setting on the client or call overrides those defaults. Another attempt can consume additional usage if the earlier response was lost. Cancellation stops the request and any retry wait. Automatic redirects are disabled.
 
+Automatic retries wait at most five seconds per attempt. A longer valid `Retry-After` returns the original API error immediately without retrying early. Read `retryAfter` on the error for the original header, or null when absent.
+
 ## Docs
 
 Full field reference for every endpoint: [parseapi.com/docs](https://parseapi.com/docs)
 
-BIN lookup accepts 6-11 digits as a string, including leading zeros. Spaces and hyphens are accepted. `prefix` is the actual longest match and can be shorter than the input. Unknown reference fields are null. `deep` adds an empty object on every plan.
+## Card
+
+Send 2–11 leading digits as a string. Core returns `bin`, `brand`, `brand_name`
+and a CDN SVG `logo`. Brand detection uses reviewed network rules independently
+of issuer records. Unknown or ambiguous prefixes return null brand fields and a
+generic logo; a known network without reviewed artwork also uses the generic logo.
+
+Optional Deep adds `prefix`, `issuer`, `country`, `type` and `prepaid`, included
+in the same pooled request on every plan. Six or more digits enable directory
+matching. Fewer digits return all-null Deep fields. Compare `deep.prefix` with
+`bin`: equal is an exact recorded match; shorter is broader; null is no match.
+The longest row wins, including null fields. `prepaid: null` means unknown, not
+false. This is partial reference data, not card validity or payment acceptance.
+
+```javascript
+const card = await parse.card('51');
+console.log(card.brand, card.logo);
+const details = await parse.card('43737400', { deep: true });
+console.log(details.deep?.prefix, details.deep?.issuer);
+```
 
+Leading zeros are preserved. Only ASCII spaces, tabs, CR, LF and hyphens are
+removed; raw input is limited to 64 characters. Invalid prefixes are rejected
+before dispatch, accepted input is forwarded unchanged. Never send a full card number.
 
 ## Optional detail
 
-The default response answers the common task. Ask for `deep` when you need more detail about that same result. Core fields stay equal. City, NAICS and Emoji searches put detail inside each result. Postal nearby and distance put metropolitan detail beside the entity it describes. Time conversion keeps target detail in `to.deep`; only the source has `deep.next_dst`.
+The default response answers the common task. Ask for `deep` when you need more detail about that same result. Core fields stay equal. City, Industry and Emoji searches put detail inside each result. Postal nearby and distance put metropolitan detail beside the entity it describes. Time conversion keeps target detail in `to.deep`; only the source has `deep.next_dst`.
 
 ```ts
 const basic = await parse.time('America/New_York');
@@ -355,3 +414,5 @@ Pass a public hostname without a scheme, path, port or IP address. Stack returns
 Successful checks may be reused for up to 24 hours. `pretty` optionally formats the wire JSON. Stack uses your plan's request allowance and API version 2.0.0 selected by this client.
 
 Stack defaults to 35 seconds per attempt so a first scan has time to finish. Other lookups retain their 10-second default. An explicit client timeout applies to every operation; JavaScript also supports a per-call `timeoutMs` override.
+
+Vehicle lookups use `vin` as the input and response field. Existing VIN methods remain available for compatibility.

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.8.0";
 var API_VERSION = "2.0.0";
 var DEFAULT_BASE_URL = "https://api.parseapi.com";
 var DEFAULT_TIMEOUT_MS = 1e4;
@@ -40,15 +40,24 @@ var ParseAPIError = class extends Error {
   docs;
   /** Send this if you contact support */
   requestId;
-  constructor(status, code, message, docs, requestId) {
+  /** Original Retry-After response header, when supplied. */
+  retryAfter;
+  constructor(status, code, message, docs, requestId, retryAfter = null) {
     super(message);
     this.name = "ParseAPIError";
     this.status = status;
     this.code = code;
     this.docs = docs;
     this.requestId = requestId;
+    this.retryAfter = retryAfter;
   }
 };
+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;
 }
@@ -85,16 +94,20 @@ function metered(path, query) {
 }
 function retryDelayMs(attempt, retryAfter) {
   if (retryAfter) {
-    const seconds = Number(retryAfter);
-    if (Number.isFinite(seconds) && seconds >= 0) {
-      return Math.min(seconds * 1e3, RETRY_AFTER_CAP_MS);
+    const value = retryAfter.trim();
+    if (/^[0-9]+(?:\.[0-9]+)?$/.test(value)) {
+      const seconds = Number(value);
+      return seconds > RETRY_AFTER_CAP_MS / 1e3 ? null : seconds * 1e3;
     }
-    if (Number.isNaN(seconds)) {
-      const date = Date.parse(retryAfter);
-      if (Number.isFinite(date)) return Math.min(Math.max(date - Date.now(), 0), RETRY_AFTER_CAP_MS);
+    if (/^[A-Za-z]{3,9},? /.test(value)) {
+      const date = Date.parse(value);
+      if (Number.isFinite(date)) {
+        const delay = Math.max(date - Date.now(), 0);
+        return delay > RETRY_AFTER_CAP_MS ? null : delay;
+      }
     }
   }
-  return Math.random() * 250 * 2 ** attempt;
+  return Math.random() * Math.min(250 * 2 ** Math.min(attempt, 16), RETRY_AFTER_CAP_MS);
 }
 function parseAPI(apiKey, options = {}) {
   const key = apiKey || env("PARSEAPI_KEY");
@@ -127,7 +140,7 @@ function parseAPI(apiKey, options = {}) {
       const onAbort = () => controller.abort(signal.reason);
       signal?.addEventListener("abort", onAbort, { once: true });
       const timer = setTimeout(() => controller.abort(new DOMException("Request timed out", "TimeoutError")), attemptTimeout);
-      let retryAfter = null;
+      let retryDelay;
       try {
         let res;
         try {
@@ -153,8 +166,8 @@ function parseAPI(apiKey, options = {}) {
             res = void 0;
           }
         }
-        if (res && RETRY_STATUS.has(res.status) && attempt < retries) {
-          retryAfter = res.headers.get("Retry-After");
+        if (res) retryDelay = retryDelayMs(attempt, res.headers.get("Retry-After"));
+        if (res && RETRY_STATUS.has(res.status) && attempt < retries && retryDelay !== null) {
           await res.body?.cancel().catch(() => {
           });
         } else if (res) {
@@ -171,14 +184,15 @@ function parseAPI(apiKey, options = {}) {
             typeof body2.code === "string" ? body2.code : "unknown_error",
             typeof body2.message === "string" ? body2.message : `Request failed with status ${res.status}`,
             typeof body2.docs === "string" ? body2.docs : null,
-            typeof body2.request_id === "string" ? body2.request_id : null
+            typeof body2.request_id === "string" ? body2.request_id : null,
+            res.headers.get("Retry-After")
           );
         }
       } finally {
         clearTimeout(timer);
         signal?.removeEventListener("abort", onAbort);
       }
-      await sleep(retryDelayMs(attempt, retryAfter), signal);
+      await sleep(retryDelay ?? retryDelayMs(attempt, null), signal);
     }
   }
   const enc = encodeURIComponent;
@@ -192,6 +206,12 @@ function parseAPI(apiKey, options = {}) {
     for (const [name, value2] of Object.entries(query)) url.searchParams.set(name, String(value2));
     return !numericJson && url.href.length <= 8e3 ? request("/elevation", query, void 0, opts) : request("/elevation", void 0, void 0, opts, { [selector]: coordinates, ...sampling });
   }
+  const industry = Object.assign(
+    (code, opts) => request(`/industry/${enc(code)}`, deepQuery(opts), void 0, opts),
+    {
+      search: (query, opts) => request("/industry", { q: query, limit: opts?.limit, ...deepQuery(opts) }, void 0, opts)
+    }
+  );
   return {
     /** Estimate task access, capacity and additional charges. Requires a secret key. Reserves no units or money and does not enforce the supplied budget. */
     preflight: (task, opts) => request("/preflight", void 0, void 0, opts, task),
@@ -277,8 +297,16 @@ function parseAPI(apiKey, options = {}) {
       from: opts?.from,
       ...deepQuery(opts)
     }, void 0, opts),
+    // Keep existing callers on their established HTTP contracts.
     iban: (iban, opts) => request(`/iban/${enc(iban)}`, { country: opts?.country, ...deepQuery(opts) }, void 0, opts),
+    bin: (bin, opts) => request(`/bin/${enc(bin)}`, { deep: opts?.deep }, void 0, opts),
     npi: (npi, opts) => request(`/npi/${enc(npi)}`, deepQuery(opts), void 0, opts),
+    bank: (iban, opts) => request("/bank", void 0, void 0, opts, { iban, country: opts?.country, deep: opts?.deep }),
+    /** Check US routing/account syntax using POST. Does not verify ownership, existence or ACH eligibility. */
+    bankUsAch: (input, opts) => request("/bank", void 0, void 0, opts, { format: "us_ach", country: "US", routing: input.routing, account: input.account }),
+    /** Describe supported input fields and check scope; this does not establish country directory coverage. */
+    bankRequirements: (country, opts) => request("/bank/requirements", { country, format: opts?.format }, void 0, opts),
+    provider: (npi, opts) => request(`/provider/${enc(npi)}`, deepQuery(opts), void 0, opts),
     /** Parse a phone number and its formats. Pass country for national numbers when needed. Deep adds numbering-plan geography. */
     phone: (number, opts) => request(`/phone/${enc(number)}`, { country: opts?.country, ...deepQuery(opts) }, void 0, opts),
     /** Request a metered carrier lookup. No automatic retries by default. */
@@ -293,8 +321,13 @@ function parseAPI(apiKey, options = {}) {
     domain: (domain, opts) => request(`/domain/${enc(domain)}`, deepQuery(opts), void 0, opts),
     asn: (asn, opts) => request(`/asn/${enc(asn)}`, void 0, void 0, opts),
     mac: (mac, opts) => request(`/mac/${enc(mac)}`, void 0, void 0, opts),
-    /** Look up a 6-11 digit card prefix. Keep leading zeros in the input string. */
-    bin: (bin, opts) => request(`/bin/${enc(bin)}`, { deep: opts?.deep }, void 0, opts),
+    /** Look up a 2-11 digit card prefix. Keep leading zeros in the input string. */
+    card: async (bin, opts) => {
+      if (typeof bin !== "string" || bin.length > 64 || !/^[0-9]{2,11}$/.test(bin.replace(/[ \t\r\n-]/g, ""))) {
+        throw new TypeError("parseAPI: Card requires a string containing 2 to 11 digits. Send a prefix only.");
+      }
+      return request(`/card/${enc(bin)}`, deepQuery(opts), void 0, opts);
+    },
     /** Parse a measurement or convert it to `to`. Without `to`, use its type's canonical unit. Invalid input is plain data with `valid: false`. */
     measure: Object.assign(
       (measure, opts) => request(`/measure/${enc(measure)}`, { to: opts?.to, locale: opts?.locale, system: opts?.system }, void 0, opts),
@@ -307,19 +340,19 @@ function parseAPI(apiKey, options = {}) {
     dns: (domain, opts) => request(`/dns/${enc(domain)}`, { type: opts?.type }, void 0, opts),
     mx: (domain, opts) => request(`/mx/${enc(domain)}`, void 0, void 0, opts),
     useragent: (ua, opts) => request("/useragent", deepQuery(opts), { "User-Agent": ua }, opts),
+    /** Identify a vehicle by VIN. Paid deep adds specifications and model-level recall campaigns. */
+    vehicle: (vin, opts) => request(`/vehicle/${enc(vin)}`, deepQuery(opts), void 0, opts),
+    /** Compatibility entry for VIN callers. */
     vin: (vin, opts) => request(`/vin/${enc(vin)}`, deepQuery(opts), void 0, opts),
     /** US NAICS 2022 definitions and hierarchy. */
-    naics: Object.assign(
-      (code, opts) => request(`/naics/${enc(code)}`, deepQuery(opts), void 0, opts),
-      {
-        search: (query, opts) => request("/naics", { q: query, limit: opts?.limit, ...deepQuery(opts) }, void 0, opts)
-      }
-    ),
+    industry,
+    /** Compatibility name for industry. */
+    naics: industry,
     /** 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(