@parseapi/sdk 1.11.4 → 1.12.0

package/README.md

@@ -41,6 +41,34 @@ Preflight accepts Email, Domain, DNS, MX and Country, with at most 20 rows and 1
 
 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.
 
+## Bulk files
+
+Use `createBulkClient` for whole files. It uses the website origin separately from the lookup client's API origin.
+
+```ts
+import { createBulkClient } from '@parseapi/sdk';
+
+const bulk = createBulkClient(process.env.PARSEAPI_KEY);
+const upload = await bulk.upload({ filename: 'customers.csv', file_size: csvBytes.byteLength });
+await fetch(upload.upload_url, {
+  method: 'PUT', headers: upload.upload_headers, body: csvBytes,
+});
+await bulk.preview(upload.id); // Confirm the completed upload and request analysis.
+const progress = await bulk.status(upload.id);
+```
+
+`csvBytes` comes from your application. Convert Excel or Numbers to CSV before creating the upload. File contents transfer directly to private storage and are never sent through MCP.
+
+Analysis may take time. Poll `status` until `job.status` is `quoted`. Then call `bulk.preview(id, { checks: ['email', 'phone', 'ip'] })` to select operations present in the file, or omit `checks` to retain the detected selection. A changed selection requests analysis again. Repeat status and preview until the response includes a current `quote`.
+
+After the user approves the work and maximum USD cost, call `bulk.start(id, { quote_id: preview.quote.id, max_cost_cents })`. The server enforces that ceiling and returns any payment or setup action. A positive ceiling does not authorize a saved-card charge. Reuse the same job and quote when recovering a start request.
+
+When processing finishes, `bulk.result(id)` returns a short-lived private `download_url`. Fetch that URL directly without adding an API key header. All methods return bounded JSON metadata and preserve nullable and future server fields. They never retry automatically. If upload creation has an uncertain outcome, check the account before creating another job.
+
+Existing Bulk job URLs remain shareable. Treat job IDs and download URLs as file-access capabilities.
+
+Options are `webUrl`, `timeoutMs` and `fetch`. `PARSEAPI_WEB_URL` can set the website origin. HTTPS origins and HTTP loopback origins are accepted. Lookup `baseUrl` and `PARSEAPI_BASE_URL` stay independent.
+
 ## Weather from a postal code
 
 Start with the postal code, then pass its coordinates to weather. Reuse the client from the example above.

package/dist/index.cjs

@@ -20,13 +20,176 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BULK_CHECKS: () => BULK_CHECKS,
+  BulkAPIError: () => ParseAPIError,
   EmojiCatalog: () => EmojiCatalog,
   EmojiCatalogError: () => EmojiCatalogError,
   ParseAPIError: () => ParseAPIError,
+  createBulkClient: () => createBulkClient,
   parseAPI: () => parseAPI
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/errors.ts
+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;
+  /** Original Retry-After response header, when supplied. */
+  retryAfter;
+  constructor(status, code, message, docs = null, requestId = null, retryAfter = null) {
+    super(message);
+    this.name = "ParseAPIError";
+    this.status = status;
+    this.code = code;
+    this.docs = docs;
+    this.requestId = requestId;
+    this.retryAfter = retryAfter;
+  }
+};
+
+// src/bulk.ts
+var BULK_CHECKS = ["email", "phone", "carrier", "caller", "hlr", "ip", "domain", "useragent", "country", "postal", "address", "name", "date"];
+var MAX_RESPONSE_BYTES = 256 * 1024;
+var jobId = /^job_[23456789abcdefghjkmnpqrstuvwxyz]{14}$/;
+var invalidResponse = () => new ParseAPIError(502, "invalid_api_response", "The Bulk service returned an invalid response.");
+function origin(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TypeError("ParseAPI Bulk webUrl must be an HTTPS origin.");
+  }
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback) || url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+    throw new TypeError("ParseAPI Bulk webUrl must be an HTTPS origin, or HTTP on loopback.");
+  }
+  return url.origin;
+}
+async function boundedJson(response) {
+  const length = response.headers.get("content-length");
+  if (length && /^\d+$/.test(length) && Number(length) > MAX_RESPONSE_BYTES) {
+    await response.body?.cancel().catch(() => {
+    });
+    throw invalidResponse();
+  }
+  if (!response.body) throw invalidResponse();
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let size = 0, text = "";
+  try {
+    while (true) {
+      const part = await reader.read();
+      if (part.done) break;
+      size += part.value.byteLength;
+      if (size > MAX_RESPONSE_BYTES) {
+        await reader.cancel().catch(() => {
+        });
+        throw invalidResponse();
+      }
+      text += decoder.decode(part.value, { stream: true });
+    }
+    text += decoder.decode();
+  } finally {
+    reader.releaseLock();
+  }
+  try {
+    const data = JSON.parse(text);
+    if (data && typeof data === "object" && !Array.isArray(data)) return data;
+  } catch {
+  }
+  throw invalidResponse();
+}
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function createBulkClient(apiKey, options = {}) {
+  const key = apiKey || (typeof process !== "undefined" ? process.env.PARSEAPI_KEY : void 0);
+  if (!key) throw new Error("createBulkClient: missing API key. Pass one or set PARSEAPI_KEY.");
+  const webUrl = origin(options.webUrl ?? (typeof process !== "undefined" ? process.env.PARSEAPI_WEB_URL : void 0) ?? "https://parseapi.com");
+  const timeout = options.timeoutMs ?? 1e4;
+  if (!Number.isSafeInteger(timeout) || timeout <= 0) throw new TypeError("ParseAPI Bulk timeoutMs must be a positive integer.");
+  const doFetch = options.fetch ?? fetch;
+  function path(id) {
+    if (typeof id !== "string" || !jobId.test(id)) throw new TypeError("ParseAPI Bulk requires a valid job ID.");
+    return `/api/agent/bulk/${id}`;
+  }
+  async function request(path2, input, controls) {
+    const signal = controls?.signal;
+    signal?.throwIfAborted();
+    const controller = new AbortController();
+    const onAbort = () => controller.abort(signal?.reason);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const timer = setTimeout(() => controller.abort(new DOMException("Request timed out", "TimeoutError")), timeout);
+    try {
+      const response = await doFetch(`${webUrl}${path2}`, {
+        method: input === void 0 ? "GET" : "POST",
+        redirect: "manual",
+        credentials: "omit",
+        headers: { "X-API-Key": key, "Parse-Version": "2.0.0", "Accept": "application/json", ...input === void 0 ? {} : { "Content-Type": "application/json" } },
+        ...input === void 0 ? {} : { body: JSON.stringify(input) },
+        signal: controller.signal
+      });
+      signal?.throwIfAborted();
+      if (response.status >= 300 && response.status < 400) {
+        await response.body?.cancel().catch(() => {
+        });
+        throw new ParseAPIError(response.status, "unexpected_redirect", "The Bulk service returned an unexpected redirect.");
+      }
+      const data = await boundedJson(response);
+      signal?.throwIfAborted();
+      if (!response.ok) throw new ParseAPIError(
+        response.status,
+        typeof data.code === "string" ? data.code : "bulk_request_failed",
+        typeof data.message === "string" ? data.message : typeof data.error === "string" ? data.error : `Bulk request failed with status ${response.status}`,
+        typeof data.docs === "string" ? data.docs : null,
+        typeof data.request_id === "string" ? data.request_id : null,
+        response.headers.get("retry-after")
+      );
+      return data;
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    }
+  }
+  async function workflow(target, id, input, controls) {
+    const data = await request(target, input, controls);
+    if (!object(data.job) || data.job.id !== id || typeof data.job.status !== "string") throw invalidResponse();
+    return data;
+  }
+  return {
+    upload: async (input, controls) => {
+      if (!object(input) || typeof input.filename !== "string" || !input.filename.trim() || input.filename.length > 200 || !Number.isSafeInteger(input.file_size) || input.file_size <= 0) throw new TypeError("Provide a filename and positive file_size in bytes.");
+      if (input.country !== void 0 && (typeof input.country !== "string" || !/^[A-Za-z]{2}$/.test(input.country))) throw new TypeError("Bulk country must be an ISO2 code.");
+      if (input.lang !== void 0 && (typeof input.lang !== "string" || input.lang.length < 2 || input.lang.length > 64)) throw new TypeError("Provide a valid Bulk display language.");
+      const data = await request("/api/agent/bulk", { filename: input.filename, file_size: input.file_size, ...input.country === void 0 ? {} : { country: input.country }, ...input.lang === void 0 ? {} : { lang: input.lang } }, controls);
+      if (typeof data.id !== "string" || !jobId.test(data.id) || typeof data.upload_url !== "string" || data.upload_method !== "PUT" || typeof data.upload_expires_at !== "string" || !object(data.upload_headers) || Object.values(data.upload_headers).some((value) => typeof value !== "string")) throw invalidResponse();
+      return data;
+    },
+    preview: async (id, input = {}, controls) => {
+      if (!object(input) || input.checks !== void 0 && (!Array.isArray(input.checks) || input.checks.length < 1 || input.checks.length > BULK_CHECKS.length || input.checks.some((check) => !BULK_CHECKS.includes(check)) || new Set(input.checks).size !== input.checks.length)) throw new TypeError("Provide distinct public Bulk checks.");
+      const data = await workflow(`${path(id)}/preview`, id, input.checks === void 0 ? {} : { checks: input.checks }, controls);
+      if (data.quote !== null && (!object(data.quote) || typeof data.quote.id !== "string" || data.quote.currency !== "USD" || !Number.isSafeInteger(data.quote.cost_cents) || data.quote.cost_cents < 0 || data.quote.expires_at !== null && typeof data.quote.expires_at !== "string")) throw invalidResponse();
+      return data;
+    },
+    start: (id, input, controls) => {
+      if (!object(input) || typeof input.quote_id !== "string" || !input.quote_id || input.quote_id.length > 512 || !Number.isSafeInteger(input.max_cost_cents) || input.max_cost_cents < 0) throw new TypeError("Provide the current quote_id and approved max_cost_cents.");
+      return workflow(`${path(id)}/start`, id, { quote_id: input.quote_id, max_cost_cents: input.max_cost_cents }, controls);
+    },
+    status: (id, controls) => workflow(path(id), id, void 0, controls),
+    result: async (id, controls) => {
+      const data = await request(`${path(id)}/result`, void 0, controls);
+      if (data.id !== id || typeof data.download_url !== "string" || typeof data.expires_at !== "string") throw invalidResponse();
+      return data;
+    }
+  };
+}
+
 // src/emoji-catalog.ts
 var EmojiCatalogError = class extends Error {
   constructor(code, message) {
@@ -285,34 +448,13 @@ var EmojiCatalog = class {
 };
 
 // src/index.ts
-var VERSION = "1.11.4";
+var VERSION = "1.12.0";
 var API_VERSION = "2.0.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;
-  /** 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;
-  }
-};
 var requestControls = (opts) => ({ signal: opts?.signal, timeoutMs: opts?.timeoutMs, retries: opts?.retries });
 function env(name) {
   return typeof process !== "undefined" ? process.env?.[name] : void 0;
@@ -744,9 +886,12 @@ function cityCollectionQuery(opts) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BULK_CHECKS,
+  BulkAPIError,
   EmojiCatalog,
   EmojiCatalogError,
   ParseAPIError,
+  createBulkClient,
   parseAPI
 });
 /*! You found Dev. https://parseapi.com/dev */

package/dist/index.d.cts

@@ -1549,6 +1549,96 @@ interface CityNearbyCoordinates extends CityCollection {
     unit: string;
 }
 
+/** Every non-2xx response from the API. Branch on `code`, never on `message`. */
+declare class ParseAPIError extends Error {
+    /** HTTP status */
+    readonly status: number;
+    /** Machine-readable error code, e.g. 'not_found', 'invalid_api_key', 'rate_limited' */
+    readonly code: string;
+    /** Link to the docs section for this error */
+    readonly docs: string | null;
+    /** Send this if you contact support */
+    readonly requestId: string | null;
+    /** Original Retry-After response header, when supplied. */
+    readonly retryAfter: string | null;
+    candidates?: CityAmbiguityCandidate[];
+    constructor(status: number, code: string, message: string, docs?: string | null, requestId?: string | null, retryAfter?: string | null);
+}
+
+/** Account-owned file workflows. File bytes travel directly to the returned upload URL. */
+interface BulkClientOptions {
+    /** ParseAPI website origin. Separate from the lookup client's baseUrl. */
+    webUrl?: string;
+    /** Request timeout in milliseconds. Defaults to 10000. */
+    timeoutMs?: number;
+    /** Custom fetch implementation for this client. */
+    fetch?: typeof fetch;
+}
+interface BulkRequestOptions {
+    signal?: AbortSignal;
+}
+interface BulkUploadInput {
+    filename: string;
+    file_size: number;
+    country?: string;
+    lang?: string;
+}
+interface BulkPreviewInput {
+    checks?: string[];
+}
+interface BulkStartInput {
+    quote_id: string;
+    max_cost_cents: number;
+}
+/** Public checks supported by the current file workflow. */
+declare const BULK_CHECKS: readonly ["email", "phone", "carrier", "caller", "hlr", "ip", "domain", "useragent", "country", "postal", "address", "name", "date"];
+interface BulkUpload {
+    id: string;
+    rail: string;
+    upload_url: string;
+    upload_headers: Record<string, string>;
+    upload_method: 'PUT';
+    upload_expires_at: string;
+    [key: string]: unknown;
+}
+/** Status and previews retain server fields, including unknown and nullable results. */
+interface BulkJob {
+    id: string;
+    status: string;
+    [key: string]: unknown;
+}
+interface BulkStatus {
+    job: BulkJob;
+    poll_after_seconds?: number | null;
+    [key: string]: unknown;
+}
+interface BulkQuote {
+    id: string;
+    currency: 'USD';
+    cost_cents: number;
+    expires_at: string | null;
+    [key: string]: unknown;
+}
+interface BulkPreview extends BulkStatus {
+    quote: BulkQuote | null;
+}
+/** A short-lived download capability. Fetch this URL without an API key header. */
+interface BulkResult {
+    id: string;
+    download_url: string;
+    expires_at: string;
+    [key: string]: unknown;
+}
+interface BulkClient {
+    upload(input: BulkUploadInput, options?: BulkRequestOptions): Promise<BulkUpload>;
+    preview(id: string, input?: BulkPreviewInput, options?: BulkRequestOptions): Promise<BulkPreview>;
+    start(id: string, input: BulkStartInput, options?: BulkRequestOptions): Promise<BulkStatus>;
+    status(id: string, options?: BulkRequestOptions): Promise<BulkStatus>;
+    result(id: string, options?: BulkRequestOptions): Promise<BulkResult>;
+}
+/** Create a Bulk client. Requests are never retried automatically, including upload creation. */
+declare function createBulkClient(apiKey?: string, options?: BulkClientOptions): BulkClient;
+
 /** A proposed task contains operation counts, never lookup inputs. */
 interface PreflightOperation {
     operation: 'email' | 'domain' | 'dns' | 'mx' | 'country' | 'vat' | 'carrier' | 'caller' | 'hlr' | 'ip' | 'phone' | 'postal';
@@ -1774,21 +1864,6 @@ declare class EmojiCatalog {
     private filtered;
 }
 
-/** Every non-2xx response from the API. Branch on `code`, never on `message`. */
-declare class ParseAPIError extends Error {
-    /** HTTP status */
-    readonly status: number;
-    /** Machine-readable error code, e.g. 'not_found', 'invalid_api_key', 'rate_limited' */
-    readonly code: string;
-    /** Link to the docs section for this error */
-    readonly docs: string | null;
-    /** Send this if you contact support */
-    readonly requestId: string | null;
-    /** Original Retry-After response header, when supplied. */
-    readonly retryAfter: string | null;
-    candidates?: CityAmbiguityCandidate[];
-    constructor(status: number, code: string, message: string, docs: string | null, requestId: string | null, retryAfter?: string | null);
-}
 /** Optional output language for supported display fields. Input parsing stays unchanged. */
 interface LanguageOption {
     lang?: string;
@@ -2275,4 +2350,4 @@ interface CityNearbyCall {
     (name: string, opts: CityNearbyOptions): Promise<CityNearby | CityCollection>;
 }
 
-export { type Address, type AddressOptions, type AddressSearch, type AddressSearchOptions, type AddressSuggestion, type AgentTask, type AgentTaskInput, type AgentTaskLookupInput, type AgentTaskResult, type Asn, type AsnOptions, type Bin, type BinOptions, type Caller, type CallerOptions, type Card, type CardDeep, type CardOptions, type Carrier, type CarrierDeep, type CarrierOptions, type City, type CityAmbiguityCandidate, type CityAncestorsOptions, type CityCollection, type CityCollectionFilters, type CityDeep, type CityDistance, type CityDistanceOptions, type CityGrain, type CityIdCall, type CityIdOptions, type CityList, type CityListOptions, type CityLookupCall, type CityMatch, type CityNearby, type CityNearbyCall, type CityNearbyCoordinates, type CityNearbyCoordinatesOptions, type CityNearbyOptions, type CityNearest, type CityNearestCall, type CityNearestOptions, type CityOptions, type CityPagingOptions, type CityParent, type CityRelations, type CityRelationsOptions, type CityResource, type CityResponseOptions, type CityScopeOptions, type CitySearch, type CitySearchCall, type CitySearchOptions, type CitySort, type Company, type CompanyCandidate, type CompanyCountry, type CompanyCoverage, type CompanyCoverageOptions, type CompanyDeep, type CompanyEmailAddress, type CompanyIdOptions, type CompanyMatch, type CompanyOptions, type CompanyPhoneNumber, type CompanyProfile, type CompanyProfileAddress, type CompanyProfileDeep, type CompanyProfileDomain, type CompanyProfileEmail, type CompanyProfileEmployees, type CompanyProfileFounding, type CompanyProfileIdentifier, type CompanyProfileIndustry, type CompanyProfileJurisdiction, type CompanyProfileListing, type CompanyProfilePhone, type CompanyProfileRegistration, type CompanyProfileRegistrationAddress, type CompanyProfileRegistrationLegalForm, type CompanyProfileSource, type CompanyProfileWebsite, type CompanySearch, type CompanySearchOptions, type CompanySocialProfile, 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 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 ElevationLocations, type ElevationOptions, type Email, type EmailDeep, type EmailOptions, type Emoji, type EmojiArtwork, type EmojiArtworkSource, type EmojiBrowse, type EmojiBrowseOptions, EmojiCatalog, type EmojiCatalogConvertOptions, type EmojiCatalogData, EmojiCatalogError, type EmojiCatalogLocalization, type EmojiCatalogLookupOptions, type EmojiCatalogOptions, type EmojiCatalogParseOptions, type EmojiCatalogRegexOptions, type EmojiCatalogScope, type EmojiCatalogSearchFacts, type EmojiCatalogSearchOptions, type EmojiCategories, type EmojiCategory, type EmojiConversion, type EmojiConvertOptions, type EmojiDeep, type EmojiMetadata, type EmojiNativeSearchFacts, type EmojiNotice, type EmojiOptions, type EmojiParse, type EmojiParseOptions, type EmojiPosition, type EmojiSearch, type EmojiSearchOptions, type EmojiShortcodeSourceMetadata, type EmojiSkin, type EmojiSource, type EmojiUnresolved, type EmojiVariant, type Hlr, type HlrDeep, type HlrOptions, type Holiday, type HolidayDate, type HolidayDateOptions, type HolidayOptions, type HolidayYear, type Industry, type IndustryChild, type IndustryCorrection, type IndustryDeep, type IndustryExclusion, type IndustryMatch, type IndustryOptions, type IndustrySearch, type IndustrySearchItem, type IndustrySearchOptions, type Ip, type IpDeep, type IpOptions, type IpSelfOptions, type Language, type LanguageDeep, type LanguageOption, type LanguageOptions, 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 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 PostalLocality, 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 Stack, type StackOptions, type StackTechnology, type State, type StateDeep, type StateDistrictDeep, type StateDistrictItem, type StateDistricts, type StateDistrictsOptions, type StateOptions, type Time, type TimeAtOptions, type TimeLocation, type TimeLocationCandidate, type TimeLocationInput, type TimeOptions, type TimeResolution, type TimeResolutionAlternative, type TimeSeason, type TimeTransition, type TimeTransitionState, type TimeZoneEntry, type TimeZones, type TimeZonesOptions, 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 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 AgentTask, type AgentTaskInput, type AgentTaskLookupInput, type AgentTaskResult, type Asn, type AsnOptions, BULK_CHECKS, type Bin, type BinOptions, ParseAPIError as BulkAPIError, type BulkClient, type BulkClientOptions, type BulkJob, type BulkPreview, type BulkPreviewInput, type BulkQuote, type BulkRequestOptions, type BulkResult, type BulkStartInput, type BulkStatus, type BulkUpload, type BulkUploadInput, type Caller, type CallerOptions, type Card, type CardDeep, type CardOptions, type Carrier, type CarrierDeep, type CarrierOptions, type City, type CityAmbiguityCandidate, type CityAncestorsOptions, type CityCollection, type CityCollectionFilters, type CityDeep, type CityDistance, type CityDistanceOptions, type CityGrain, type CityIdCall, type CityIdOptions, type CityList, type CityListOptions, type CityLookupCall, type CityMatch, type CityNearby, type CityNearbyCall, type CityNearbyCoordinates, type CityNearbyCoordinatesOptions, type CityNearbyOptions, type CityNearest, type CityNearestCall, type CityNearestOptions, type CityOptions, type CityPagingOptions, type CityParent, type CityRelations, type CityRelationsOptions, type CityResource, type CityResponseOptions, type CityScopeOptions, type CitySearch, type CitySearchCall, type CitySearchOptions, type CitySort, type Company, type CompanyCandidate, type CompanyCountry, type CompanyCoverage, type CompanyCoverageOptions, type CompanyDeep, type CompanyEmailAddress, type CompanyIdOptions, type CompanyMatch, type CompanyOptions, type CompanyPhoneNumber, type CompanyProfile, type CompanyProfileAddress, type CompanyProfileDeep, type CompanyProfileDomain, type CompanyProfileEmail, type CompanyProfileEmployees, type CompanyProfileFounding, type CompanyProfileIdentifier, type CompanyProfileIndustry, type CompanyProfileJurisdiction, type CompanyProfileListing, type CompanyProfilePhone, type CompanyProfileRegistration, type CompanyProfileRegistrationAddress, type CompanyProfileRegistrationLegalForm, type CompanyProfileSource, type CompanyProfileWebsite, type CompanySearch, type CompanySearchOptions, type CompanySocialProfile, 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 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 ElevationLocations, type ElevationOptions, type Email, type EmailDeep, type EmailOptions, type Emoji, type EmojiArtwork, type EmojiArtworkSource, type EmojiBrowse, type EmojiBrowseOptions, EmojiCatalog, type EmojiCatalogConvertOptions, type EmojiCatalogData, EmojiCatalogError, type EmojiCatalogLocalization, type EmojiCatalogLookupOptions, type EmojiCatalogOptions, type EmojiCatalogParseOptions, type EmojiCatalogRegexOptions, type EmojiCatalogScope, type EmojiCatalogSearchFacts, type EmojiCatalogSearchOptions, type EmojiCategories, type EmojiCategory, type EmojiConversion, type EmojiConvertOptions, type EmojiDeep, type EmojiMetadata, type EmojiNativeSearchFacts, type EmojiNotice, type EmojiOptions, type EmojiParse, type EmojiParseOptions, type EmojiPosition, type EmojiSearch, type EmojiSearchOptions, type EmojiShortcodeSourceMetadata, type EmojiSkin, type EmojiSource, type EmojiUnresolved, type EmojiVariant, type Hlr, type HlrDeep, type HlrOptions, type Holiday, type HolidayDate, type HolidayDateOptions, type HolidayOptions, type HolidayYear, type Industry, type IndustryChild, type IndustryCorrection, type IndustryDeep, type IndustryExclusion, type IndustryMatch, type IndustryOptions, type IndustrySearch, type IndustrySearchItem, type IndustrySearchOptions, type Ip, type IpDeep, type IpOptions, type IpSelfOptions, type Language, type LanguageDeep, type LanguageOption, type LanguageOptions, 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 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 PostalLocality, 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 Stack, type StackOptions, type StackTechnology, type State, type StateDeep, type StateDistrictDeep, type StateDistrictItem, type StateDistricts, type StateDistrictsOptions, type StateOptions, type Time, type TimeAtOptions, type TimeLocation, type TimeLocationCandidate, type TimeLocationInput, type TimeOptions, type TimeResolution, type TimeResolutionAlternative, type TimeSeason, type TimeTransition, type TimeTransitionState, type TimeZoneEntry, type TimeZones, type TimeZonesOptions, 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 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, createBulkClient, parseAPI };

package/dist/index.d.ts

@@ -1549,6 +1549,96 @@ interface CityNearbyCoordinates extends CityCollection {
     unit: string;
 }
 
+/** Every non-2xx response from the API. Branch on `code`, never on `message`. */
+declare class ParseAPIError extends Error {
+    /** HTTP status */
+    readonly status: number;
+    /** Machine-readable error code, e.g. 'not_found', 'invalid_api_key', 'rate_limited' */
+    readonly code: string;
+    /** Link to the docs section for this error */
+    readonly docs: string | null;
+    /** Send this if you contact support */
+    readonly requestId: string | null;
+    /** Original Retry-After response header, when supplied. */
+    readonly retryAfter: string | null;
+    candidates?: CityAmbiguityCandidate[];
+    constructor(status: number, code: string, message: string, docs?: string | null, requestId?: string | null, retryAfter?: string | null);
+}
+
+/** Account-owned file workflows. File bytes travel directly to the returned upload URL. */
+interface BulkClientOptions {
+    /** ParseAPI website origin. Separate from the lookup client's baseUrl. */
+    webUrl?: string;
+    /** Request timeout in milliseconds. Defaults to 10000. */
+    timeoutMs?: number;
+    /** Custom fetch implementation for this client. */
+    fetch?: typeof fetch;
+}
+interface BulkRequestOptions {
+    signal?: AbortSignal;
+}
+interface BulkUploadInput {
+    filename: string;
+    file_size: number;
+    country?: string;
+    lang?: string;
+}
+interface BulkPreviewInput {
+    checks?: string[];
+}
+interface BulkStartInput {
+    quote_id: string;
+    max_cost_cents: number;
+}
+/** Public checks supported by the current file workflow. */
+declare const BULK_CHECKS: readonly ["email", "phone", "carrier", "caller", "hlr", "ip", "domain", "useragent", "country", "postal", "address", "name", "date"];
+interface BulkUpload {
+    id: string;
+    rail: string;
+    upload_url: string;
+    upload_headers: Record<string, string>;
+    upload_method: 'PUT';
+    upload_expires_at: string;
+    [key: string]: unknown;
+}
+/** Status and previews retain server fields, including unknown and nullable results. */
+interface BulkJob {
+    id: string;
+    status: string;
+    [key: string]: unknown;
+}
+interface BulkStatus {
+    job: BulkJob;
+    poll_after_seconds?: number | null;
+    [key: string]: unknown;
+}
+interface BulkQuote {
+    id: string;
+    currency: 'USD';
+    cost_cents: number;
+    expires_at: string | null;
+    [key: string]: unknown;
+}
+interface BulkPreview extends BulkStatus {
+    quote: BulkQuote | null;
+}
+/** A short-lived download capability. Fetch this URL without an API key header. */
+interface BulkResult {
+    id: string;
+    download_url: string;
+    expires_at: string;
+    [key: string]: unknown;
+}
+interface BulkClient {
+    upload(input: BulkUploadInput, options?: BulkRequestOptions): Promise<BulkUpload>;
+    preview(id: string, input?: BulkPreviewInput, options?: BulkRequestOptions): Promise<BulkPreview>;
+    start(id: string, input: BulkStartInput, options?: BulkRequestOptions): Promise<BulkStatus>;
+    status(id: string, options?: BulkRequestOptions): Promise<BulkStatus>;
+    result(id: string, options?: BulkRequestOptions): Promise<BulkResult>;
+}
+/** Create a Bulk client. Requests are never retried automatically, including upload creation. */
+declare function createBulkClient(apiKey?: string, options?: BulkClientOptions): BulkClient;
+
 /** A proposed task contains operation counts, never lookup inputs. */
 interface PreflightOperation {
     operation: 'email' | 'domain' | 'dns' | 'mx' | 'country' | 'vat' | 'carrier' | 'caller' | 'hlr' | 'ip' | 'phone' | 'postal';
@@ -1774,21 +1864,6 @@ declare class EmojiCatalog {
     private filtered;
 }
 
-/** Every non-2xx response from the API. Branch on `code`, never on `message`. */
-declare class ParseAPIError extends Error {
-    /** HTTP status */
-    readonly status: number;
-    /** Machine-readable error code, e.g. 'not_found', 'invalid_api_key', 'rate_limited' */
-    readonly code: string;
-    /** Link to the docs section for this error */
-    readonly docs: string | null;
-    /** Send this if you contact support */
-    readonly requestId: string | null;
-    /** Original Retry-After response header, when supplied. */
-    readonly retryAfter: string | null;
-    candidates?: CityAmbiguityCandidate[];
-    constructor(status: number, code: string, message: string, docs: string | null, requestId: string | null, retryAfter?: string | null);
-}
 /** Optional output language for supported display fields. Input parsing stays unchanged. */
 interface LanguageOption {
     lang?: string;
@@ -2275,4 +2350,4 @@ interface CityNearbyCall {
     (name: string, opts: CityNearbyOptions): Promise<CityNearby | CityCollection>;
 }
 
-export { type Address, type AddressOptions, type AddressSearch, type AddressSearchOptions, type AddressSuggestion, type AgentTask, type AgentTaskInput, type AgentTaskLookupInput, type AgentTaskResult, type Asn, type AsnOptions, type Bin, type BinOptions, type Caller, type CallerOptions, type Card, type CardDeep, type CardOptions, type Carrier, type CarrierDeep, type CarrierOptions, type City, type CityAmbiguityCandidate, type CityAncestorsOptions, type CityCollection, type CityCollectionFilters, type CityDeep, type CityDistance, type CityDistanceOptions, type CityGrain, type CityIdCall, type CityIdOptions, type CityList, type CityListOptions, type CityLookupCall, type CityMatch, type CityNearby, type CityNearbyCall, type CityNearbyCoordinates, type CityNearbyCoordinatesOptions, type CityNearbyOptions, type CityNearest, type CityNearestCall, type CityNearestOptions, type CityOptions, type CityPagingOptions, type CityParent, type CityRelations, type CityRelationsOptions, type CityResource, type CityResponseOptions, type CityScopeOptions, type CitySearch, type CitySearchCall, type CitySearchOptions, type CitySort, type Company, type CompanyCandidate, type CompanyCountry, type CompanyCoverage, type CompanyCoverageOptions, type CompanyDeep, type CompanyEmailAddress, type CompanyIdOptions, type CompanyMatch, type CompanyOptions, type CompanyPhoneNumber, type CompanyProfile, type CompanyProfileAddress, type CompanyProfileDeep, type CompanyProfileDomain, type CompanyProfileEmail, type CompanyProfileEmployees, type CompanyProfileFounding, type CompanyProfileIdentifier, type CompanyProfileIndustry, type CompanyProfileJurisdiction, type CompanyProfileListing, type CompanyProfilePhone, type CompanyProfileRegistration, type CompanyProfileRegistrationAddress, type CompanyProfileRegistrationLegalForm, type CompanyProfileSource, type CompanyProfileWebsite, type CompanySearch, type CompanySearchOptions, type CompanySocialProfile, 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 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 ElevationLocations, type ElevationOptions, type Email, type EmailDeep, type EmailOptions, type Emoji, type EmojiArtwork, type EmojiArtworkSource, type EmojiBrowse, type EmojiBrowseOptions, EmojiCatalog, type EmojiCatalogConvertOptions, type EmojiCatalogData, EmojiCatalogError, type EmojiCatalogLocalization, type EmojiCatalogLookupOptions, type EmojiCatalogOptions, type EmojiCatalogParseOptions, type EmojiCatalogRegexOptions, type EmojiCatalogScope, type EmojiCatalogSearchFacts, type EmojiCatalogSearchOptions, type EmojiCategories, type EmojiCategory, type EmojiConversion, type EmojiConvertOptions, type EmojiDeep, type EmojiMetadata, type EmojiNativeSearchFacts, type EmojiNotice, type EmojiOptions, type EmojiParse, type EmojiParseOptions, type EmojiPosition, type EmojiSearch, type EmojiSearchOptions, type EmojiShortcodeSourceMetadata, type EmojiSkin, type EmojiSource, type EmojiUnresolved, type EmojiVariant, type Hlr, type HlrDeep, type HlrOptions, type Holiday, type HolidayDate, type HolidayDateOptions, type HolidayOptions, type HolidayYear, type Industry, type IndustryChild, type IndustryCorrection, type IndustryDeep, type IndustryExclusion, type IndustryMatch, type IndustryOptions, type IndustrySearch, type IndustrySearchItem, type IndustrySearchOptions, type Ip, type IpDeep, type IpOptions, type IpSelfOptions, type Language, type LanguageDeep, type LanguageOption, type LanguageOptions, 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 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 PostalLocality, 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 Stack, type StackOptions, type StackTechnology, type State, type StateDeep, type StateDistrictDeep, type StateDistrictItem, type StateDistricts, type StateDistrictsOptions, type StateOptions, type Time, type TimeAtOptions, type TimeLocation, type TimeLocationCandidate, type TimeLocationInput, type TimeOptions, type TimeResolution, type TimeResolutionAlternative, type TimeSeason, type TimeTransition, type TimeTransitionState, type TimeZoneEntry, type TimeZones, type TimeZonesOptions, 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 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 AgentTask, type AgentTaskInput, type AgentTaskLookupInput, type AgentTaskResult, type Asn, type AsnOptions, BULK_CHECKS, type Bin, type BinOptions, ParseAPIError as BulkAPIError, type BulkClient, type BulkClientOptions, type BulkJob, type BulkPreview, type BulkPreviewInput, type BulkQuote, type BulkRequestOptions, type BulkResult, type BulkStartInput, type BulkStatus, type BulkUpload, type BulkUploadInput, type Caller, type CallerOptions, type Card, type CardDeep, type CardOptions, type Carrier, type CarrierDeep, type CarrierOptions, type City, type CityAmbiguityCandidate, type CityAncestorsOptions, type CityCollection, type CityCollectionFilters, type CityDeep, type CityDistance, type CityDistanceOptions, type CityGrain, type CityIdCall, type CityIdOptions, type CityList, type CityListOptions, type CityLookupCall, type CityMatch, type CityNearby, type CityNearbyCall, type CityNearbyCoordinates, type CityNearbyCoordinatesOptions, type CityNearbyOptions, type CityNearest, type CityNearestCall, type CityNearestOptions, type CityOptions, type CityPagingOptions, type CityParent, type CityRelations, type CityRelationsOptions, type CityResource, type CityResponseOptions, type CityScopeOptions, type CitySearch, type CitySearchCall, type CitySearchOptions, type CitySort, type Company, type CompanyCandidate, type CompanyCountry, type CompanyCoverage, type CompanyCoverageOptions, type CompanyDeep, type CompanyEmailAddress, type CompanyIdOptions, type CompanyMatch, type CompanyOptions, type CompanyPhoneNumber, type CompanyProfile, type CompanyProfileAddress, type CompanyProfileDeep, type CompanyProfileDomain, type CompanyProfileEmail, type CompanyProfileEmployees, type CompanyProfileFounding, type CompanyProfileIdentifier, type CompanyProfileIndustry, type CompanyProfileJurisdiction, type CompanyProfileListing, type CompanyProfilePhone, type CompanyProfileRegistration, type CompanyProfileRegistrationAddress, type CompanyProfileRegistrationLegalForm, type CompanyProfileSource, type CompanyProfileWebsite, type CompanySearch, type CompanySearchOptions, type CompanySocialProfile, 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 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 ElevationLocations, type ElevationOptions, type Email, type EmailDeep, type EmailOptions, type Emoji, type EmojiArtwork, type EmojiArtworkSource, type EmojiBrowse, type EmojiBrowseOptions, EmojiCatalog, type EmojiCatalogConvertOptions, type EmojiCatalogData, EmojiCatalogError, type EmojiCatalogLocalization, type EmojiCatalogLookupOptions, type EmojiCatalogOptions, type EmojiCatalogParseOptions, type EmojiCatalogRegexOptions, type EmojiCatalogScope, type EmojiCatalogSearchFacts, type EmojiCatalogSearchOptions, type EmojiCategories, type EmojiCategory, type EmojiConversion, type EmojiConvertOptions, type EmojiDeep, type EmojiMetadata, type EmojiNativeSearchFacts, type EmojiNotice, type EmojiOptions, type EmojiParse, type EmojiParseOptions, type EmojiPosition, type EmojiSearch, type EmojiSearchOptions, type EmojiShortcodeSourceMetadata, type EmojiSkin, type EmojiSource, type EmojiUnresolved, type EmojiVariant, type Hlr, type HlrDeep, type HlrOptions, type Holiday, type HolidayDate, type HolidayDateOptions, type HolidayOptions, type HolidayYear, type Industry, type IndustryChild, type IndustryCorrection, type IndustryDeep, type IndustryExclusion, type IndustryMatch, type IndustryOptions, type IndustrySearch, type IndustrySearchItem, type IndustrySearchOptions, type Ip, type IpDeep, type IpOptions, type IpSelfOptions, type Language, type LanguageDeep, type LanguageOption, type LanguageOptions, 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 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 PostalLocality, 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 Stack, type StackOptions, type StackTechnology, type State, type StateDeep, type StateDistrictDeep, type StateDistrictItem, type StateDistricts, type StateDistrictsOptions, type StateOptions, type Time, type TimeAtOptions, type TimeLocation, type TimeLocationCandidate, type TimeLocationInput, type TimeOptions, type TimeResolution, type TimeResolutionAlternative, type TimeSeason, type TimeTransition, type TimeTransitionState, type TimeZoneEntry, type TimeZones, type TimeZonesOptions, 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 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, createBulkClient, parseAPI };

package/dist/index.js

@@ -1,3 +1,163 @@
+// src/errors.ts
+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;
+  /** Original Retry-After response header, when supplied. */
+  retryAfter;
+  constructor(status, code, message, docs = null, requestId = null, retryAfter = null) {
+    super(message);
+    this.name = "ParseAPIError";
+    this.status = status;
+    this.code = code;
+    this.docs = docs;
+    this.requestId = requestId;
+    this.retryAfter = retryAfter;
+  }
+};
+
+// src/bulk.ts
+var BULK_CHECKS = ["email", "phone", "carrier", "caller", "hlr", "ip", "domain", "useragent", "country", "postal", "address", "name", "date"];
+var MAX_RESPONSE_BYTES = 256 * 1024;
+var jobId = /^job_[23456789abcdefghjkmnpqrstuvwxyz]{14}$/;
+var invalidResponse = () => new ParseAPIError(502, "invalid_api_response", "The Bulk service returned an invalid response.");
+function origin(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TypeError("ParseAPI Bulk webUrl must be an HTTPS origin.");
+  }
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback) || url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+    throw new TypeError("ParseAPI Bulk webUrl must be an HTTPS origin, or HTTP on loopback.");
+  }
+  return url.origin;
+}
+async function boundedJson(response) {
+  const length = response.headers.get("content-length");
+  if (length && /^\d+$/.test(length) && Number(length) > MAX_RESPONSE_BYTES) {
+    await response.body?.cancel().catch(() => {
+    });
+    throw invalidResponse();
+  }
+  if (!response.body) throw invalidResponse();
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let size = 0, text = "";
+  try {
+    while (true) {
+      const part = await reader.read();
+      if (part.done) break;
+      size += part.value.byteLength;
+      if (size > MAX_RESPONSE_BYTES) {
+        await reader.cancel().catch(() => {
+        });
+        throw invalidResponse();
+      }
+      text += decoder.decode(part.value, { stream: true });
+    }
+    text += decoder.decode();
+  } finally {
+    reader.releaseLock();
+  }
+  try {
+    const data = JSON.parse(text);
+    if (data && typeof data === "object" && !Array.isArray(data)) return data;
+  } catch {
+  }
+  throw invalidResponse();
+}
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function createBulkClient(apiKey, options = {}) {
+  const key = apiKey || (typeof process !== "undefined" ? process.env.PARSEAPI_KEY : void 0);
+  if (!key) throw new Error("createBulkClient: missing API key. Pass one or set PARSEAPI_KEY.");
+  const webUrl = origin(options.webUrl ?? (typeof process !== "undefined" ? process.env.PARSEAPI_WEB_URL : void 0) ?? "https://parseapi.com");
+  const timeout = options.timeoutMs ?? 1e4;
+  if (!Number.isSafeInteger(timeout) || timeout <= 0) throw new TypeError("ParseAPI Bulk timeoutMs must be a positive integer.");
+  const doFetch = options.fetch ?? fetch;
+  function path(id) {
+    if (typeof id !== "string" || !jobId.test(id)) throw new TypeError("ParseAPI Bulk requires a valid job ID.");
+    return `/api/agent/bulk/${id}`;
+  }
+  async function request(path2, input, controls) {
+    const signal = controls?.signal;
+    signal?.throwIfAborted();
+    const controller = new AbortController();
+    const onAbort = () => controller.abort(signal?.reason);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const timer = setTimeout(() => controller.abort(new DOMException("Request timed out", "TimeoutError")), timeout);
+    try {
+      const response = await doFetch(`${webUrl}${path2}`, {
+        method: input === void 0 ? "GET" : "POST",
+        redirect: "manual",
+        credentials: "omit",
+        headers: { "X-API-Key": key, "Parse-Version": "2.0.0", "Accept": "application/json", ...input === void 0 ? {} : { "Content-Type": "application/json" } },
+        ...input === void 0 ? {} : { body: JSON.stringify(input) },
+        signal: controller.signal
+      });
+      signal?.throwIfAborted();
+      if (response.status >= 300 && response.status < 400) {
+        await response.body?.cancel().catch(() => {
+        });
+        throw new ParseAPIError(response.status, "unexpected_redirect", "The Bulk service returned an unexpected redirect.");
+      }
+      const data = await boundedJson(response);
+      signal?.throwIfAborted();
+      if (!response.ok) throw new ParseAPIError(
+        response.status,
+        typeof data.code === "string" ? data.code : "bulk_request_failed",
+        typeof data.message === "string" ? data.message : typeof data.error === "string" ? data.error : `Bulk request failed with status ${response.status}`,
+        typeof data.docs === "string" ? data.docs : null,
+        typeof data.request_id === "string" ? data.request_id : null,
+        response.headers.get("retry-after")
+      );
+      return data;
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    }
+  }
+  async function workflow(target, id, input, controls) {
+    const data = await request(target, input, controls);
+    if (!object(data.job) || data.job.id !== id || typeof data.job.status !== "string") throw invalidResponse();
+    return data;
+  }
+  return {
+    upload: async (input, controls) => {
+      if (!object(input) || typeof input.filename !== "string" || !input.filename.trim() || input.filename.length > 200 || !Number.isSafeInteger(input.file_size) || input.file_size <= 0) throw new TypeError("Provide a filename and positive file_size in bytes.");
+      if (input.country !== void 0 && (typeof input.country !== "string" || !/^[A-Za-z]{2}$/.test(input.country))) throw new TypeError("Bulk country must be an ISO2 code.");
+      if (input.lang !== void 0 && (typeof input.lang !== "string" || input.lang.length < 2 || input.lang.length > 64)) throw new TypeError("Provide a valid Bulk display language.");
+      const data = await request("/api/agent/bulk", { filename: input.filename, file_size: input.file_size, ...input.country === void 0 ? {} : { country: input.country }, ...input.lang === void 0 ? {} : { lang: input.lang } }, controls);
+      if (typeof data.id !== "string" || !jobId.test(data.id) || typeof data.upload_url !== "string" || data.upload_method !== "PUT" || typeof data.upload_expires_at !== "string" || !object(data.upload_headers) || Object.values(data.upload_headers).some((value) => typeof value !== "string")) throw invalidResponse();
+      return data;
+    },
+    preview: async (id, input = {}, controls) => {
+      if (!object(input) || input.checks !== void 0 && (!Array.isArray(input.checks) || input.checks.length < 1 || input.checks.length > BULK_CHECKS.length || input.checks.some((check) => !BULK_CHECKS.includes(check)) || new Set(input.checks).size !== input.checks.length)) throw new TypeError("Provide distinct public Bulk checks.");
+      const data = await workflow(`${path(id)}/preview`, id, input.checks === void 0 ? {} : { checks: input.checks }, controls);
+      if (data.quote !== null && (!object(data.quote) || typeof data.quote.id !== "string" || data.quote.currency !== "USD" || !Number.isSafeInteger(data.quote.cost_cents) || data.quote.cost_cents < 0 || data.quote.expires_at !== null && typeof data.quote.expires_at !== "string")) throw invalidResponse();
+      return data;
+    },
+    start: (id, input, controls) => {
+      if (!object(input) || typeof input.quote_id !== "string" || !input.quote_id || input.quote_id.length > 512 || !Number.isSafeInteger(input.max_cost_cents) || input.max_cost_cents < 0) throw new TypeError("Provide the current quote_id and approved max_cost_cents.");
+      return workflow(`${path(id)}/start`, id, { quote_id: input.quote_id, max_cost_cents: input.max_cost_cents }, controls);
+    },
+    status: (id, controls) => workflow(path(id), id, void 0, controls),
+    result: async (id, controls) => {
+      const data = await request(`${path(id)}/result`, void 0, controls);
+      if (data.id !== id || typeof data.download_url !== "string" || typeof data.expires_at !== "string") throw invalidResponse();
+      return data;
+    }
+  };
+}
+
 // src/emoji-catalog.ts
 var EmojiCatalogError = class extends Error {
   constructor(code, message) {
@@ -256,34 +416,13 @@ var EmojiCatalog = class {
 };
 
 // src/index.ts
-var VERSION = "1.11.4";
+var VERSION = "1.12.0";
 var API_VERSION = "2.0.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;
-  /** 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;
-  }
-};
 var requestControls = (opts) => ({ signal: opts?.signal, timeoutMs: opts?.timeoutMs, retries: opts?.retries });
 function env(name) {
   return typeof process !== "undefined" ? process.env?.[name] : void 0;
@@ -714,9 +853,12 @@ function cityCollectionQuery(opts) {
   };
 }
 export {
+  BULK_CHECKS,
+  ParseAPIError as BulkAPIError,
   EmojiCatalog,
   EmojiCatalogError,
   ParseAPIError,
+  createBulkClient,
   parseAPI
 };
 /*! You found Dev. https://parseapi.com/dev */

package/package.json

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