catastrogps 1.0.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;
@@ -117,6 +139,233 @@ interface ResolveResult {
     candidates: ResolveCandidate[];
     ambiguous: boolean;
 }
+interface AddressCandidatesQuery {
+    q?: string;
+    country?: AddressCountryCode;
+    street?: string;
+    number?: number;
+    municipality?: string;
+    postcode?: string;
+    limit?: number;
+}
+interface AddressCandidate {
+    refCatastral: string;
+    pais: 'ES' | 'PV' | 'NA' | string;
+    direccion: string;
+    numero?: number;
+    codigoPostal?: string;
+    municipio: string;
+    provincia: string;
+    latitud: number;
+    longitud: number;
+    confianza: number;
+    coincideNumero: boolean;
+    coincideMunicipio: boolean;
+    enCopia: boolean;
+    direccionCatastro?: string;
+    uso?: string;
+    viviendas?: number;
+    anioConstruccion?: number;
+}
+interface AddressCandidatesResult {
+    consulta: {
+        texto: string;
+        calle?: string;
+        numero?: number;
+        municipio?: string;
+        codigoPostal?: string;
+    };
+    candidatos: AddressCandidate[];
+    attribution: string;
+}
+interface Unit {
+    refCatastral: string;
+    escalera: string;
+    planta: string;
+    puerta: string;
+    uso: string;
+    superficie: number;
+    descripcion: string;
+    participacion?: number;
+    anio?: number;
+    direccion?: string;
+}
+interface Construction {
+    escalera: string;
+    planta: string;
+    puerta: string;
+    uso: string;
+    superficie: number;
+    descripcion: string;
+}
+interface UnitsPageData {
+    refCatastral: string;
+    direccion?: string;
+    codigoPostal?: string;
+    municipio?: string;
+    provincia?: string;
+    usoGeneral?: string;
+    superficieTotal?: number;
+    anioConstruccion?: number;
+    participacion?: string;
+    totalUnidades: number;
+    totalUnidadesFinca: number;
+    unidades: Unit[];
+    construcciones?: Construction[];
+    truncated: boolean;
+    nextCursor?: string;
+    dataSource: 'clone' | 'catastro' | string;
+    dataDate: string;
+    attribution: string;
+}
+interface UnitsPage {
+    cursor?: string;
+    etag?: string;
+    notModified: boolean;
+    data: UnitsPageData;
+}
+interface UnitsResult {
+    refCatastral: string;
+    direccion?: string;
+    codigoPostal?: string;
+    municipio?: string;
+    provincia?: string;
+    usoGeneral?: string;
+    anioConstruccion?: number;
+    totalUnidadesFinca: number;
+    unidades: Unit[];
+    construcciones: Construction[];
+    dataSource: string;
+    dataDate: string;
+    attribution: string;
+    changed: boolean;
+    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;
@@ -124,6 +373,14 @@ declare class ExportResource {
     file(reference: string, format: ExportFormat, options?: CountryOption): Promise<ArrayBuffer>;
 }
 
+declare class FincasResource {
+    private readonly client;
+    constructor(client: CatastroGPS);
+    searchAddress(query: string | AddressCandidatesQuery): Promise<AddressCandidatesResult>;
+    pages(refcat14: string, options?: GetUnitsOptions): AsyncGenerator<UnitsPage>;
+    units(refcat14: string, options?: GetUnitsOptions): Promise<UnitsResult>;
+}
+
 interface PointQuery extends CountryOption {
     lat: number;
     lng: number;
@@ -137,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";
@@ -147,10 +410,18 @@ interface RequestOptions {
     query?: Query;
     body?: unknown;
     raw?: boolean;
+    ifNoneMatch?: string;
+}
+interface ConditionalResponse<T> {
+    data?: T;
+    etag?: string;
+    notModified: boolean;
+    quota?: Quota;
 }
 declare class CatastroGPS {
     readonly parcels: ParcelsResource;
     readonly export: ExportResource;
+    readonly fincas: FincasResource;
     lastQuota?: Quota;
     private readonly apiKey;
     private readonly baseUrl;
@@ -158,18 +429,23 @@ declare class CatastroGPS {
     private readonly maxRetries;
     private readonly fetchImpl;
     constructor(options?: CatastroGPSOptions);
+    searchAddressCandidates(query: string | AddressCandidatesQuery): Promise<AddressCandidatesResult>;
+    getUnits(refcat14: string, options?: GetUnitsOptions): Promise<UnitsResult>;
+    iterUnitPages(refcat14: string, options?: GetUnitsOptions): AsyncGenerator<UnitsPage>;
     resolve(text: string, options?: {
         hint?: string;
     }): Promise<ResolveResult>;
     request<T>(method: 'GET' | 'POST', path: string, options?: RequestOptions): Promise<T>;
+    conditionalRequest<T>(method: 'GET' | 'POST', path: string, options?: RequestOptions): Promise<ConditionalResponse<T>>;
     private once;
     private buildUrl;
     private shouldRetry;
     private retryDelayMs;
     private captureQuota;
 }
+declare function readQuota(headers: Headers): Quota | undefined;
 
-declare const VERSION = "1.0.0";
+declare const VERSION = "1.2.0";
 
 declare class CatastroGPSError extends Error {
     readonly status?: number;
@@ -195,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;
@@ -208,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;
@@ -215,6 +505,7 @@ declare class RateLimitError extends CatastroGPSError {
 }
 declare class ServiceUnavailableError extends CatastroGPSError {
     name: string;
+    retryAfterSeconds?: number;
 }
 declare class ServerError extends CatastroGPSError {
     name: string;
@@ -226,4 +517,4 @@ declare class NetworkError extends CatastroGPSError {
     name: string;
 }
 
-export { type AddressMatch, type AgricultureData, AmbiguousReferenceError, AuthenticationError, COUNTRY_CODES, CatastroGPS, CatastroGPSError, type CatastroGPSOptions, type CountryCode, type CountryOption, CoverageError, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, ENRICHMENT_COUNTRY_CODES, type EnrichmentCountryCode, type ExportFormat, type FetchLike, ForbiddenError, NetworkError, NotFoundError, type Parcel, type ParcelGeometry, type PointMatch, type PointQuery, type Quota, QuotaExceededError, RateLimitError, type ResolveCandidate, type ResolveResult, ServerError, ServiceUnavailableError, type SolarEstimate, TimeoutError, 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 };