catastrogps 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -14,11 +14,33 @@ interface CatastroGPSOptions {
 interface CountryOption<C extends string = CountryCode> {
     country?: C;
 }
+declare const ADDRESS_COUNTRY_CODES: readonly ["ES", "FR", "IT", "DE", "AT", "NL", "BE", "PL", "CH", "CZ", "DK", "NO", "FI", "EE", "LV", "LT", "SI", "SK", "BG", "GR", "CY", "LU", "LI", "IS", "IE", "UK", "PT"];
+type AddressCountryCode = (typeof ADDRESS_COUNTRY_CODES)[number];
+declare const UNITS_COUNTRY_CODES: readonly ["ES", "PV", "NA"];
+type UnitsCountryCode = (typeof UNITS_COUNTRY_CODES)[number];
+interface PrepaidOverage {
+    enabled: boolean;
+    balance?: number;
+    unitPrice?: number;
+    remainingUnits?: number;
+}
+interface BurstLimit {
+    limit?: number;
+    remaining?: number;
+    resetSeconds?: number;
+}
+interface FincaCap {
+    cap?: number;
+    used?: number;
+}
 interface Quota {
     plan?: string;
     limit?: number;
     remaining?: number;
     resetsAt?: string;
+    overage?: PrepaidOverage;
+    rateLimit?: BurstLimit;
+    fincaCap?: FincaCap;
 }
 interface Parcel {
     refCatastral: string;
@@ -119,6 +141,7 @@ interface ResolveResult {
 }
 interface AddressCandidatesQuery {
     q?: string;
+    country?: AddressCountryCode;
     street?: string;
     number?: number;
     municipality?: string;
@@ -219,8 +242,130 @@ interface UnitsResult {
     pages: UnitsPage[];
 }
 interface GetUnitsOptions {
+    country?: UnitsCountryCode;
     previous?: UnitsResult;
 }
+interface LocatedOptions extends CountryOption<Exclude<CountryCode, 'UK' | 'HR'>> {
+    lat?: number;
+    lng?: number;
+}
+interface DataSource {
+    name?: string;
+    provider?: string;
+    license?: string;
+    attribution?: string;
+    url?: string;
+    resolution?: string;
+    edition?: string;
+}
+type BlockStatus = 'ok' | 'no_data' | 'unavailable';
+interface ProtectedSite {
+    code: string;
+    name: string;
+    type?: 'SPA' | 'SCI' | 'SPA_SCI' | string;
+    designation?: string;
+    country?: string;
+    overlap_pct?: number | null;
+}
+interface Terrain {
+    refcat: string;
+    country: string;
+    relief: {
+        status: BlockStatus;
+        elevation_m?: {
+            mean: number;
+            min: number;
+            max: number;
+        };
+        slope?: {
+            mean_pct: number;
+            mean_deg: number;
+            max_pct: number;
+            class: string;
+            max_class: string;
+            share_over_10_pct: number;
+            classes_pct: Record<string, number>;
+        };
+        aspect?: {
+            dominant: string;
+            dominant_share_pct: number;
+            mean_deg: number | null;
+            flat_share_pct: number;
+            sectors_pct: Record<string, number>;
+        };
+        sample?: {
+            method: string;
+            cells: number;
+            resolution_m: number;
+        };
+        source?: DataSource;
+    };
+    protected_areas: {
+        status: BlockStatus;
+        intersects?: boolean;
+        inside?: boolean;
+        max_overlap_pct?: number | null;
+        natura2000?: ProtectedSite[];
+        national?: ProtectedSite[];
+        method?: string;
+        sources?: DataSource[];
+    };
+    climate?: {
+        status: BlockStatus;
+        baseline?: Record<string, number>;
+        recent?: Record<string, number>;
+        [key: string]: unknown;
+    };
+    calculated_at?: string;
+    provenance?: string;
+}
+interface GroundMotion {
+    refcat: string;
+    country: string;
+    status: BlockStatus;
+    reason?: 'no_reflectors' | 'outside_coverage' | 'parcel_too_large' | string;
+    period?: {
+        from: string;
+        to: string;
+        label: string;
+    };
+    ground_motion?: {
+        class: string;
+        worst_class?: string;
+        vertical: {
+            mean_mm_year: number;
+            max_subsidence_mm_year?: number;
+            max_uplift_mm_year?: number;
+            std_mm_year?: number;
+            acceleration_mm_year2?: number;
+            rmse_mm?: number;
+        };
+        east_west?: {
+            mean_mm_year: number;
+            std_mm_year?: number;
+        };
+        yearly_displacement?: Array<{
+            year: number;
+            mm: number;
+        }>;
+        cells_with_data: number;
+        cells_considered: number;
+        coverage_pct: number;
+        basis?: 'parcel' | 'surroundings' | string;
+        cell_size_m?: number;
+    };
+    source?: DataSource;
+    calculated_at?: string;
+    provenance?: string;
+}
+type MarketData = Record<string, unknown>;
+type ScoreData = Record<string, unknown>;
+type ValueHistory = Record<string, unknown>;
+type Comparison = Record<string, unknown>;
+interface CompareItem {
+    reference: string;
+    country: EnrichmentCountryCode;
+}
 
 declare class ExportResource {
     private readonly client;
@@ -249,6 +394,12 @@ declare class ParcelsResource {
     geometry(reference: string, options?: CountryOption<Exclude<CountryCode, 'UK'>>): Promise<ParcelGeometry>;
     solar(reference: string, options?: CountryOption<EnrichmentCountryCode>): Promise<SolarEstimate>;
     agriculture(reference: string, options?: CountryOption<EnrichmentCountryCode>): Promise<AgricultureData>;
+    terrain(reference: string, options?: LocatedOptions): Promise<Terrain>;
+    groundMotion(reference: string, options?: LocatedOptions): Promise<GroundMotion>;
+    market(reference: string, options?: CountryOption<EnrichmentCountryCode>): Promise<MarketData>;
+    score(reference: string, options?: CountryOption<EnrichmentCountryCode>): Promise<ScoreData>;
+    valueHistory(reference: string, options?: CountryOption<EnrichmentCountryCode | 'AT'>): Promise<ValueHistory>;
+    compare(parcels: CompareItem[]): Promise<Comparison>;
 }
 
 declare const DEFAULT_BASE_URL = "https://api.catastrogps.es";
@@ -265,6 +416,7 @@ interface ConditionalResponse<T> {
     data?: T;
     etag?: string;
     notModified: boolean;
+    quota?: Quota;
 }
 declare class CatastroGPS {
     readonly parcels: ParcelsResource;
@@ -291,8 +443,9 @@ declare class CatastroGPS {
     private retryDelayMs;
     private captureQuota;
 }
+declare function readQuota(headers: Headers): Quota | undefined;
 
-declare const VERSION = "1.1.0";
+declare const VERSION = "1.2.0";
 
 declare class CatastroGPSError extends Error {
     readonly status?: number;
@@ -318,8 +471,20 @@ declare class NotFoundError extends CatastroGPSError {
 declare class ValidationError extends CatastroGPSError {
     name: string;
 }
+declare class PlaceNameError extends ValidationError {
+    name: string;
+    get location(): {
+        lat: number;
+        lng: number;
+        address?: string;
+        label?: string;
+    } | undefined;
+}
 declare class CoverageError extends CatastroGPSError {
     name: string;
+    get country(): string | undefined;
+    get feature(): string | undefined;
+    get supportedCountries(): string[];
 }
 declare class AmbiguousReferenceError extends CatastroGPSError {
     name: string;
@@ -331,6 +496,8 @@ declare class AmbiguousReferenceError extends CatastroGPSError {
 }
 declare class QuotaExceededError extends CatastroGPSError {
     name: string;
+    quota?: Quota;
+    get prepaidBalanceEmpty(): boolean;
 }
 declare class RateLimitError extends CatastroGPSError {
     name: string;
@@ -350,4 +517,4 @@ declare class NetworkError extends CatastroGPSError {
     name: string;
 }
 
-export { type AddressCandidate, type AddressCandidatesQuery, type AddressCandidatesResult, type AddressMatch, type AgricultureData, AmbiguousReferenceError, AuthenticationError, COUNTRY_CODES, CatastroGPS, CatastroGPSError, type CatastroGPSOptions, type ConditionalResponse, type Construction, type CountryCode, type CountryOption, CoverageError, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, ENRICHMENT_COUNTRY_CODES, type EnrichmentCountryCode, type ExportFormat, type FetchLike, ForbiddenError, type GetUnitsOptions, NetworkError, NotFoundError, type Parcel, type ParcelGeometry, type PointMatch, type PointQuery, type Quota, QuotaExceededError, RateLimitError, type ResolveCandidate, type ResolveResult, ServerError, ServiceUnavailableError, type SolarEstimate, TimeoutError, type Unit, type UnitsPage, type UnitsPageData, type UnitsResult, VERSION, ValidationError };
+export { ADDRESS_COUNTRY_CODES, type AddressCandidate, type AddressCandidatesQuery, type AddressCandidatesResult, type AddressCountryCode, type AddressMatch, type AgricultureData, AmbiguousReferenceError, AuthenticationError, type BlockStatus, type BurstLimit, COUNTRY_CODES, CatastroGPS, CatastroGPSError, type CatastroGPSOptions, type CompareItem, type Comparison, type ConditionalResponse, type Construction, type CountryCode, type CountryOption, CoverageError, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, type DataSource, ENRICHMENT_COUNTRY_CODES, type EnrichmentCountryCode, type ExportFormat, type FetchLike, type FincaCap, ForbiddenError, type GetUnitsOptions, type GroundMotion, type LocatedOptions, type MarketData, NetworkError, NotFoundError, type Parcel, type ParcelGeometry, PlaceNameError, type PointMatch, type PointQuery, type PrepaidOverage, type ProtectedSite, type Quota, QuotaExceededError, RateLimitError, type ResolveCandidate, type ResolveResult, type ScoreData, ServerError, ServiceUnavailableError, type SolarEstimate, type Terrain, TimeoutError, UNITS_COUNTRY_CODES, type Unit, type UnitsCountryCode, type UnitsPage, type UnitsPageData, type UnitsResult, VERSION, ValidationError, type ValueHistory, readQuota };

package/dist/index.js

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ADDRESS_COUNTRY_CODES: () => ADDRESS_COUNTRY_CODES,
   AmbiguousReferenceError: () => AmbiguousReferenceError,
   AuthenticationError: () => AuthenticationError,
   COUNTRY_CODES: () => COUNTRY_CODES,
@@ -33,13 +34,16 @@ __export(index_exports, {
   ForbiddenError: () => ForbiddenError,
   NetworkError: () => NetworkError,
   NotFoundError: () => NotFoundError,
+  PlaceNameError: () => PlaceNameError,
   QuotaExceededError: () => QuotaExceededError,
   RateLimitError: () => RateLimitError,
   ServerError: () => ServerError,
   ServiceUnavailableError: () => ServiceUnavailableError,
   TimeoutError: () => TimeoutError,
+  UNITS_COUNTRY_CODES: () => UNITS_COUNTRY_CODES,
   VERSION: () => VERSION,
-  ValidationError: () => ValidationError
+  ValidationError: () => ValidationError,
+  readQuota: () => readQuota
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -70,8 +74,24 @@ var NotFoundError = class extends CatastroGPSError {
 var ValidationError = class extends CatastroGPSError {
   name = "ValidationError";
 };
+var PlaceNameError = class extends ValidationError {
+  name = "PlaceNameError";
+  get location() {
+    const details = this.details;
+    return details?.location;
+  }
+};
 var CoverageError = class extends CatastroGPSError {
   name = "CoverageError";
+  get country() {
+    return this.details?.country;
+  }
+  get feature() {
+    return this.details?.feature;
+  }
+  get supportedCountries() {
+    return this.details?.supportedCountries ?? [];
+  }
 };
 var AmbiguousReferenceError = class extends CatastroGPSError {
   name = "AmbiguousReferenceError";
@@ -82,6 +102,10 @@ var AmbiguousReferenceError = class extends CatastroGPSError {
 };
 var QuotaExceededError = class extends CatastroGPSError {
   name = "QuotaExceededError";
+  quota;
+  get prepaidBalanceEmpty() {
+    return this.quota?.overage?.enabled === true;
+  }
 };
 var RateLimitError = class extends CatastroGPSError {
   name = "RateLimitError";
@@ -100,14 +124,19 @@ var TimeoutError = class extends CatastroGPSError {
 var NetworkError = class extends CatastroGPSError {
   name = "NetworkError";
 };
-function errorFromResponse(status, body, retryAfter) {
+function errorFromResponse(status, body, retryAfter, quota) {
   const code = typeof body.code === "string" ? body.code : void 0;
   const message = typeof body.error === "string" && body.error || typeof body.message === "string" && body.message || `HTTP ${status}`;
   const details = body.data ?? body.parsed;
   const options = { status, code, details, body };
   if (code === "CNV_AMBIGUOUS" || status === 300) return new AmbiguousReferenceError(message, options);
   if (code === "CNV_COVERAGE") return new CoverageError(message, options);
-  if (code === "KEY_AUTH_004") return new QuotaExceededError(message, options);
+  if (code === "CNV_PLACE_NAME") return new PlaceNameError(message, options);
+  if (code === "KEY_AUTH_004") {
+    const error = new QuotaExceededError(message, options);
+    error.quota = quota;
+    return error;
+  }
   if (status === 429) {
     const error = new RateLimitError(message, options);
     error.retryAfterSeconds = retryAfter;
@@ -145,7 +174,75 @@ var ExportResource = class {
   }
 };
 
+// src/types.ts
+var COUNTRY_CODES = [
+  "ES",
+  "PV",
+  "NA",
+  "PT",
+  "FR",
+  "IT",
+  "DE",
+  "AT",
+  "CH",
+  "LI",
+  "BE",
+  "NL",
+  "LU",
+  "PL",
+  "CZ",
+  "SK",
+  "SI",
+  "HR",
+  "BG",
+  "GR",
+  "CY",
+  "DK",
+  "SE",
+  "NO",
+  "FI",
+  "IS",
+  "EE",
+  "LV",
+  "LT",
+  "IE",
+  "UK"
+];
+var ENRICHMENT_COUNTRY_CODES = ["ES", "PV", "NA", "PT", "FR", "IT", "DE"];
+var ADDRESS_COUNTRY_CODES = [
+  "ES",
+  "FR",
+  "IT",
+  "DE",
+  "AT",
+  "NL",
+  "BE",
+  "PL",
+  "CH",
+  "CZ",
+  "DK",
+  "NO",
+  "FI",
+  "EE",
+  "LV",
+  "LT",
+  "SI",
+  "SK",
+  "BG",
+  "GR",
+  "CY",
+  "LU",
+  "LI",
+  "IS",
+  "IE",
+  "UK",
+  "PT"
+];
+var UNITS_COUNTRY_CODES = ["ES", "PV", "NA"];
+
 // src/resources/parcels.ts
+var MIN_COMPARE = 2;
+var MAX_COMPARE = 3;
 var ParcelsResource = class {
   constructor(client) {
     this.client = client;
@@ -178,7 +275,46 @@ var ParcelsResource = class {
     });
     return data.agro ?? data;
   }
+  async terrain(reference, options = {}) {
+    return this.client.request("GET", parcelPath(reference, "/terrain"), { query: locatedQuery(options) });
+  }
+  async groundMotion(reference, options = {}) {
+    return this.client.request("GET", parcelPath(reference, "/ground-motion"), { query: locatedQuery(options) });
+  }
+  async market(reference, options = {}) {
+    return this.client.request("GET", parcelPath(reference, "/market"), { query: { country: options.country } });
+  }
+  async score(reference, options = {}) {
+    return this.client.request("GET", parcelPath(reference, "/score"), { query: { country: options.country } });
+  }
+  async valueHistory(reference, options = {}) {
+    return this.client.request("GET", parcelPath(reference, "/value-history"), {
+      query: { country: options.country }
+    });
+  }
+  async compare(parcels) {
+    if (parcels.length < MIN_COMPARE || parcels.length > MAX_COMPARE) {
+      throw new CatastroGPSError(`compare takes ${MIN_COMPARE} or ${MAX_COMPARE} parcels`);
+    }
+    const parcelas = parcels.map((parcel) => {
+      if (!parcel.reference?.trim()) throw new CatastroGPSError("reference must not be empty");
+      if (!ENRICHMENT_COUNTRY_CODES.includes(parcel.country)) {
+        throw new CatastroGPSError(`country must be one of ${ENRICHMENT_COUNTRY_CODES.join(", ")}`);
+      }
+      return { ref_catastral: parcel.reference.trim(), country: parcel.country };
+    });
+    return this.client.request("POST", "/api/catastro/compare", { body: { parcelas } });
+  }
 };
+function locatedQuery(options) {
+  const hasLat = options.lat !== void 0;
+  const hasLng = options.lng !== void 0;
+  if (hasLat !== hasLng) throw new CatastroGPSError("lat and lng go together");
+  if (hasLat && (!Number.isFinite(options.lat) || !Number.isFinite(options.lng))) {
+    throw new CatastroGPSError("lat and lng must be finite numbers");
+  }
+  return { country: options.country, lat: options.lat, lng: options.lng };
+}
 function parcelPath(reference, suffix = "") {
   if (!reference.trim()) throw new CatastroGPSError("reference must not be empty");
   return `/api/catastro/${encodeURIComponent(reference.trim())}${suffix}`;
@@ -196,6 +332,7 @@ var FincasResource = class {
     if (!params.q?.trim() && !params.street?.trim()) throw new CatastroGPSError("q or street is required");
     return this.client.request("GET", "/api/search/address/candidates", {
       query: {
+        country: params.country,
         q: params.q?.trim(),
         street: params.street?.trim(),
         number: params.number,
@@ -212,7 +349,7 @@ var FincasResource = class {
     for (let count = 0; count < MAX_PAGES; count += 1) {
       const previous = previousByCursor.get(cursor ?? "");
       const response = await this.client.conditionalRequest("GET", path, {
-        query: { cursor },
+        query: { cursor, country: options.country },
         ifNoneMatch: previous?.etag
       });
       const data = response.notModified && previous ? previous.data : response.data;
@@ -250,7 +387,7 @@ var FincasResource = class {
 };
 
 // src/version.ts
-var VERSION = "1.1.0";
+var VERSION = "1.2.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.catastrogps.es";
@@ -345,17 +482,22 @@ var CatastroGPS = class {
     } finally {
       clearTimeout(timer);
     }
-    this.captureQuota(response.headers);
+    const quota = this.captureQuota(response.headers);
     const etag = response.headers.get("ETag") ?? void 0;
-    if (response.status === NOT_MODIFIED) return { etag: etag ?? options.ifNoneMatch, notModified: true };
+    if (response.status === NOT_MODIFIED) return { etag: etag ?? options.ifNoneMatch, notModified: true, quota };
     if (!response.ok) {
       const body2 = await readJson(response);
       const retryAfter = Number(response.headers.get("Retry-After"));
-      throw errorFromResponse(response.status, body2, Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : void 0);
+      throw errorFromResponse(
+        response.status,
+        body2,
+        Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : void 0,
+        readQuota(response.headers)
+      );
     }
-    if (options.raw) return { data: await response.arrayBuffer(), etag, notModified: false };
+    if (options.raw) return { data: await response.arrayBuffer(), etag, notModified: false, quota };
     const body = await readJson(response);
-    return { data: "data" in body ? body.data : body, etag, notModified: false };
+    return { data: "data" in body ? body.data : body, etag, notModified: false, quota };
   }
   buildUrl(path, query) {
     const url = new URL(`${this.baseUrl}${path}`);
@@ -379,20 +521,47 @@ var CatastroGPS = class {
   captureQuota(headers) {
     const quota = readQuota(headers);
     if (quota) this.lastQuota = quota;
+    return quota;
   }
 };
 function readQuota(headers) {
-  const plan = headers.get("X-Quota-Tier") ?? void 0;
-  const family = headers.has("X-Quota-Limit") ? "X-Quota" : plan ? "X-RateLimit" : void 0;
-  if (!family) return void 0;
-  const limit = headers.get(`${family}-Limit`);
-  const remaining = headers.get(`${family}-Remaining`);
-  return {
-    plan,
-    limit: limit === null ? void 0 : Number(limit),
-    remaining: remaining === null ? void 0 : Number(remaining),
-    resetsAt: headers.get(`${family}-Reset`) ?? void 0
-  };
+  const quota = {};
+  const plan = headers.get("X-Quota-Tier");
+  if (plan !== null) quota.plan = plan;
+  const limit = numberHeader(headers, "X-Quota-Limit");
+  if (limit !== void 0) quota.limit = limit;
+  const remaining = numberHeader(headers, "X-Quota-Remaining");
+  if (remaining !== void 0) quota.remaining = remaining;
+  const resetsAt = headers.get("X-Quota-Reset");
+  if (resetsAt !== null) quota.resetsAt = resetsAt;
+  if (headers.get("X-Quota-Overage")?.toLowerCase() === "on") {
+    quota.overage = {
+      enabled: true,
+      balance: numberHeader(headers, "X-Quota-Balance"),
+      unitPrice: numberHeader(headers, "X-Quota-Overage-Unit-Price"),
+      remainingUnits: numberHeader(headers, "X-Quota-Overage-Remaining")
+    };
+  }
+  if (headers.has("X-RateLimit-Limit") || headers.has("X-RateLimit-Remaining")) {
+    quota.rateLimit = {
+      limit: numberHeader(headers, "X-RateLimit-Limit"),
+      remaining: numberHeader(headers, "X-RateLimit-Remaining"),
+      resetSeconds: numberHeader(headers, "X-RateLimit-Reset")
+    };
+  }
+  if (headers.has("X-Quota-Finca-Cap")) {
+    quota.fincaCap = {
+      cap: numberHeader(headers, "X-Quota-Finca-Cap"),
+      used: numberHeader(headers, "X-Quota-Finca-Cap-Used")
+    };
+  }
+  return Object.keys(quota).length > 0 ? quota : void 0;
+}
+function numberHeader(headers, name) {
+  const raw = headers.get(name);
+  if (raw === null || raw.trim() === "") return void 0;
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : void 0;
 }
 async function readJson(response) {
   try {
@@ -409,44 +578,9 @@ function readEnv(name) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-
-// src/types.ts
-var COUNTRY_CODES = [
-  "ES",
-  "PV",
-  "NA",
-  "PT",
-  "FR",
-  "IT",
-  "DE",
-  "AT",
-  "CH",
-  "LI",
-  "BE",
-  "NL",
-  "LU",
-  "PL",
-  "CZ",
-  "SK",
-  "SI",
-  "HR",
-  "BG",
-  "GR",
-  "CY",
-  "DK",
-  "SE",
-  "NO",
-  "FI",
-  "IS",
-  "EE",
-  "LV",
-  "LT",
-  "IE",
-  "UK"
-];
-var ENRICHMENT_COUNTRY_CODES = ["ES", "PV", "NA", "PT", "FR", "IT", "DE"];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ADDRESS_COUNTRY_CODES,
   AmbiguousReferenceError,
   AuthenticationError,
   COUNTRY_CODES,
@@ -460,11 +594,14 @@ var ENRICHMENT_COUNTRY_CODES = ["ES", "PV", "NA", "PT", "FR", "IT", "DE"];
   ForbiddenError,
   NetworkError,
   NotFoundError,
+  PlaceNameError,
   QuotaExceededError,
   RateLimitError,
   ServerError,
   ServiceUnavailableError,
   TimeoutError,
+  UNITS_COUNTRY_CODES,
   VERSION,
-  ValidationError
+  ValidationError,
+  readQuota
 });