@parseapi/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 parseAPI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# @parseapi/sdk
+
+Official parseAPI client for Node and TypeScript.
+
+```bash
+npm install @parseapi/sdk
+```
+
+```ts
+import { parseAPI } from '@parseapi/sdk';
+
+const parse = parseAPI('your-api-key');
+const country = await parse.country('US');
+```
+
+Get a key at [parseapi.com](https://parseapi.com). The client also reads `PARSEAPI_KEY` from the environment.
+
+## Calls
+
+One method per endpoint, named after the route.
+
+```ts
+await parse.ip('8.8.8.8');
+await parse.ip.self();
+await parse.email('hello@gmail.com');
+await parse.phone('+14155552671');
+await parse.postal('28202', { country: 'US' });
+await parse.postal.nearby('28202', { country: 'US', radius: 40 });
+await parse.postal.distance('28202', '10001', { country: 'US' });
+await parse.city('charlotte', { country: 'US' });
+await parse.city.id('city_mb8mbqrkz8zb');
+await parse.city.search('char', { country: 'US', limit: 10 });
+await parse.city.nearest(35.2271, -80.8431);
+await parse.country('US');
+await parse.country.states('US');
+await parse.state('NC', { country: 'US' });
+await parse.state.districts('NC', { country: 'US' });
+await parse.district('37081');
+await parse.continent('NA');
+await parse.continent.countries('NA');
+await parse.currency('USD');
+await parse.currency.rate('USD', 'EUR');
+await parse.language('en');
+await parse.timezone('America/New_York');
+await parse.holiday('US', { year: 2026 });
+await parse.holiday.date('US', '2026-12-25');
+await parse.elevation(35.2271, -80.8431);
+await parse.point(36.0726, -79.792);
+await parse.weather(40.7128, -74.006);
+await parse.domain('example.com');
+await parse.mx('example.com');
+await parse.useragent(uaString);
+await parse.emoji('rocket');
+await parse.emoji.search('fire');
+```
+
+Every response is fully typed.
+
+## Deep
+
+Pass `deep: true` to include the nested `deep` object with richer fields.
+
+```ts
+const ip = await parse.ip('52.94.76.10', { deep: true });
+ip.deep?.datacenter; // true
+```
+
+## Errors
+
+Every non-2xx response throws a `ParseAPIError` with `status`, `code`, `docs`, and `requestId`. Branch on `code`.
+
+```ts
+import { ParseAPIError } from '@parseapi/sdk';
+
+try {
+  await parse.city('atlantis');
+} catch (err) {
+  if (err instanceof ParseAPIError && err.code === 'not_found') {
+    // no such city
+  }
+}
+```
+
+## Options
+
+```ts
+const parse = parseAPI('your-api-key', {
+  timeoutMs: 10000, // per-attempt timeout
+  retries: 2,       // automatic retries on network errors, 429, and 5xx
+});
+```
+
+Requires Node 18 or later. Zero dependencies.
+
+## Docs
+
+Full field reference for every endpoint: [parseapi.com/docs](https://parseapi.com/docs)

package/dist/index.cjs

@@ -0,0 +1,200 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ParseAPIError: () => ParseAPIError,
+  parseAPI: () => parseAPI
+});
+module.exports = __toCommonJS(index_exports);
+var VERSION = "0.1.0";
+var DEFAULT_BASE_URL = "https://api.parseapi.com";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var DEFAULT_RETRIES = 2;
+var RETRY_STATUS = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+var RETRY_AFTER_CAP_MS = 5e3;
+var ParseAPIError = class extends Error {
+  /** HTTP status */
+  status;
+  /** Machine-readable error code, e.g. 'not_found', 'invalid_api_key', 'rate_limited' */
+  code;
+  /** Link to the docs section for this error */
+  docs;
+  /** Send this if you contact support */
+  requestId;
+  constructor(status, code, message, docs, requestId) {
+    super(message);
+    this.name = "ParseAPIError";
+    this.status = status;
+    this.code = code;
+    this.docs = docs;
+    this.requestId = requestId;
+  }
+};
+function env(name) {
+  return typeof process !== "undefined" ? process.env?.[name] : void 0;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+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);
+    }
+  }
+  return Math.random() * 250 * 2 ** attempt;
+}
+function parseAPI(apiKey, options = {}) {
+  const key = apiKey ?? env("PARSEAPI_KEY");
+  if (!key) {
+    throw new Error("parseAPI: missing API key. Pass one or set PARSEAPI_KEY.");
+  }
+  const baseUrl = (options.baseUrl ?? env("PARSEAPI_BASE_URL") ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const retries = options.retries ?? DEFAULT_RETRIES;
+  const doFetch = options.fetch ?? fetch;
+  async function request(path, query, headers) {
+    const url = new URL(baseUrl + path);
+    for (const [name, value] of Object.entries(query ?? {})) {
+      if (value !== void 0) url.searchParams.set(name, String(value));
+    }
+    for (let attempt = 0; ; attempt++) {
+      let res;
+      try {
+        res = await doFetch(url, {
+          headers: {
+            "X-API-Key": key,
+            "User-Agent": `parseapi-node/${VERSION}`,
+            ...headers
+          },
+          signal: AbortSignal.timeout(timeoutMs)
+        });
+      } catch (err) {
+        if (attempt < retries) {
+          await sleep(retryDelayMs(attempt, null));
+          continue;
+        }
+        throw err;
+      }
+      if (res.ok) {
+        return await res.json();
+      }
+      if (RETRY_STATUS.has(res.status) && attempt < retries) {
+        await sleep(retryDelayMs(attempt, res.headers.get("Retry-After")));
+        continue;
+      }
+      let body = {};
+      try {
+        body = await res.json();
+      } catch {
+      }
+      throw new ParseAPIError(
+        res.status,
+        typeof body.code === "string" ? body.code : "unknown_error",
+        typeof body.message === "string" ? body.message : `Request failed with status ${res.status}`,
+        typeof body.docs === "string" ? body.docs : null,
+        typeof body.request_id === "string" ? body.request_id : null
+      );
+    }
+  }
+  const enc = encodeURIComponent;
+  const deepQuery = (opts) => opts?.deep ? { deep: true } : {};
+  return {
+    ip: Object.assign(
+      (ip, opts) => request(`/ip/${enc(ip)}`, deepQuery(opts)),
+      {
+        self: (opts) => request("/ip", deepQuery(opts))
+      }
+    ),
+    continent: Object.assign(
+      (code) => request(`/continent/${enc(code)}`),
+      {
+        countries: (code) => request(`/continent/${enc(code)}/countries`)
+      }
+    ),
+    country: Object.assign(
+      (code) => request(`/country/${enc(code)}`),
+      {
+        states: (code) => request(`/country/${enc(code)}/states`)
+      }
+    ),
+    state: Object.assign(
+      (code, opts) => request(`/state/${enc(code)}`, { country: opts.country }),
+      {
+        districts: (code, opts) => request(`/state/${enc(code)}/districts`, { country: opts.country })
+      }
+    ),
+    district: (code, opts) => request(`/district/${enc(code)}`, { country: opts?.country }),
+    city: Object.assign(
+      (name, opts) => request(`/city/${enc(name)}`, { country: opts?.country, state: opts?.state }),
+      {
+        id: (id) => request(`/city/id/${enc(id)}`),
+        search: (q, opts) => request("/city", { q, country: opts?.country, state: opts?.state, limit: opts?.limit }),
+        nearest: (lat, lon) => request("/city", { lat, lon })
+      }
+    ),
+    postal: Object.assign(
+      (code, opts) => request(`/postal/${enc(code)}`, { country: opts.country }),
+      {
+        nearby: (code, opts) => request(`/postal/${enc(code)}/nearby`, {
+          country: opts.country,
+          radius: opts.radius,
+          unit: opts.unit
+        }),
+        distance: (from, to, opts) => request(`/postal/${enc(from)}/distance/${enc(to)}`, { country: opts.country })
+      }
+    ),
+    email: (email, opts) => request(`/email/${enc(email)}`, deepQuery(opts)),
+    phone: (number, opts) => request(`/phone/${enc(number)}`, { country: opts?.country, ...deepQuery(opts) }),
+    domain: (domain, opts) => request(`/domain/${enc(domain)}`, deepQuery(opts)),
+    mx: (domain) => request(`/mx/${enc(domain)}`),
+    useragent: (ua, opts) => request("/useragent", deepQuery(opts), { "User-Agent": ua }),
+    currency: Object.assign(
+      (code) => request(`/currency/${enc(code)}`),
+      {
+        rate: (base, quote) => request(`/currency/${enc(base)}/${enc(quote)}`)
+      }
+    ),
+    language: (code) => request(`/language/${enc(code)}`),
+    timezone: (id, opts) => request(`/timezone/${enc(id)}`, { at: opts?.at }),
+    holiday: Object.assign(
+      (country, opts) => request(`/holiday/${enc(country)}`, { year: opts?.year }),
+      {
+        date: (country, date) => request(`/holiday/${enc(country)}/${enc(date)}`)
+      }
+    ),
+    elevation: (lat, lon) => request("/elevation", { lat, lon }),
+    point: (lat, lon, opts) => request("/point", { lat, lon, ...deepQuery(opts) }),
+    weather: (lat, lon, opts) => request("/weather", { lat, lon, ...deepQuery(opts) }),
+    emoji: Object.assign(
+      (emoji) => request(`/emoji/${enc(emoji)}`),
+      {
+        search: (q, opts) => request("/emoji", { q, limit: opts?.limit })
+      }
+    )
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ParseAPIError,
+  parseAPI
+});