catastrogps 1.1.0 → 1.2.1

package/dist/index.mjs

@@ -25,8 +25,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";
@@ -37,6 +53,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";
@@ -55,14 +75,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;
@@ -100,7 +125,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;
@@ -133,7 +226,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}`;
@@ -151,6 +283,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,
@@ -167,7 +300,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;
@@ -205,7 +338,7 @@ var FincasResource = class {
 };
 
 // src/version.ts
-var VERSION = "1.1.0";
+var VERSION = "1.2.1";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.catastrogps.es";
@@ -300,17 +433,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}`);
@@ -334,20 +472,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 {
@@ -364,43 +529,8 @@ 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"];
 export {
+  ADDRESS_COUNTRY_CODES,
   AmbiguousReferenceError,
   AuthenticationError,
   COUNTRY_CODES,
@@ -414,11 +544,14 @@ export {
   ForbiddenError,
   NetworkError,
   NotFoundError,
+  PlaceNameError,
   QuotaExceededError,
   RateLimitError,
   ServerError,
   ServiceUnavailableError,
   TimeoutError,
+  UNITS_COUNTRY_CODES,
   VERSION,
-  ValidationError
+  ValidationError,
+  readQuota
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "catastrogps",
-  "version": "1.1.0",
-  "description": "Official JavaScript/TypeScript client for the Catastro GPS API: cadastral parcels in 31 European countries and regions by reference, coordinates or Spanish address",
+  "version": "1.2.1",
+  "description": "Official JavaScript/TypeScript client for the Catastro GPS API: parcels from 29 European countries (31 official cadastres, including the Basque Country and Navarre) by reference, coordinates or address; building units, terrain, ground motion, solar and more",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -28,6 +28,7 @@
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
   "keywords": [
@@ -48,6 +49,9 @@
     "germany",
     "real-estate",
     "proptech",
+    "copernicus",
+    "natura-2000",
+    "ground-motion",
     "sdk"
   ],
   "author": "The Hidden Panda <soporte@catastrogps.es>",
@@ -57,10 +61,11 @@
     "email": "soporte@catastrogps.es"
   },
   "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.2.7",
     "tsup": "^8.0.0",
     "typescript": "^5.4.0",
-    "vitest": "^3.0.0",
-    "@types/node": "^22.0.0"
+    "vitest": "^3.0.0"
   },
   "engines": {
     "node": ">=18.0.0"