@cenogram/mcp-server 0.2.0 → 0.5.0

package/dist/api-client.js

@@ -3,6 +3,22 @@ import { getClientId } from "./client-id.js";
 import { authErrorMessage, getAuthMode } from "./error-messages.js";
 import { requestContext } from "./request-context.js";
 const BASE_URL = process.env.CENOGRAM_API_URL || "https://cenogram.pl";
+export function getDemographics(params, apiKey) {
+    return fetchApi("/api/v1/demographics", toQueryParams({
+        location: params.location,
+        teryt: params.teryt,
+        year: params.year,
+        yearFrom: params.yearFrom,
+        yearTo: params.yearTo,
+        category: params.category,
+    }), apiKey);
+}
+export function getInfrastructureSignals(params, apiKey) {
+    return fetchApi("/api/v1/infrastructure-signals", toQueryParams({
+        location: params.location,
+        teryt: params.teryt,
+    }), apiKey);
+}
 function extractCreditInfo(res) {
     if (!res.headers)
         return null;
@@ -12,14 +28,22 @@ function extractCreditInfo(res) {
         return null;
     return { balance, cost };
 }
-// ── OAuth internal auth ────────────────────────────────────────────
-// SOH char (\x01) is impossible in base64url or ctx_ keys - used as both prefix and separator
-const OAUTH_CTX_PREFIX = "\x01";
+export const OAUTH_CTX_PREFIX = "\x01";
 export function encodeOAuthCtx(userId, grantId) {
-    // \x01{userId}\x01{grantId} - \x01 cannot appear in UUIDs (hex + hyphens only)
     return `${OAUTH_CTX_PREFIX}${userId}${OAUTH_CTX_PREFIX}${grantId}`;
 }
-// ── Shared HTTP helpers ────────────────────────────────────────────
+export function decodeOAuthCtx(key) {
+    if (!key.startsWith(OAUTH_CTX_PREFIX))
+        return null;
+    const rest = key.slice(OAUTH_CTX_PREFIX.length);
+    const sepIdx = rest.indexOf(OAUTH_CTX_PREFIX);
+    if (sepIdx <= 0)
+        return null;
+    const grantId = rest.slice(sepIdx + OAUTH_CTX_PREFIX.length);
+    if (!grantId)
+        return null;
+    return { userId: rest.slice(0, sepIdx), grantId };
+}
 function buildHeaders(apiKey) {
     const headers = {
         "X-Source": "mcp-server",
@@ -47,13 +71,34 @@ function buildHeaders(apiKey) {
     }
     return headers;
 }
+export function parseRetryAfterSeconds(headerValue) {
+    if (!headerValue)
+        return null;
+    const raw = headerValue.trim();
+    if (/^\d+$/.test(raw))
+        return Math.max(1, parseInt(raw, 10));
+    if (!/[A-Za-z]/.test(raw))
+        return null;
+    const asDate = Date.parse(raw);
+    if (Number.isNaN(asDate))
+        return null;
+    return Math.max(1, Math.ceil((asDate - Date.now()) / 1000));
+}
+export function formatRetryAfter(seconds) {
+    const unit = (value, name) => `${value} ${name}${value === 1 ? "" : "s"}`;
+    if (seconds < 60)
+        return unit(seconds, "second");
+    if (seconds < 3600)
+        return unit(Math.ceil(seconds / 60), "minute");
+    if (seconds < 86400)
+        return unit(Math.ceil(seconds / 3600), "hour");
+    return unit(Math.ceil(seconds / 86400), "day");
+}
 async function handleErrorResponse(res, apiKey) {
-    // 429 has special Retry-After handling - keep dedicated path
     if (res.status === 429) {
-        const retryAfter = res.headers?.get?.("Retry-After");
-        const days = retryAfter ? Math.ceil(parseInt(retryAfter, 10) / 86400) : null;
-        const resetInfo = days !== null ? ` Resets in ${days} day(s).` : "";
-        throw new Error(`Too many requests.${resetInfo}`);
+        const seconds = parseRetryAfterSeconds(res.headers?.get?.("Retry-After"));
+        const wait = seconds !== null ? ` Retry in ${formatRetryAfter(seconds)}.` : " Retry shortly.";
+        throw new Error(`Too many requests - this is a rate limit, not an exhausted allowance.${wait}`);
     }
     const body = (await res.json().catch(() => ({})));
     const mode = getAuthMode(apiKey ?? process.env.CENOGRAM_API_KEY);
@@ -67,7 +112,6 @@ function toQueryParams(obj) {
     }
     return params;
 }
-// ── HTTP client ─────────────────────────────────────────────────────
 export async function fetchApi(path, params, apiKey) {
     const url = new URL(path, BASE_URL);
     if (params) {
@@ -109,12 +153,11 @@ export async function fetchApiPost(path, body, apiKey) {
         clearTimeout(timeout);
     }
 }
-// ── Typed wrappers ──────────────────────────────────────────────────
 export function getStats(apiKey) {
-    return fetchApi("/api/stats", undefined, apiKey);
+    return fetchApi("/api/v1/stats", undefined, apiKey);
 }
 export function getTransactions(p, apiKey) {
-    return fetchApi("/api/transactions", toQueryParams({
+    return fetchApi("/api/v1/transactions", toQueryParams({
         district: p.district,
         teryt: p.teryt,
         street: p.street,
@@ -123,8 +166,15 @@ export function getTransactions(p, apiKey) {
         propertyType: p.propertyType,
         marketType: p.marketType,
         unitFunction: p.unitFunction,
+        ownershipType: p.ownershipType,
         buildingType: p.buildingType,
         mpzpDesignation: p.mpzpDesignation,
+        transactionType: p.transactionType,
+        rooms: p.rooms,
+        floor: p.floor,
+        floodRisk: p.floodRisk,
+        heritageStatus: p.heritageStatus,
+        landslideRisk: p.landslideRisk,
         minPrice: p.minPrice,
         maxPrice: p.maxPrice,
         dateFrom: p.dateFrom,
@@ -139,15 +189,24 @@ export function getTransactions(p, apiKey) {
     }), apiKey);
 }
 export function getTransactionsSummary(p, apiKey) {
-    return fetchApi("/api/transactions/summary", toQueryParams({
+    return fetchApi("/api/v1/transactions/summary", toQueryParams({
         district: p.district,
         teryt: p.teryt,
         street: p.street,
+        buildingNumber: p.buildingNumber,
+        parcelId: p.parcelId,
         propertyType: p.propertyType,
         marketType: p.marketType,
         unitFunction: p.unitFunction,
+        ownershipType: p.ownershipType,
         buildingType: p.buildingType,
         mpzpDesignation: p.mpzpDesignation,
+        transactionType: p.transactionType,
+        rooms: p.rooms,
+        floor: p.floor,
+        floodRisk: p.floodRisk,
+        heritageStatus: p.heritageStatus,
+        landslideRisk: p.landslideRisk,
         minPrice: p.minPrice,
         maxPrice: p.maxPrice,
         dateFrom: p.dateFrom,
@@ -158,19 +217,67 @@ export function getTransactionsSummary(p, apiKey) {
     }), apiKey);
 }
 export function getPricePerM2(apiKey) {
-    return fetchApi("/api/price-per-m2", undefined, apiKey);
+    return fetchApi("/api/v1/price-per-m2", undefined, apiKey);
 }
 export function getDistricts(apiKey) {
-    return fetchApi("/api/districts", undefined, apiKey);
+    return fetchApi("/api/v1/districts", undefined, apiKey);
+}
+export function getRentalYield(params, apiKey) {
+    return fetchApi("/api/v1/rental-yield", toQueryParams({
+        location: params.location,
+        teryt: params.teryt,
+        areaBucket: params.areaBucket,
+    }), apiKey);
+}
+export function getRentalYieldLocations(params, apiKey) {
+    return fetchApi("/api/v1/rental-yield/locations", toQueryParams({
+        search: params.search,
+    }), apiKey);
+}
+export function getPriceSpread(params, apiKey) {
+    return fetchApi("/api/v1/price-spread", toQueryParams({
+        location: params.location,
+        teryt: params.teryt,
+        marketType: params.marketType,
+        areaBucket: params.areaBucket,
+    }), apiKey);
+}
+export function getPriceSpreadLocations(params, apiKey) {
+    return fetchApi("/api/v1/price-spread/locations", toQueryParams({
+        search: params.search,
+    }), apiKey);
+}
+export function getValuation(params, apiKey) {
+    return fetchApi("/api/v1/valuations", toQueryParams({
+        lat: params.lat,
+        lng: params.lng,
+        parcelId: params.parcelId,
+        area: params.area,
+        rooms: params.rooms,
+        market: params.market,
+        includeComps: params.includeComps ? "true" : undefined,
+    }), apiKey);
 }
 export function getLocations(parent, apiKey) {
-    return fetchApi("/api/locations", parent ? { parent } : undefined, apiKey);
+    return fetchApi("/api/v1/locations", parent ? { parent } : undefined, apiKey);
 }
 export function getPriceHistogram(bins = 20, max = 3_000_000, apiKey) {
-    return fetchApi("/api/stats/price-histogram", toQueryParams({ bins, max }), apiKey);
+    return fetchApi("/api/v1/stats/price-histogram", toQueryParams({ bins, max }), apiKey);
 }
 export function searchParcels(q, limit, apiKey) {
-    return fetchApi("/api/parcels/search", toQueryParams({ q, limit }), apiKey);
+    return fetchApi("/api/v1/parcels/search", toQueryParams({ q, limit }), apiKey);
+}
+export function resolveParcel(params, apiKey) {
+    return fetchApi("/api/v1/parcels/resolve", toQueryParams({
+        q: params.q,
+        parcelId: params.parcelId,
+        lat: params.lat,
+        lng: params.lng,
+    }), apiKey);
+}
+export function getParcelReport(parcelKey, apiKey) {
+    const urlKey = parcelKey.trim().replace(/\//g, "-");
+    return fetchApi(`/api/v1/parcels/${encodeURIComponent(urlKey)}/report`, undefined, apiKey);
 }
 export function searchByPolygon(p, apiKey) {
     const body = { polygon: p.polygon };
@@ -182,6 +289,8 @@ export function searchByPolygon(p, apiKey) {
         body.unitFunction = p.unitFunction;
     if (p.buildingType != null)
         body.buildingType = p.buildingType;
+    if (p.ownershipType != null)
+        body.ownershipType = p.ownershipType;
     if (p.mpzpDesignation)
         body.mpzpDesignation = p.mpzpDesignation;
     if (p.minPrice != null)
@@ -200,18 +309,29 @@ export function searchByPolygon(p, apiKey) {
         body.district = p.district;
     if (p.street)
         body.street = p.street;
+    if (p.transactionType)
+        body.transactionType = p.transactionType;
+    if (p.rooms)
+        body.rooms = p.rooms;
+    if (p.floor)
+        body.floor = p.floor;
     if (p.limit != null)
         body.limit = p.limit;
-    return fetchApiPost("/api/transactions/spatial", body, apiKey);
+    return fetchApiPost("/api/v1/transactions/spatial", body, apiKey);
 }
 export function compareLocations(p, apiKey) {
-    return fetchApi("/api/transactions/summary/compare", toQueryParams({
+    return fetchApi("/api/v1/transactions/summary/compare", toQueryParams({
         districts: p.districts,
+        include: p.include,
         propertyType: p.propertyType,
         marketType: p.marketType,
         unitFunction: p.unitFunction,
+        ownershipType: p.ownershipType,
         buildingType: p.buildingType,
         mpzpDesignation: p.mpzpDesignation,
+        transactionType: p.transactionType,
+        rooms: p.rooms,
+        floor: p.floor,
         minPrice: p.minPrice,
         maxPrice: p.maxPrice,
         dateFrom: p.dateFrom,
@@ -221,3 +341,30 @@ export function compareLocations(p, apiKey) {
         street: p.street,
     }), apiKey);
 }
+export function getBuildingBreakdown(transactionId, apiKey) {
+    return fetchApi(`/api/v1/transactions/${transactionId}/buildings`, undefined, apiKey);
+}
+export function getTransactionFlood(transactionId, apiKey) {
+    return fetchApi(`/api/v1/transactions/${transactionId}/flood`, undefined, apiKey);
+}
+export function getTransactionHeritage(transactionId, apiKey) {
+    return fetchApi(`/api/v1/transactions/${transactionId}/heritage`, undefined, apiKey);
+}
+export function getTransactionLandslide(transactionId, apiKey) {
+    return fetchApi(`/api/v1/transactions/${transactionId}/landslide`, undefined, apiKey);
+}
+export function getTransactionSurroundings(transactionId, apiKey) {
+    return fetchApi(`/api/v1/transactions/${transactionId}/surroundings`, undefined, apiKey);
+}
+export function getTransactionTransit(transactionId, apiKey) {
+    return fetchApi(`/api/v1/transactions/${transactionId}/transit`, undefined, apiKey);
+}
+export function getTransactionPermits(transactionId, apiKey) {
+    return fetchApi(`/api/v1/transactions/${transactionId}/permits`, undefined, apiKey);
+}
+export function getTransactionPlanning(transactionId, apiKey) {
+    return fetchApi(`/api/v1/transactions/${transactionId}/planning`, undefined, apiKey);
+}
+export function getTransactionFarmland(transactionId, apiKey) {
+    return fetchApi(`/api/v1/transactions/${transactionId}/farmland`, undefined, apiKey);
+}

package/dist/auth-dispatch.js

@@ -1,29 +1,13 @@
 import { validateOAuthJwt, OAuthConfigError } from "./oauth-jwt.js";
 import { encodeOAuthCtx } from "./api-client.js";
 export const RESOURCE_METADATA = "https://mcp.cenogram.pl/.well-known/oauth-protected-resource";
-// RFC 6750 § 3 quoted-string alphabet: %x20-21 / %x23-5B / %x5D-7E (ASCII visible without " or \)
 const QUOTED_RE = /^[\x20\x21\x23-\x5B\x5D-\x7E]*$/;
-// RFC 7235 BWS (bad whitespace): SP / HTAB
 const BEARER_RE = /^Bearer[ \t]+(.+)$/i;
-// JWT shape: 3 base64url segments separated by dots, starting with eyJ
 const JWT_SHAPE_RE = /^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
-// Log-unsafe codepoints (log poisoning via multi-byte UTF-8 controls):
-//   \x00-\x1F      ASCII C0 controls
-//   \x7F-\x9F      DEL + C1 controls (incl. U+0085 NEL = bytes 0xc2 0x85)
-//   U+2028, U+2029 Line/Paragraph Separator (NOT escaped by JSON.stringify)
-//   U+202A-U+202E  BiDi controls LRE/RLE/PDF/LRO/RLO (Trojan Source attacks)
-//   U+2066-U+2069  BiDi isolates LRI/RLI/FSI/PDI
-//   U+FEFF         Zero-Width No-Break Space / BOM
-// Goal: prevent log injection / terminal RTL render manipulation when user-controlled
-// bytes (kid in JWT header, suffix of cngrm_ API key) reach stderr JSON logs.
-// eslint-disable-next-line no-control-regex -- control chars in regex are the whole point
 const LOG_UNSAFE_RE = /[\x00-\x1F\x7F-\x9F\u2028\u2029\u202A-\u202E\u2066-\u2069\uFEFF]/g;
 export function sanitizeForLog(s) {
     return s.replace(LOG_UNSAFE_RE, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
 }
-// Static descriptions for WWW-Authenticate header - quoted-safe ASCII, no user input echoed.
-// Note: unknown_key and invalid intentionally share the same description to avoid leaking
-// validation timing/identity info on the wire (security: minimize info oracle).
 const REASON_DESC = {
     expired: "Token expired",
     unknown_key: "Token validation failed",
@@ -64,10 +48,6 @@ function build403(scope, description) {
     };
 }
 export async function dispatchAuth(authHeader, validateJwt = validateOAuthJwt) {
-    // RFC 6750 §3.1: oversized auth attempt → invalid_token (client tried auth, not missing).
-    // 8192 B = below Node default http.maxHeaderSize (16KB), accommodates JWT with claims +
-    // Bearer prefix (~700-1500 bytes for current claim set: sub, scope, grant_id, client_id).
-    // Check before regex match to avoid ReDoS / memory on huge string.
     const MAX_AUTH_HEADER_BYTES = 8192;
     if (authHeader && Buffer.byteLength(authHeader, "utf-8") > MAX_AUTH_HEADER_BYTES) {
         return {
@@ -81,7 +61,6 @@ export async function dispatchAuth(authHeader, validateJwt = validateOAuthJwt) {
             log: { evt: "auth.rejected", reason: "oversized_header", kid: null },
         };
     }
-    // Parse Bearer token (RFC 7235: BWS = SP/HTAB)
     const match = authHeader?.match(BEARER_RE);
     const rawToken = match?.[1]?.trim() ?? "";
     if (!rawToken) {
@@ -94,7 +73,6 @@ export async function dispatchAuth(authHeader, validateJwt = validateOAuthJwt) {
             log: { evt: "auth.rejected", reason: "missing", kid: null },
         };
     }
-    // Fast path: API key (most common). Format validation delegated to upstream API.
     if (rawToken.startsWith("cngrm_")) {
         return {
             kind: "passthrough",
@@ -102,7 +80,6 @@ export async function dispatchAuth(authHeader, validateJwt = validateOAuthJwt) {
             log: { evt: "auth.passthrough", mode: "api_key", key_prefix: sanitizeForLog(rawToken.slice(0, 10)) },
         };
     }
-    // OAuth JWT shape check - reject anything that doesn't look like a JWT before crypto ops
     if (!JWT_SHAPE_RE.test(rawToken)) {
         return {
             kind: "401",
@@ -115,7 +92,6 @@ export async function dispatchAuth(authHeader, validateJwt = validateOAuthJwt) {
             log: { evt: "auth.rejected", reason: "invalid_format", kid: null },
         };
     }
-    // Validate JWT
     let result;
     try {
         result = await validateJwt(rawToken);
@@ -132,14 +108,12 @@ export async function dispatchAuth(authHeader, validateJwt = validateOAuthJwt) {
         throw e;
     }
     if (!result.ok) {
-        // Extract kid from header for logging (best-effort, not on wire)
         let headerKid = null;
         try {
             const headerJson = JSON.parse(Buffer.from(rawToken.split(".")[0], "base64url").toString("utf-8"));
             headerKid = safeKid(headerJson.kid);
         }
         catch {
-            // ignore - kid logging is best-effort
         }
         return {
             kind: "401",
@@ -162,7 +136,6 @@ export async function dispatchAuth(authHeader, validateJwt = validateOAuthJwt) {
     return {
         kind: "passthrough",
         apiKey: encodeOAuthCtx(result.claims.sub, result.claims.grant_id),
-        // Sanitize grant_id for log consistency with key_prefix/kid (defense in depth - JWT is signed but spec allows custom claims).
         log: { evt: "auth.passthrough", mode: "oauth", grant_id: sanitizeForLog(result.claims.grant_id) },
     };
 }

package/dist/client-id.js

@@ -8,12 +8,10 @@ let cachedId = null;
 export function getClientId() {
     if (cachedId)
         return cachedId;
-    // Allow override via env var
     if (process.env.CENOGRAM_CLIENT_ID?.trim()) {
         cachedId = process.env.CENOGRAM_CLIENT_ID.trim();
         return cachedId;
     }
-    // Try reading persisted ID
     try {
         const stored = readFileSync(CLIENT_ID_FILE, "utf-8").trim();
         if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(stored)) {
@@ -22,16 +20,13 @@ export function getClientId() {
         }
     }
     catch {
-        // File doesn't exist or isn't readable - generate new
     }
-    // Generate and persist
     const id = randomUUID();
     try {
         mkdirSync(CONFIG_DIR, { recursive: true });
         writeFileSync(CLIENT_ID_FILE, id + "\n", { mode: 0o600 });
     }
     catch {
-        // Read-only fs (Docker, sandbox) - use ephemeral ID
     }
     cachedId = id;
     return id;

package/dist/error-messages.d.ts

@@ -1,8 +1,12 @@
 export type AuthMode = "oauth" | "api_key" | "stdio_env" | "none";
 export declare function getAuthMode(apiKey?: string): AuthMode;
+export declare function signupUrl(): string;
 export interface ErrorBody {
     error?: string;
+    message?: string;
     currentBalance?: number;
     creditsRequired?: number;
+    upgrade?: string;
+    successor?: string;
 }
 export declare function authErrorMessage(status: number, mode: AuthMode, body?: ErrorBody): string;

package/dist/error-messages.js

@@ -1,4 +1,4 @@
-// SOH char (\x01) - must match OAUTH_CTX_PREFIX in api-client.ts
+import { channelSrc } from "./transport-mode.js";
 const OAUTH_CTX_PREFIX = "\x01";
 export function getAuthMode(apiKey) {
     if (!apiKey)
@@ -9,28 +9,71 @@ export function getAuthMode(apiKey) {
         return "api_key";
     return "stdio_env";
 }
+export function signupUrl() {
+    return `https://cenogram.pl/api?src=${channelSrc()}`;
+}
+function specificMessage(body) {
+    const rawError = typeof body.error === "string" ? body.error.trim() : "";
+    const rawMessage = typeof body.message === "string" ? body.message.trim() : "";
+    const candidate = rawMessage || rawError;
+    return candidate.length > 0 && candidate.length <= 500 ? candidate : "";
+}
+function sentence(text) {
+    return /[.!?]$/.test(text) ? text : `${text}.`;
+}
+function specificField(value) {
+    if (typeof value !== "string")
+        return "";
+    const trimmed = value.trim();
+    return trimmed.length > 0 && trimmed.length <= 500 ? trimmed : "";
+}
 export function authErrorMessage(status, mode, body = {}) {
+    const specific = specificMessage(body);
     switch (status) {
         case 401:
             if (mode === "oauth") {
                 return "Connection to Cenogram expired or was revoked. In Claude open: Settings > Connectors > Cenogram, disconnect and reconnect.";
             }
-            return "API key rejected. Check https://cenogram.pl/api/keys if it's still active.";
+            if (mode === "none") {
+                return (`No Cenogram API key configured. Get a free key at ${signupUrl()}, ` +
+                    "then set it as the CENOGRAM_API_KEY environment variable of this MCP server.");
+            }
+            return "API key rejected. Check https://cenogram.pl/ustawienia#api-keys if it's still active.";
         case 402: {
+            const explanation = specificField(body.message);
+            if (body.error === "trial_expired" && explanation) {
+                const upgrade = specificField(body.upgrade);
+                return upgrade && !explanation.includes(upgrade) ? `${sentence(explanation)} (${upgrade})` : explanation;
+            }
             const balance = body.currentBalance ?? 0;
             const required = body.creditsRequired ?? "?";
             if (mode === "oauth") {
-                return `Insufficient credits (balance: ${balance}, query cost: ${required}). Top up: https://cenogram.pl/api#cennik`;
+                return `Insufficient credits (balance: ${balance}, query cost: ${required}). Top up: https://cenogram.pl/api?src=${channelSrc()}#cennik`;
             }
-            return `Insufficient credits for key's account (balance: ${balance}, query cost: ${required}). Top up: https://cenogram.pl/api#cennik`;
+            return `Insufficient credits for key's account (balance: ${balance}, query cost: ${required}). Top up: https://cenogram.pl/api?src=${channelSrc()}#cennik`;
         }
         case 403:
             if (body.error === "email_not_verified") {
                 return "Account email not verified. Check your inbox, click the activation link, then retry.";
             }
-            return `Access denied (HTTP 403).`;
-        case 503:
-            return "Cenogram temporarily unavailable (maintenance mode). Try again shortly.";
+            return specific ? `Access denied: ${specific}` : "Access denied (HTTP 403).";
+        case 503: {
+            if (!specific)
+                return "Cenogram temporarily unavailable. Try again shortly.";
+            const saysRetry = /try again|retry|spr[oó]buj ponownie/i.test(specific);
+            return `Cenogram temporarily unavailable: ${sentence(specific)}${saysRetry ? "" : " Try again shortly."}`;
+        }
+        case 410: {
+            const successor = specificField(body.successor);
+            const reason = sentence(specific || "This endpoint has been retired.");
+            const where = successor ? ` It was replaced by ${successor}.` : "";
+            return `${reason}${where} This is permanent - retrying will not help. Update @cenogram/mcp-server to the latest version.`;
+        }
+        case 404:
+            return specific || "Not found (HTTP 404). Check the location name or TERYT code.";
+        case 400:
+        case 422:
+            return specific ? `Invalid request: ${specific}` : `Invalid request (HTTP ${status}). Check parameters.`;
         default:
             return `Cenogram API unavailable (HTTP ${status}). Try again shortly.`;
     }

package/dist/formatters.d.ts

@@ -1,4 +1,5 @@
-import type { Transaction, TransactionsResponse, TransactionsSummary, StatsResponse, PricePerM2Row, HistogramBin, ParcelSearchResponse, SpatialSearchResponse, CompareResponse, LocationItem } from "./api-client.js";
+import type { Transaction, TransactionsResponse, TransactionsSummary, StatsResponse, PricePerM2Row, HistogramBin, ParcelSearchResponse, ParcelResolveResponse, SpatialSearchResponse, CompareResponse, LocationItem, RentalYieldResponse, RentalYieldLocationsResponse, PriceSpreadResponse, PriceSpreadLocationsResponse, ValuationResponse, BuildingBreakdownResponse, FloodBreakdownResponse, HeritageBreakdownResponse, LandslideBreakdownResponse, SurroundingsResponse, TransitBreakdownResponse, PermitsResponse, PlanningResponse, FarmlandResponse, DemographicsResponse, InfrastructureSignalsResponse, ParcelReportResponse } from "./api-client.js";
+export declare const MARKET_CAVEAT = "Note: median/average prices are market-based \u2014 fractional ownership shares and non-market deeds (public tenders, foreclosures, privileged/subsidized sales) are excluded from price aggregates. Transaction counts and coverage stay complete.";
 export declare function formatPLN(value: number | null | undefined): string;
 export declare function formatArea(m2: number | null | undefined): string;
 export declare function formatNumber(value: number | null | undefined): string;
@@ -8,6 +9,24 @@ export declare function formatMarketOverview(stats: StatsResponse): string;
 export declare function formatPriceStats(rows: PricePerM2Row[], location?: string): string;
 export declare function formatHistogram(bins: HistogramBin[]): string;
 export declare function formatParcelResults(res: ParcelSearchResponse, query: string): string;
+export declare function formatParcelResolve(res: ParcelResolveResponse): string;
 export declare function formatSpatialResults(res: SpatialSearchResponse): string;
+export declare function formatBuildingBreakdown(res: BuildingBreakdownResponse): string;
+export declare function formatFloodBreakdown(res: FloodBreakdownResponse): string;
+export declare function formatHeritageBreakdown(res: HeritageBreakdownResponse): string;
+export declare function formatLandslideBreakdown(res: LandslideBreakdownResponse): string;
+export declare function formatSurroundings(res: SurroundingsResponse): string;
+export declare function formatTransitBreakdown(res: TransitBreakdownResponse): string;
+export declare function formatPermitsBreakdown(res: PermitsResponse): string;
+export declare function formatPlanningBreakdown(res: PlanningResponse): string;
+export declare function formatFarmland(res: FarmlandResponse): string;
 export declare function formatLocationHierarchy(items: LocationItem[], parent?: string): string;
 export declare function formatCompareResults(res: CompareResponse): string;
+export declare function formatDemographics(r: DemographicsResponse): string;
+export declare function formatInfrastructureSignals(r: InfrastructureSignalsResponse): string;
+export declare function formatRentalYield(r: RentalYieldResponse): string;
+export declare function formatRentalYieldLocations(r: RentalYieldLocationsResponse): string;
+export declare function formatPriceSpread(r: PriceSpreadResponse): string;
+export declare function formatPriceSpreadLocations(r: PriceSpreadLocationsResponse): string;
+export declare function formatValuation(r: ValuationResponse): string;
+export declare function formatParcelReport(res: ParcelReportResponse): string;