@parseapi/sdk 0.3.2 → 1.0.0

package/dist/index.js

@@ -1,5 +1,6 @@
 // src/index.ts
-var VERSION = "0.3.2";
+var VERSION = "1.0.0";
+var API_VERSION = "2.0.0";
 var DEFAULT_BASE_URL = "https://api.parseapi.com";
 var DEFAULT_TIMEOUT_MS = 1e4;
 var DEFAULT_RETRIES = 2;
@@ -89,6 +90,7 @@ function parseAPI(apiKey, options = {}) {
     validateTimeout(attemptTimeout);
     validateRetries(retries);
     const url = new URL(baseUrl + path);
+    if (controls.lang !== void 0) url.searchParams.set("lang", controls.lang);
     for (const [name, value] of Object.entries(query ?? {})) {
       if (value !== void 0) url.searchParams.set(name, String(value));
     }
@@ -104,7 +106,7 @@ function parseAPI(apiKey, options = {}) {
         try {
           res = await doFetch(url, {
             redirect: "manual",
-            headers: { "X-API-Key": key, "User-Agent": `parseapi-node/${VERSION}`, ...headers },
+            headers: { "X-API-Key": key, "User-Agent": `parseapi-node/${VERSION}`, ...headers, "Parse-Version": API_VERSION },
             signal: controller.signal
           });
         } catch (error) {
@@ -154,9 +156,11 @@ function parseAPI(apiKey, options = {}) {
   const enc = encodeURIComponent;
   const deepQuery = (opts) => opts?.deep ? { deep: true } : {};
   return {
+    /** Look up an IP. `deep: true` adds enrichment included with a paid plan, without a separate check meter. */
     ip: Object.assign(
       (ip, opts) => request(`/ip/${enc(ip)}`, deepQuery(opts), void 0, opts),
       {
+        /** Look up the public IP making this request. On a server, this is the server's IP. */
         self: (opts) => request("/ip", deepQuery(opts), void 0, opts)
       }
     ),
@@ -173,69 +177,104 @@ function parseAPI(apiKey, options = {}) {
       }
     ),
     country: Object.assign(
-      (code, opts) => request(`/country/${enc(code)}`, void 0, void 0, opts),
+      (code, opts) => request(`/country/${enc(code)}`, deepQuery(opts), void 0, opts),
       {
         states: (code, opts) => request(`/country/${enc(code)}/states`, void 0, void 0, opts)
       }
     ),
     state: Object.assign(
-      (code, opts) => request(`/state/${enc(code)}`, { country: opts?.country }, void 0, opts),
+      (code, opts) => request(`/state/${enc(code)}`, { country: opts?.country, ...deepQuery(opts) }, void 0, opts),
       {
-        districts: (code, opts) => request(`/state/${enc(code)}/districts`, { country: opts?.country }, void 0, opts)
+        districts: (code, opts) => request(`/state/${enc(code)}/districts`, { country: opts?.country, ...deepQuery(opts) }, void 0, opts)
       }
     ),
-    district: (code, opts) => request(`/district/${enc(code)}`, { country: opts?.country, state: opts?.state }, void 0, opts),
+    district: (code, opts) => request(`/district/${enc(code)}`, { country: opts?.country, state: opts?.state, ...deepQuery(opts) }, void 0, opts),
     city: Object.assign(
-      (name, opts) => request(`/city/${enc(name)}`, { country: opts?.country, state: opts?.state }, void 0, opts),
+      (name, opts) => request(`/city/${enc(name)}`, { country: opts?.country, state: opts?.state, ...deepQuery(opts) }, void 0, opts),
       {
-        id: (id, opts) => request(`/city/id/${enc(id)}`, void 0, void 0, opts),
-        search: (query, opts) => request("/city", { q: query, country: opts?.country, state: opts?.state, limit: opts?.limit }, void 0, opts),
-        nearest: (lat, lon, opts) => request("/city", { lat, lon }, void 0, opts),
+        id: (id, opts) => request(`/city/id/${enc(id)}`, deepQuery(opts), void 0, opts),
+        search: (query, opts) => request("/city", { q: query, country: opts?.country, state: opts?.state, limit: opts?.limit, ...deepQuery(opts) }, void 0, opts),
+        nearest: (lat, lon, opts) => request("/city", { lat, lon, ...deepQuery(opts) }, void 0, opts),
         nearby: (name, opts) => request(`/city/${enc(name)}/nearby`, {
           radius: opts?.radius,
           unit: opts?.unit,
           country: opts?.country,
           state: opts?.state,
-          limit: opts?.limit
+          limit: opts?.limit,
+          ...deepQuery(opts)
         }, void 0, opts)
       }
     ),
+    /** Look up a postal area. Pass country when known. Check nullable latitude/longitude before another location lookup. */
     postal: Object.assign(
-      (code, opts) => request(`/postal/${enc(code)}`, { country: opts?.country }, void 0, opts),
+      (code, opts) => request(`/postal/${enc(code)}`, { country: opts?.country, ...deepQuery(opts) }, void 0, opts),
       {
         nearby: (code, opts) => request(`/postal/${enc(code)}/nearby`, {
           country: opts?.country,
           radius: opts?.radius,
-          unit: opts?.unit
+          unit: opts?.unit,
+          ...deepQuery(opts)
         }, void 0, opts),
-        distance: (from, to, opts) => request(`/postal/${enc(from)}/distance/${enc(to)}`, { country: opts?.country }, void 0, opts)
+        distance: (from, to, opts) => request(`/postal/${enc(from)}/distance/${enc(to)}`, { country: opts?.country, ...deepQuery(opts) }, void 0, opts)
       }
     ),
     address: Object.assign(
       (address, opts) => request(`/address/${enc(address)}`, { country: opts?.country, ...deepQuery(opts) }, void 0, opts),
       {
+        /** Find address suggestions using the context supplied. Prefer postal, or city and state, from the form. ip is an optional end-user locality hint for server-side calls. An empty result has reason more_input, missing_context or no_matches. Suggestions have reason null. Operational failures are errors. */
         search: (query, opts) => request("/address", { q: query, country: opts?.country, postal: opts?.postal, city: opts?.city, state: opts?.state, ip: opts?.ip }, void 0, opts)
       }
     ),
     company: (number, opts) => request(`/company/${enc(number)}`, { country: opts?.country, ...deepQuery(opts) }, void 0, opts),
+    /**
+     * Parse an email and check its format and domain.
+     * `deep: true` explicitly requests a metered deliverability check using included checks or enabled on-demand usage.
+     * Deep checks default to one attempt. An explicit retry count can repeat paid usage.
+     */
     email: (email, opts) => request(`/email/${enc(email)}`, deepQuery(opts), void 0, opts),
+    /** Check VAT format and checksum. `deep: true` requests a metered registry check where supported, with no automatic retries by default. */
     vat: (number, opts) => request(`/vat/${enc(number)}`, {
       country: opts?.country,
       from: opts?.from,
       ...deepQuery(opts)
     }, void 0, opts),
-    iban: (iban, opts) => request(`/iban/${enc(iban)}`, { country: opts?.country }, void 0, opts),
+    iban: (iban, opts) => request(`/iban/${enc(iban)}`, { country: opts?.country, ...deepQuery(opts) }, void 0, opts),
     npi: (npi, opts) => request(`/npi/${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),
-    carrier: (number, opts) => request(`/carrier/${enc(number)}`, { country: opts?.country }, void 0, opts),
+    /** Request a metered carrier lookup. No automatic retries by default. */
+    carrier: (number, opts) => request(`/carrier/${enc(number)}`, { country: opts?.country, ...deepQuery(opts) }, void 0, opts),
+    /** Request a metered caller-name lookup for a NANP number. No automatic retries by default. */
     caller: (number, opts) => request(`/caller/${enc(number)}`, { country: opts?.country }, void 0, opts),
-    hlr: (number, opts) => request(`/hlr/${enc(number)}`, { country: opts?.country }, void 0, opts),
+    /** Look up phone status at the last check. Live means assigned and connected means reachable at that check. Cached results may be returned. Null means unconfirmed. Deep adds network diagnostics within the same metered lookup. No automatic retries by default. */
+    hlr: (number, opts) => request(`/hlr/${enc(number)}`, { country: opts?.country, ...deepQuery(opts) }, void 0, opts),
+    /** Check whether a domain is registered. Deep adds registration dates, registrar, status and DNSSEC on paid plans. */
     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),
+    /** 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),
+      {
+        /** Discover reviewed units. Pass `unit` to find compatible conversion targets. */
+        units: (opts) => request("/measure/units", { q: opts?.query, type: opts?.type, unit: opts?.unit }, void 0, opts)
+      }
+    ),
+    /** Look up DNS records with TTLs. Type selects the question and may include its CNAME chain. Pooled on every plan. */
+    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),
     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)
+      }
+    ),
+    /** 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),
       {
@@ -243,7 +282,7 @@ function parseAPI(apiKey, options = {}) {
       }
     ),
     currency: Object.assign(
-      (code, opts) => request(`/currency/${enc(code)}`, void 0, void 0, opts),
+      (code, opts) => request(`/currency/${enc(code)}`, deepQuery(opts), void 0, opts),
       {
         rate: (base, quote, opts) => request(`/currency/${enc(base)}/${enc(quote)}`, {
           date: opts?.date,
@@ -251,18 +290,25 @@ function parseAPI(apiKey, options = {}) {
         }, void 0, opts)
       }
     ),
-    language: (code, opts) => request(`/language/${enc(code)}`, void 0, void 0, opts),
-    name: (name, opts) => request(`/name/${enc(name)}`, void 0, void 0, opts),
+    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. */
+    time: Object.assign(
+      (timezone, opts) => request(timezone === void 0 ? "/time" : `/time/${enc(timezone)}`, { at: opts?.at, to: opts?.to, ...deepQuery(opts) }, void 0, opts),
+      {
+        at: (lat, lon, opts) => request("/time", { lat, lon, at: opts?.at, to: opts?.to, ...deepQuery(opts) }, void 0, opts)
+      }
+    ),
     timezone: Object.assign(
-      (id, opts) => request(`/timezone/${enc(id)}`, { at: opts?.at, to: opts?.to }, void 0, opts),
+      (id, opts) => request(`/timezone/${enc(id)}`, { at: opts?.at, to: opts?.to, ...deepQuery(opts) }, void 0, opts),
       {
-        at: (lat, lon, opts) => request("/timezone", { lat, lon, at: opts?.at }, void 0, opts)
+        at: (lat, lon, opts) => request("/timezone", { lat, lon, at: opts?.at, ...deepQuery(opts) }, void 0, opts)
       }
     ),
     date: Object.assign(
-      (date, opts) => request(`/date/${enc(date)}`, { format: opts?.format, to: opts?.to }, void 0, opts),
+      (date, opts) => request(`/date/${enc(date)}`, { format: opts?.format, to: opts?.to, ...deepQuery(opts) }, void 0, opts),
       {
-        today: (opts) => request("/date", { to: opts?.to }, void 0, opts)
+        today: (opts) => request("/date", { to: opts?.to, ...deepQuery(opts) }, void 0, opts)
       }
     ),
     holiday: Object.assign(
@@ -272,12 +318,14 @@ function parseAPI(apiKey, options = {}) {
       }
     ),
     elevation: (lat, lon, opts) => request("/elevation", { lat, lon }, void 0, opts),
+    /** Resolve the country, state, district and timezone at coordinates. Deep adds terrain and compact nearest-city context on every plan. The timezone ID stays in core. The nearest city is null when none is within 200 km. */
     point: (lat, lon, opts) => request("/point", { lat, lon, ...deepQuery(opts) }, void 0, opts),
+    /** Get current conditions in metric and imperial units. Paid deep adds specialist current measurements, forecasts and related detail. With deep, date selects a past UTC day (YYYY-MM-DD) in deep.history alongside current conditions. Date alone does not request history. */
     weather: (lat, lon, opts) => request("/weather", { lat, lon, date: opts?.date, ...deepQuery(opts) }, void 0, opts),
     emoji: Object.assign(
-      (emoji, opts) => request(`/emoji/${enc(emoji)}`, void 0, void 0, opts),
+      (emoji, opts) => request(`/emoji/${enc(emoji)}`, deepQuery(opts), void 0, opts),
       {
-        search: (query, opts) => request("/emoji", { q: query, limit: opts?.limit }, void 0, opts)
+        search: (query, opts) => request("/emoji", { q: query, limit: opts?.limit, ...deepQuery(opts) }, void 0, opts)
       }
     )
   };
@@ -286,3 +334,4 @@ export {
   ParseAPIError,
   parseAPI
 };
+/*! You found Dev. https://parseapi.com/dev */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@parseapi/sdk",
-	"version": "0.3.2",
+	"version": "1.0.0",
 	"description": "Official ParseAPI client for Node and TypeScript. One key, minimal JSON, fast.",
 	"keywords": [
 		"parseapi",
@@ -59,6 +59,9 @@
 		"@types/node": "^22.10.0",
 		"tsup": "^8.3.5",
 		"typescript": "^5.7.0",
-		"vitest": "^2.1.8"
+		"vitest": "^4.1.11"
+	},
+	"overrides": {
+		"esbuild": "0.27.2"
 	}
 }