@sjunepark/landprice 0.0.1 → 0.0.3

package/dist/sources/realtyprice/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const sourcePageSize = 20;
+export declare const realtypriceTmBesselProj4 = "+proj=tmerc +lat_0=38 +lon_0=127.0028902777778 +k=1 +x_0=200000 +y_0=500000 +ellps=bessel +units=m +no_defs +towgs84=-115.80,474.99,674.11,1.16,-2.31,-1.63,6.43";

package/dist/sources/realtyprice/endpoints.d.ts

@@ -0,0 +1,14 @@
+export declare const realtypriceBaseUrl = "https://www.realtyprice.kr";
+export declare const standardLandSourcePage: "https://www.realtyprice.kr/notice/gsstandard/search.htm";
+export declare const individualLandSourcePage: "https://www.realtyprice.kr/notice/gsindividual/search.htm";
+export declare const endpoints: {
+    readonly searchPage: "/notice/gsstandard/search.htm";
+    readonly individualSearchPage: "/notice/gsindividual/search.htm";
+    readonly currentArea: "/notice/bjd/searchBjd.bjd";
+    readonly noticeDateArea: "/notice/bjd/searchBjdYear.bjd";
+    readonly individualCurrentArea: "/notice/bjd/searchBjdApi.bjd";
+    readonly individualSearchList: "/notice/search/gsiSearchListApi.search";
+    readonly searchList: "/notice/search/gssSearchList.search";
+    readonly detail: "/notice/iw/iwSearchPriceinfoGs.iw";
+};
+export declare const buildRealtypriceUrl: (endpoint: string, params?: Record<string, string | number | undefined>) => string;

package/dist/sources/realtyprice/fetch.d.ts

@@ -0,0 +1,2 @@
+export declare const fetchRealtypriceText: (sourceUrl: string, signal?: AbortSignal) => Promise<string>;
+export declare const fetchRealtypriceJson: (sourceUrl: string, signal?: AbortSignal) => Promise<unknown>;

package/dist/sources/realtyprice/metadata.d.ts

@@ -0,0 +1,2 @@
+import type { Completeness, RealtypriceSourcePage, ResultMetadata } from "../../capabilities/types.ts";
+export declare const realtypriceMetadata: (endpoint: string, completeness: Completeness, sourceBehavior: string, query?: Record<string, unknown>, sourcePage?: RealtypriceSourcePage) => ResultMetadata;

package/dist/sources/realtyprice/provider.d.ts

@@ -0,0 +1,6 @@
+import type { GetAvailableYearsProvider } from "../../capabilities/get-available-years/provider.ts";
+import type { ListAreasProvider } from "../../capabilities/list-areas/provider.ts";
+import type { SearchStandardLandPricesProvider } from "../../capabilities/search-standard-land-prices/provider.ts";
+import type { SearchIndividualLandPricesProvider } from "../../capabilities/search-individual-land-prices/provider.ts";
+import type { GetStandardLandPriceDetailProvider } from "../../capabilities/get-standard-land-price-detail/provider.ts";
+export declare const realtypriceProvider: GetAvailableYearsProvider & ListAreasProvider & SearchStandardLandPricesProvider & SearchIndividualLandPricesProvider & GetStandardLandPriceDetailProvider;

package/dist/sources/realtyprice/source-helpers.d.ts

@@ -0,0 +1,19 @@
+import { LandpriceFailure } from "../../capabilities/types.ts";
+export type SearchPageYearValues = {
+    readonly startyear: string;
+    readonly endyear: string;
+    readonly yearstartyear: string;
+    readonly yearendyear: string;
+};
+export declare const asRecord: (value: unknown, sourceUrl: string, label: string) => Record<string, unknown>;
+export declare const asOptionalArray: (value: unknown, sourceUrl: string, label: string) => readonly unknown[];
+export declare const parseSearchPageYearValues: (html: string, sourceUrl: string) => SearchPageYearValues;
+export declare const sourceChanged: (sourceUrl: string, message: string) => LandpriceFailure;
+export declare const optionalString: (value: unknown) => string | undefined;
+export declare const nullableDisplay: (value: unknown) => string | null;
+export declare const parseFormattedNumber: (value: unknown) => number | undefined;
+export declare const compactText: (...parts: readonly unknown[]) => string | undefined;
+export declare const optionalNumber: (value: unknown) => number | undefined;
+export declare const pickModelList: (payload: unknown, sourceUrl: string) => readonly unknown[];
+export declare const pickPaginatedModel: (payload: unknown, sourceUrl: string) => Record<string, unknown>;
+export declare const pickModel: (payload: unknown, sourceUrl: string) => Record<string, unknown>;

package/dist/toolset.d.ts

@@ -0,0 +1,216 @@
+export type ToolRunContext = {
+    readonly signal?: AbortSignal;
+};
+export type OperationSummary = {
+    readonly name: string;
+    readonly label: string;
+    readonly description: string;
+};
+export type OperationSpec = OperationSummary & {
+    readonly inputJsonSchema: unknown;
+    readonly resultJsonSchema: unknown;
+    readonly requiredInputKeys: readonly string[];
+    readonly examples: readonly Record<string, unknown>[];
+    readonly limitations: readonly string[];
+    readonly resultSummary: string;
+};
+export type ToolsetHelp = {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly usage: string;
+    readonly operations: readonly OperationSummary[];
+    readonly limitations: readonly string[];
+    readonly actionProtocol: {
+        readonly actions: readonly SingleToolActionInput["action"][];
+        readonly guidance: readonly string[];
+    };
+};
+export type ValidationFailure = {
+    readonly code: "missing_parameter" | "invalid_parameter" | "unknown_parameter" | "invalid_request";
+    readonly message: string;
+    readonly operationName?: string;
+    readonly parameter?: string;
+    readonly reason?: string;
+    readonly expected?: string;
+    readonly actual?: unknown;
+    readonly recoveryHint?: string;
+    readonly exampleInput?: Record<string, unknown>;
+    readonly retryable: boolean;
+    readonly recoveryAction?: {
+        readonly kind: "inspect_tool_help";
+    } | {
+        readonly kind: "inspect_command_help";
+        readonly operationName: string;
+    };
+};
+export type ValidationResult = {
+    readonly ok: true;
+    readonly input: Record<string, unknown>;
+} | {
+    readonly ok: false;
+    readonly error: ValidationFailure;
+};
+export type SerializedError = {
+    readonly name: string;
+    readonly message: string;
+    readonly code?: string;
+    readonly retryable?: boolean;
+    readonly parameter?: string;
+    readonly sourceUrl?: string;
+    readonly recoveryHint?: string;
+    readonly operationName?: string;
+};
+export type LandpriceToolset = {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly help: () => ToolsetHelp;
+    readonly listOperations: () => readonly OperationSummary[];
+    readonly getOperation: (name: string) => OperationSpec | undefined;
+    readonly getCommandHelp: (name: string) => OperationSpec | undefined;
+    readonly validateInput: (name: string, input: unknown) => ValidationResult;
+    readonly execute: (name: string, input: Record<string, unknown>, context?: ToolRunContext) => Promise<unknown>;
+    readonly serializeError: (error: unknown) => SerializedError;
+};
+export type SingleToolActionInput = {
+    readonly action: "help" | "command_help" | "validate" | "run";
+    readonly command?: string;
+    readonly inputJson?: Record<string, unknown>;
+};
+export type TextContent = {
+    readonly type: "text";
+    readonly text: string;
+};
+export type SingleToolActionResult = {
+    readonly ok: true;
+    readonly action: "help";
+    readonly help: ToolsetHelp;
+} | {
+    readonly ok: true;
+    readonly action: "command_help";
+    readonly command: string;
+    readonly commandHelp: OperationSpec;
+} | {
+    readonly ok: true;
+    readonly action: "validate";
+    readonly command: string;
+    readonly validation: Extract<ValidationResult, {
+        ok: true;
+    }>;
+} | {
+    readonly ok: true;
+    readonly action: "run";
+    readonly command: string;
+    readonly normalizedInput: Record<string, unknown>;
+    readonly result: unknown;
+} | {
+    readonly ok: false;
+    readonly action: "help" | "command_help" | "validate" | "run" | "adapter_validation";
+    readonly command?: string;
+    readonly error: ValidationFailure | SerializedError;
+};
+export type HostToolResult = {
+    readonly content: readonly TextContent[];
+    readonly details: SingleToolActionResult;
+};
+declare const operationNames: readonly ["get-available-years", "list-areas", "search-standard-land-prices", "search-individual-land-prices", "get-standard-land-price-detail"];
+export type LandpriceOperationName = typeof operationNames[number];
+export declare class ToolsetValidationError extends Error {
+    readonly failure: ValidationFailure;
+    constructor(failure: ValidationFailure);
+}
+export declare const landpriceOperationSpecs: readonly [{
+    readonly name: "get-available-years";
+    readonly label: "Get available years";
+    readonly description: "Discover RealtyPrice-supported standard-land search and notice-date year ranges.";
+    readonly inputJsonSchema: import("effect/JSONSchema").JsonSchema7Root;
+    readonly resultJsonSchema: import("effect/JSONSchema").JsonSchema7Root;
+    readonly requiredInputKeys: readonly [];
+    readonly examples: readonly [{
+        readonly responseDetail: "concise";
+    }];
+    readonly limitations: readonly ["Observed from the standard-land search page, so availability can drift when RealtyPrice changes the page."];
+    readonly resultSummary: "Returns supported year ranges and source observation metadata.";
+}, {
+    readonly name: "list-areas";
+    readonly label: "List areas";
+    readonly description: "Discover RealtyPrice area codes for a selected year, land-price surface, and area hierarchy level.";
+    readonly inputJsonSchema: import("effect/JSONSchema").JsonSchema7Root;
+    readonly resultJsonSchema: import("effect/JSONSchema").JsonSchema7Root;
+    readonly requiredInputKeys: readonly ["year", "level"];
+    readonly examples: readonly [{
+        readonly year: 2025;
+        readonly surface: "individual-land";
+        readonly level: "district";
+        readonly sidoCode: "43";
+    }, {
+        readonly year: 2025;
+        readonly surface: "individual-land";
+        readonly level: "legal-dong";
+        readonly sidoCode: "43";
+        readonly districtCode: "43770";
+    }];
+    readonly limitations: readonly ["Individual-land area discovery supports current-address mode only.", "Area code menus are source-specific and should be rechecked when moving between surfaces or years."];
+    readonly resultSummary: "Returns area code rows with source fields, parent context, metadata, and endpoint references.";
+}, {
+    readonly name: "search-standard-land-prices";
+    readonly label: "Search standard land prices";
+    readonly description: "Search standard-land official price records by source year and legal-dong code.";
+    readonly inputJsonSchema: import("effect/JSONSchema").JsonSchema7Root;
+    readonly resultJsonSchema: import("effect/JSONSchema").JsonSchema7Root;
+    readonly requiredInputKeys: readonly ["year", "districtCode", "legalDongCode"];
+    readonly examples: readonly [{
+        readonly year: 2026;
+        readonly districtCode: "11680";
+        readonly legalDongCode: "10300";
+        readonly regionName: "서울특별시 강남구 개포동";
+    }];
+    readonly limitations: readonly ["Search results are paginated with a source-observed page size of 20.", "Detail lookup is only available for records whose result says detailAvailable is true."];
+    readonly resultSummary: "Returns paginated standard-land records, source references, metadata, and warnings.";
+}, {
+    readonly name: "search-individual-land-prices";
+    readonly label: "Search individual land prices";
+    readonly description: "Search individual-land official price records for one parcel and one or more base years.";
+    readonly inputJsonSchema: import("effect/JSONSchema").JsonSchema7Root;
+    readonly resultJsonSchema: import("effect/JSONSchema").JsonSchema7Root;
+    readonly requiredInputKeys: readonly ["districtCode", "legalDongCode", "year|years", "parcel|bun1"];
+    readonly examples: readonly [{
+        readonly year: 2025;
+        readonly districtCode: "43770";
+        readonly legalDongCode: "25624";
+        readonly parcel: "603-1";
+    }, {
+        readonly years: readonly [2026, 2025, 2024];
+        readonly districtCode: "43770";
+        readonly legalDongCode: "25624";
+        readonly parcel: "603-1";
+    }];
+    readonly limitations: readonly ["Multi-year lookup is capped at five years and issues one source request per year.", "Use list-areas with surface=individual-land before searching if district or legal-dong codes are unknown."];
+    readonly resultSummary: "Returns individual-land parcel records, normalized lot references, metadata, references, and warnings.";
+}, {
+    readonly name: "get-standard-land-price-detail";
+    readonly label: "Get standard land price detail";
+    readonly description: "Fetch evaluation-basis/detail data for one standard-land record reference from a prior search result.";
+    readonly inputJsonSchema: import("effect/JSONSchema").JsonSchema7Root;
+    readonly resultJsonSchema: import("effect/JSONSchema").JsonSchema7Root;
+    readonly requiredInputKeys: readonly ["standardLandReference"];
+    readonly examples: readonly [{
+        readonly standardLandReference: {
+            readonly year: 2026;
+            readonly regCode: "11680";
+            readonly eubCode: "10300";
+            readonly sourceSanFlag: "1";
+            readonly bun1: "0086";
+            readonly bun2: "0000";
+            readonly standardLandNumber: "276";
+        };
+    }];
+    readonly limitations: readonly ["Requires a standardLandReference copied from a search-standard-land-prices result.", "RealtyPrice detail rows may omit appraisal fields; missing source values are preserved as null or absent fields."];
+    readonly resultSummary: "Returns one standard-land detail envelope with appraisal fields, source metadata, references, and warnings.";
+}];
+export declare const landpriceOperationSummaries: readonly OperationSummary[];
+export declare const createLandpriceToolset: () => LandpriceToolset;
+export declare const executeLandpriceAction: (toolset: LandpriceToolset, input: SingleToolActionInput, context?: ToolRunContext) => Promise<HostToolResult>;
+export declare const formatLandpriceActionResult: (details: SingleToolActionResult) => string;
+export {};