catastrogps 1.0.0 → 1.2.0

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";
@@ -44,6 +64,7 @@ var RateLimitError = class extends CatastroGPSError {
 };
 var ServiceUnavailableError = class extends CatastroGPSError {
   name = "ServiceUnavailableError";
+  retryAfterSeconds;
 };
 var ServerError = class extends CatastroGPSError {
   name = "ServerError";
@@ -54,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;
@@ -71,7 +97,11 @@ function errorFromResponse(status, body, retryAfter) {
   if (status === 403) return new ForbiddenError(message, options);
   if (status === 404) return new NotFoundError(message, options);
   if (status === 400 || status === 422) return new ValidationError(message, options);
-  if (status === 503) return new ServiceUnavailableError(message, options);
+  if (status === 503) {
+    const error = new ServiceUnavailableError(message, options);
+    error.retryAfterSeconds = retryAfter;
+    return error;
+  }
   if (status >= 500) return new ServerError(message, options);
   return new CatastroGPSError(message, options);
 }
@@ -95,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;
@@ -128,14 +226,119 @@ 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}`;
 }
 
+// src/resources/fincas.ts
+var MAX_PAGES = 1e3;
+var FincasResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async searchAddress(query) {
+    const params = typeof query === "string" ? { q: query } : query;
+    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,
+        municipality: params.municipality?.trim(),
+        postcode: params.postcode?.trim(),
+        limit: params.limit
+      }
+    });
+  }
+  async *pages(refcat14, options = {}) {
+    const path = parcelPath(refcat14, "/units");
+    const previousByCursor = new Map((options.previous?.pages ?? []).map((page) => [page.cursor ?? "", page]));
+    let cursor;
+    for (let count = 0; count < MAX_PAGES; count += 1) {
+      const previous = previousByCursor.get(cursor ?? "");
+      const response = await this.client.conditionalRequest("GET", path, {
+        query: { cursor, country: options.country },
+        ifNoneMatch: previous?.etag
+      });
+      const data = response.notModified && previous ? previous.data : response.data;
+      if (!data) throw new CatastroGPSError("The API answered 304 for a page that was not in the previous import");
+      const page = { cursor, etag: response.etag, notModified: response.notModified, data };
+      yield page;
+      if (!data.truncated || !data.nextCursor) return;
+      cursor = data.nextCursor;
+    }
+    throw new CatastroGPSError(`Stopped after ${MAX_PAGES} pages`);
+  }
+  async units(refcat14, options = {}) {
+    const pages = [];
+    for await (const page of this.pages(refcat14, options)) pages.push(page);
+    const first = pages[0].data;
+    const last = pages[pages.length - 1].data;
+    return {
+      refCatastral: first.refCatastral,
+      direccion: first.direccion,
+      codigoPostal: first.codigoPostal,
+      municipio: first.municipio,
+      provincia: first.provincia,
+      usoGeneral: first.usoGeneral,
+      anioConstruccion: first.anioConstruccion,
+      totalUnidadesFinca: last.totalUnidadesFinca ?? pages.reduce((sum, p) => sum + p.data.unidades.length, 0),
+      unidades: pages.flatMap((page) => page.data.unidades),
+      construcciones: pages.flatMap((page) => page.data.construcciones ?? []),
+      dataSource: first.dataSource,
+      dataDate: first.dataDate,
+      attribution: first.attribution,
+      changed: !pages.every((page) => page.notModified) || pages.length !== (options.previous?.pages.length ?? -1),
+      pages
+    };
+  }
+};
+
 // src/version.ts
-var VERSION = "1.0.0";
+var VERSION = "1.2.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.catastrogps.es";
@@ -143,9 +346,12 @@ var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_RETRIES = 2;
 var BACKOFF_BASE_MS = 500;
 var RETRYABLE_STATUS = /* @__PURE__ */ new Set([502, 503, 504]);
+var NOT_MODIFIED = 304;
+var MAX_RETRY_AFTER_SECONDS = 60;
 var CatastroGPS = class {
   parcels;
   export;
+  fincas;
   lastQuota;
   apiKey;
   baseUrl;
@@ -170,11 +376,25 @@ var CatastroGPS = class {
     this.fetchImpl = fetchImpl;
     this.parcels = new ParcelsResource(this);
     this.export = new ExportResource(this);
+    this.fincas = new FincasResource(this);
+  }
+  async searchAddressCandidates(query) {
+    return this.fincas.searchAddress(query);
+  }
+  async getUnits(refcat14, options = {}) {
+    return this.fincas.units(refcat14, options);
+  }
+  iterUnitPages(refcat14, options = {}) {
+    return this.fincas.pages(refcat14, options);
   }
   async resolve(text, options = {}) {
     return this.request("GET", "/api/resolve", { query: { q: text, hint: options.hint } });
   }
   async request(method, path, options = {}) {
+    const result = await this.conditionalRequest(method, path, options);
+    return result.data;
+  }
+  async conditionalRequest(method, path, options = {}) {
     const url = this.buildUrl(path, options.query);
     let attempt = 0;
     for (; ; ) {
@@ -196,6 +416,7 @@ var CatastroGPS = class {
       "User-Agent": `catastrogps-js/${VERSION}`
     };
     if (options.body !== void 0) headers["Content-Type"] = "application/json";
+    if (options.ifNoneMatch) headers["If-None-Match"] = options.ifNoneMatch;
     let response;
     try {
       response = await this.fetchImpl(url, {
@@ -212,15 +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, 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 await response.arrayBuffer();
+    if (options.raw) return { data: await response.arrayBuffer(), etag, notModified: false, quota };
     const body = await readJson(response);
-    return "data" in body ? body.data : body;
+    return { data: "data" in body ? body.data : body, etag, notModified: false, quota };
   }
   buildUrl(path, query) {
     const url = new URL(`${this.baseUrl}${path}`);
@@ -236,21 +464,56 @@ var CatastroGPS = class {
     return error instanceof CatastroGPSError && error.status !== void 0 && RETRYABLE_STATUS.has(error.status);
   }
   retryDelayMs(error, attempt) {
-    if (error instanceof RateLimitError && error.retryAfterSeconds) return error.retryAfterSeconds * 1e3;
+    if ((error instanceof RateLimitError || error instanceof ServiceUnavailableError) && error.retryAfterSeconds) {
+      return Math.min(error.retryAfterSeconds, MAX_RETRY_AFTER_SECONDS) * 1e3;
+    }
     return BACKOFF_BASE_MS * 2 ** attempt;
   }
   captureQuota(headers) {
-    const limit = headers.get("X-RateLimit-Limit");
-    if (limit === null) return;
-    const remaining = headers.get("X-RateLimit-Remaining");
-    this.lastQuota = {
-      plan: headers.get("X-Quota-Tier") ?? void 0,
-      limit: Number(limit),
-      remaining: remaining === null ? void 0 : Number(remaining),
-      resetsAt: headers.get("X-RateLimit-Reset") ?? void 0
-    };
+    const quota = readQuota(headers);
+    if (quota) this.lastQuota = quota;
+    return quota;
   }
 };
+function readQuota(headers) {
+  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 {
     const parsed = await response.json();
@@ -266,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,
@@ -316,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.0.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.0",
+  "description": "Official JavaScript/TypeScript client for the Catastro GPS API: parcels from 26 European cadastres plus 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"