@parseapi/sdk 1.0.0 → 1.2.0

package/README.md

@@ -17,14 +17,30 @@ Get a key at [parseapi.com](https://parseapi.com). The client also reads `PARSEA
 
 ## API versions
 
-Version 1.0.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.2.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.
 
-Previously published SDKs keep their existing behavior and use the team's default. Requests without `Parse-Version` also use that default, managed in [Dashboard API version](https://parseapi.com/dashboard/versions). Keep it unchanged while older applications depend on it. Rolling back to an SDK without a version header restores the team default, so rollback only restores the old contract when that default has stayed unchanged.
+SDK packages older than 1.0.0 keep their existing behavior and use the team's default. Requests without `Parse-Version` also use that default, managed in [Dashboard API version](https://parseapi.com/dashboard/versions). Keep it unchanged while older applications depend on it. Rolling back to an SDK without a version header restores the team default, so rollback only restores the old contract when that default has stayed unchanged.
 
 The package owns its supported API version. For direct HTTP integrations, an explicit `Parse-Version` header selects a supported contract. See [API versions and migration](https://parseapi.com/docs/versioning).
 
+## Task preflight
+
+Use a secret key to estimate access, advisory capacity and additional charges before a task. Preflight is available with API contract `2.0.0`.
+
+```ts
+const estimate = await parse.preflight({
+  operations: [{ operation: 'email', count: 100, deep: true }],
+  budget_usd: '2.50',
+});
+console.log(estimate.permitted, estimate.cost, estimate.capacity, estimate.budget);
+```
+
+Preflight accepts Email, Domain, DNS, MX and Country, with at most 20 rows and 100,000 total lookups. Supply operation counts without personal data or lookup inputs. Monetary values use decimal strings. The maximum assumes included Email checks are exhausted. The projection uses currently unallocated included checks. Rates come from the credential's accepted terms.
+
+Check `permitted`, `cost.status`, `capacity` and the optional `budget.within_maximum` together. Unknown values remain null. Capacity can change with concurrent work. Preflight reserves no units or money, performs no paid checks and does not enforce the supplied budget. It uses the normal request rate limit. Estimates allow up to three attempts per ordinary lookup and one per Email Deep lookup. Extra retries or calls require a new estimate. Subscription fees, tax and model costs are excluded.
+
 ## Weather from a postal code
 
 Start with the postal code, then pass its coordinates to weather. Reuse the client from the example above.
@@ -194,7 +210,7 @@ Choose enrichment for the question you need answered.
 |---|---|
 | IP | Richer IP fields included with a paid plan. No separate check meter. |
 | 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 deliverability check, using included email checks or enabled on-demand usage. |
+| 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. |
 | Country, State, District, City, Postal | The place profile on paid plans, including demographic and tax facts where held. |
@@ -203,6 +219,10 @@ Choose enrichment for the question you need answered.
 | 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. |
 
+Email deep includes mailbox status and the reason for the result, plus a suggested first name, no-reply flag, plus-address tag and mail service. The suggested name is not a verified identity. Unavailable details are null.
+
+Reasons include `accepted`, `invalid_format`, `invalid_domain`, `no_mail_server`, `mailbox_not_found`, `mailbox_disabled`, `mailbox_full`, `catchall`, `disposable`, `temporary_failure`, `rejected` and `unconfirmed`.
+
 Carrier, caller, and HLR are separate metered operations. Choose them explicitly when you need their answers. Ordinary lookups retry twice by default. Metered checks use one attempt by default. Setting retries explicitly can repeat paid usage.
 
 Without `deep`, the response omits that key. When requested, it is an empty object if access is locked or the operation has no deep fields. Otherwise it contains the available fields. A missing or null field means unknown.

package/dist/index.cjs

@@ -24,7 +24,7 @@ __export(index_exports, {
   parseAPI: () => parseAPI
 });
 module.exports = __toCommonJS(index_exports);
-var VERSION = "1.0.0";
+var VERSION = "1.2.0";
 var API_VERSION = "2.0.0";
 var DEFAULT_BASE_URL = "https://api.parseapi.com";
 var DEFAULT_TIMEOUT_MS = 1e4;
@@ -107,13 +107,14 @@ function parseAPI(apiKey, options = {}) {
   validateTimeout(timeoutMs);
   validateRetries(configuredRetries);
   const doFetch = options.fetch ?? fetch;
-  async function request(path, query, headers, controls = {}) {
+  async function request(path, query, headers, controls = {}, json) {
     const signal = controls.signal;
     signal?.throwIfAborted();
     const attemptTimeout = controls.timeoutMs ?? timeoutMs;
     const retries = controls.retries ?? configuredRetries ?? (metered(path, query) ? 0 : DEFAULT_RETRIES);
     validateTimeout(attemptTimeout);
     validateRetries(retries);
+    const body = json === void 0 ? void 0 : JSON.stringify(json);
     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 ?? {})) {
@@ -131,7 +132,8 @@ function parseAPI(apiKey, options = {}) {
         try {
           res = await doFetch(url, {
             redirect: "manual",
-            headers: { "X-API-Key": key, "User-Agent": `parseapi-node/${VERSION}`, ...headers, "Parse-Version": API_VERSION },
+            ...body === void 0 ? {} : { method: "POST", body },
+            headers: { "X-API-Key": key, "User-Agent": `parseapi-node/${VERSION}`, ...body === void 0 ? {} : { "Content-Type": "application/json" }, ...headers, "Parse-Version": API_VERSION },
             signal: controller.signal
           });
         } catch (error) {
@@ -155,20 +157,20 @@ function parseAPI(apiKey, options = {}) {
           await res.body?.cancel().catch(() => {
           });
         } else if (res) {
-          let body = {};
+          let body2 = {};
           try {
             const parsed = await res.json();
-            if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) body = parsed;
+            if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) body2 = parsed;
           } catch {
             controller.signal.throwIfAborted();
           }
           signal?.throwIfAborted();
           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
+            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
           );
         }
       } finally {
@@ -181,6 +183,8 @@ function parseAPI(apiKey, options = {}) {
   const enc = encodeURIComponent;
   const deepQuery = (opts) => opts?.deep ? { deep: true } : {};
   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),
     /** 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),

package/dist/index.d.cts

@@ -250,8 +250,19 @@ interface PostalDistance {
     distance_mi: number;
 }
 interface EmailDeep {
+    /** Suggested first name. Not a verified identity. */
+    first_name?: string | null;
+    no_reply?: boolean | null;
+    /** Plus-address tag, without the plus sign. */
+    tag?: string | null;
+    /** Mail service handling the address, such as Google or Microsoft. */
+    mail_provider?: string | null;
     deliverable: boolean | null;
     catchall: boolean | null;
+    /** Mailbox status: deliverable, undeliverable or risky. Null when unavailable. */
+    status?: string | null;
+    /** Why the address received this result, such as mailbox_full or mailbox_not_found. Null when unavailable. */
+    reason?: string | null;
 }
 interface Email {
     email: string;
@@ -1243,6 +1254,102 @@ interface PropertyTax {
     period: string;
 }
 
+/** A proposed task contains operation counts, never lookup inputs. */
+interface PreflightOperation {
+    operation: 'email' | 'domain' | 'dns' | 'mx' | 'country';
+    /** Positive integer, at most 100000. */
+    count: number;
+    deep?: boolean;
+}
+interface PreflightTask {
+    /** One to twenty rows, totaling at most 100000 lookups. */
+    operations: PreflightOperation[];
+    /** Nonnegative USD decimal string with at most two fractional digits. Advisory, never an enforced cap. */
+    budget_usd?: string;
+}
+interface PreflightOperationEstimate {
+    operation: string;
+    count: number;
+    deep: boolean;
+    permitted: boolean;
+    reason: string | null;
+    /** Attempts per lookup under the default SDK retry policy. */
+    max_http_attempts: number;
+    pooled_requests_max: number;
+    metered_units_max: number;
+}
+interface PreflightCost {
+    currency: string;
+    status: string;
+    minimum_usd: string;
+    /** Additional charges assuming included units are exhausted. Null when the effective rate is unknown. */
+    maximum_usd: string | null;
+    /** Additional charges using currently unallocated included units. */
+    projected_maximum_usd: string | null;
+    on_demand_unit_price_usd: string | null;
+}
+interface PreflightPooledCapacity {
+    advisory: true;
+    required_max: number;
+    policy: string | null;
+    limit: number | null;
+    used_at_snapshot: number | null;
+    remaining_at_snapshot: number | null;
+    /** Unix seconds, or null when no active grace deadline is known. */
+    grace_until: number | null;
+    /** Unix seconds. */
+    reset_at: number;
+    allowed_at_snapshot: boolean | null;
+    status: string;
+}
+interface PreflightEmailCapacity {
+    advisory: true;
+    required_max: number;
+    included_limit: number;
+    reserved_at_snapshot: number | null;
+    unallocated_included_at_snapshot: number | null;
+    projected_overage_units_max: number | null;
+    on_demand_enabled: boolean | null;
+    fits_unallocated_capacity: boolean | null;
+    /** Unix seconds. */
+    reset_at: number;
+}
+interface PreflightSpendCapacity {
+    advisory: true;
+    currency: string;
+    cap_usd: string | null;
+    cap_status: string;
+    reserved_usd_at_snapshot: string | null;
+    unallocated_usd_at_snapshot: string | null;
+    /** Unix seconds. */
+    reset_at: number;
+}
+/** A credential-specific estimate. Counters are advisory and can change during execution. */
+interface Preflight {
+    schema_version: string;
+    api_version: string;
+    /** ISO 8601 evaluation time. */
+    evaluated_at: string;
+    estimate_only: true;
+    supported: boolean;
+    /** Permission for the requested features, separate from available capacity. */
+    permitted: boolean;
+    operations: PreflightOperationEstimate[];
+    cost: PreflightCost;
+    capacity: {
+        pooled_requests: PreflightPooledCapacity;
+        email_verifications: PreflightEmailCapacity;
+        shared_on_demand_spend: PreflightSpendCapacity;
+    };
+    budget?: {
+        amount_usd: string;
+        within_maximum: boolean | null;
+        enforced: false;
+    };
+    assumptions: string[];
+    warnings: string[];
+}
+
 /** Every non-2xx response from the API. Branch on `code`, never on `message`. */
 declare class ParseAPIError extends Error {
     /** HTTP status */
@@ -1461,6 +1568,8 @@ interface DeepOption {
     deep?: boolean;
 }
 declare function parseAPI(apiKey?: string, options?: ParseAPIOptions): {
+    /** 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: PreflightTask, opts?: RequestOptions) => Promise<Preflight>;
     /** Look up an IP. `deep: true` adds enrichment included with a paid plan, without a separate check meter. */
     ip: ((ip: string, opts?: IpOptions) => Promise<Ip>) & {
         /** Look up the public IP making this request. On a server, this is the server's IP. */
@@ -1566,4 +1675,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 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 PostalMetro, type PostalMetrosDeep, type PostalNearby, type PostalNearbyItem, type PostalNearbyOptions, type PostalOptions, type PropertyTax, type RequestOptions, 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 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 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 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 };

package/dist/index.d.ts

@@ -250,8 +250,19 @@ interface PostalDistance {
     distance_mi: number;
 }
 interface EmailDeep {
+    /** Suggested first name. Not a verified identity. */
+    first_name?: string | null;
+    no_reply?: boolean | null;
+    /** Plus-address tag, without the plus sign. */
+    tag?: string | null;
+    /** Mail service handling the address, such as Google or Microsoft. */
+    mail_provider?: string | null;
     deliverable: boolean | null;
     catchall: boolean | null;
+    /** Mailbox status: deliverable, undeliverable or risky. Null when unavailable. */
+    status?: string | null;
+    /** Why the address received this result, such as mailbox_full or mailbox_not_found. Null when unavailable. */
+    reason?: string | null;
 }
 interface Email {
     email: string;
@@ -1243,6 +1254,102 @@ interface PropertyTax {
     period: string;
 }
 
+/** A proposed task contains operation counts, never lookup inputs. */
+interface PreflightOperation {
+    operation: 'email' | 'domain' | 'dns' | 'mx' | 'country';
+    /** Positive integer, at most 100000. */
+    count: number;
+    deep?: boolean;
+}
+interface PreflightTask {
+    /** One to twenty rows, totaling at most 100000 lookups. */
+    operations: PreflightOperation[];
+    /** Nonnegative USD decimal string with at most two fractional digits. Advisory, never an enforced cap. */
+    budget_usd?: string;
+}
+interface PreflightOperationEstimate {
+    operation: string;
+    count: number;
+    deep: boolean;
+    permitted: boolean;
+    reason: string | null;
+    /** Attempts per lookup under the default SDK retry policy. */
+    max_http_attempts: number;
+    pooled_requests_max: number;
+    metered_units_max: number;
+}
+interface PreflightCost {
+    currency: string;
+    status: string;
+    minimum_usd: string;
+    /** Additional charges assuming included units are exhausted. Null when the effective rate is unknown. */
+    maximum_usd: string | null;
+    /** Additional charges using currently unallocated included units. */
+    projected_maximum_usd: string | null;
+    on_demand_unit_price_usd: string | null;
+}
+interface PreflightPooledCapacity {
+    advisory: true;
+    required_max: number;
+    policy: string | null;
+    limit: number | null;
+    used_at_snapshot: number | null;
+    remaining_at_snapshot: number | null;
+    /** Unix seconds, or null when no active grace deadline is known. */
+    grace_until: number | null;
+    /** Unix seconds. */
+    reset_at: number;
+    allowed_at_snapshot: boolean | null;
+    status: string;
+}
+interface PreflightEmailCapacity {
+    advisory: true;
+    required_max: number;
+    included_limit: number;
+    reserved_at_snapshot: number | null;
+    unallocated_included_at_snapshot: number | null;
+    projected_overage_units_max: number | null;
+    on_demand_enabled: boolean | null;
+    fits_unallocated_capacity: boolean | null;
+    /** Unix seconds. */
+    reset_at: number;
+}
+interface PreflightSpendCapacity {
+    advisory: true;
+    currency: string;
+    cap_usd: string | null;
+    cap_status: string;
+    reserved_usd_at_snapshot: string | null;
+    unallocated_usd_at_snapshot: string | null;
+    /** Unix seconds. */
+    reset_at: number;
+}
+/** A credential-specific estimate. Counters are advisory and can change during execution. */
+interface Preflight {
+    schema_version: string;
+    api_version: string;
+    /** ISO 8601 evaluation time. */
+    evaluated_at: string;
+    estimate_only: true;
+    supported: boolean;
+    /** Permission for the requested features, separate from available capacity. */
+    permitted: boolean;
+    operations: PreflightOperationEstimate[];
+    cost: PreflightCost;
+    capacity: {
+        pooled_requests: PreflightPooledCapacity;
+        email_verifications: PreflightEmailCapacity;
+        shared_on_demand_spend: PreflightSpendCapacity;
+    };
+    budget?: {
+        amount_usd: string;
+        within_maximum: boolean | null;
+        enforced: false;
+    };
+    assumptions: string[];
+    warnings: string[];
+}
+
 /** Every non-2xx response from the API. Branch on `code`, never on `message`. */
 declare class ParseAPIError extends Error {
     /** HTTP status */
@@ -1461,6 +1568,8 @@ interface DeepOption {
     deep?: boolean;
 }
 declare function parseAPI(apiKey?: string, options?: ParseAPIOptions): {
+    /** 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: PreflightTask, opts?: RequestOptions) => Promise<Preflight>;
     /** Look up an IP. `deep: true` adds enrichment included with a paid plan, without a separate check meter. */
     ip: ((ip: string, opts?: IpOptions) => Promise<Ip>) & {
         /** Look up the public IP making this request. On a server, this is the server's IP. */
@@ -1566,4 +1675,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 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 PostalMetro, type PostalMetrosDeep, type PostalNearby, type PostalNearbyItem, type PostalNearbyOptions, type PostalOptions, type PropertyTax, type RequestOptions, 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 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 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 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 };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-var VERSION = "1.0.0";
+var VERSION = "1.2.0";
 var API_VERSION = "2.0.0";
 var DEFAULT_BASE_URL = "https://api.parseapi.com";
 var DEFAULT_TIMEOUT_MS = 1e4;
@@ -82,13 +82,14 @@ function parseAPI(apiKey, options = {}) {
   validateTimeout(timeoutMs);
   validateRetries(configuredRetries);
   const doFetch = options.fetch ?? fetch;
-  async function request(path, query, headers, controls = {}) {
+  async function request(path, query, headers, controls = {}, json) {
     const signal = controls.signal;
     signal?.throwIfAborted();
     const attemptTimeout = controls.timeoutMs ?? timeoutMs;
     const retries = controls.retries ?? configuredRetries ?? (metered(path, query) ? 0 : DEFAULT_RETRIES);
     validateTimeout(attemptTimeout);
     validateRetries(retries);
+    const body = json === void 0 ? void 0 : JSON.stringify(json);
     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 ?? {})) {
@@ -106,7 +107,8 @@ function parseAPI(apiKey, options = {}) {
         try {
           res = await doFetch(url, {
             redirect: "manual",
-            headers: { "X-API-Key": key, "User-Agent": `parseapi-node/${VERSION}`, ...headers, "Parse-Version": API_VERSION },
+            ...body === void 0 ? {} : { method: "POST", body },
+            headers: { "X-API-Key": key, "User-Agent": `parseapi-node/${VERSION}`, ...body === void 0 ? {} : { "Content-Type": "application/json" }, ...headers, "Parse-Version": API_VERSION },
             signal: controller.signal
           });
         } catch (error) {
@@ -130,20 +132,20 @@ function parseAPI(apiKey, options = {}) {
           await res.body?.cancel().catch(() => {
           });
         } else if (res) {
-          let body = {};
+          let body2 = {};
           try {
             const parsed = await res.json();
-            if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) body = parsed;
+            if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) body2 = parsed;
           } catch {
             controller.signal.throwIfAborted();
           }
           signal?.throwIfAborted();
           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
+            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
           );
         }
       } finally {
@@ -156,6 +158,8 @@ function parseAPI(apiKey, options = {}) {
   const enc = encodeURIComponent;
   const deepQuery = (opts) => opts?.deep ? { deep: true } : {};
   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),
     /** 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),

package/package.json

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