htag-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,691 @@
+/**
+ * Client configuration options.
+ */
+interface HtAgClientOptions {
+    /** API key for authentication. Sent as the `x-api-key` header. */
+    apiKey: string;
+    /** Target environment. Determines the base URL unless `baseUrl` is provided. */
+    environment?: 'dev' | 'prod';
+    /** Custom base URL. Overrides the environment-based URL when provided. */
+    baseUrl?: string;
+    /** Maximum number of retry attempts for retryable errors (429, 5xx). Defaults to 3. */
+    maxRetries?: number;
+    /** Base delay in milliseconds for exponential backoff. Defaults to 500. */
+    retryBaseDelay?: number;
+    /** Request timeout in milliseconds. Defaults to 30000 (30 seconds). */
+    timeout?: number;
+}
+/**
+ * Resolved internal configuration used by the HTTP layer.
+ */
+interface ResolvedConfig {
+    apiKey: string;
+    publicBaseUrl: string;
+    internalBaseUrl: string;
+    maxRetries: number;
+    retryBaseDelay: number;
+    timeout: number;
+}
+/**
+ * Generic paginated response wrapper returned by the Markets API.
+ */
+interface BaseResponse<T> {
+    data: T[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Standard request options that can be passed to any SDK method.
+ */
+interface RequestOptions {
+    /** AbortSignal for request cancellation. */
+    signal?: AbortSignal;
+}
+/**
+ * Level enum for market queries.
+ */
+type LevelEnum = 'lga' | 'suburb';
+/**
+ * Property type enum for market queries.
+ */
+type PropertyTypeEnum = 'house' | 'unit' | 'townhouse' | 'other';
+
+/**
+ * Internal HTTP transport used by all domain clients.
+ */
+declare class HttpClient {
+    private readonly config;
+    constructor(config: ResolvedConfig);
+    /**
+     * Execute a GET request against the public API base.
+     */
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Execute a POST request against the public API base.
+     */
+    post<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
+    /**
+     * Execute a GET request against the internal API base.
+     */
+    internalGet<T>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Execute a POST request against the internal API base.
+     */
+    internalPost<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
+    private request;
+}
+
+interface AddressRecord {
+    address_key?: string | null;
+    gnaf_property_pid?: string | null;
+    legal_parcel_id?: string | null;
+    mb_category?: string | null;
+    suburb_loc_pid?: string | null;
+    suburb_slug?: string | null;
+    lat?: number | null;
+    lon?: number | null;
+    flood?: boolean | null;
+    bushfire?: boolean | null;
+    heritage?: boolean | null;
+    zoning?: string | null;
+    IRSD?: number | null;
+    IRSAD?: number | null;
+    IER?: number | null;
+    IEO?: number | null;
+    public_housing?: number | null;
+    private_rentals?: number | null;
+    address_label?: string | null;
+    address_site_name?: string | null;
+    building_name?: string | null;
+    flat_type?: string | null;
+    flat_number?: string | null;
+    level_type?: string | null;
+    level_number?: string | null;
+    number_first?: string | null;
+    number_last?: string | null;
+    lot_number?: string | null;
+    street_name?: string | null;
+    street_type?: string | null;
+    street_suffix?: string | null;
+    locality_name?: string | null;
+    state?: string | null;
+    postcode?: string | null;
+}
+interface AddressSearchResult extends AddressRecord {
+    score: number;
+}
+interface AddressSearchParams extends RequestOptions {
+    /** Free-text address query string. */
+    q: string;
+    /** Minimum matching score threshold (0-1). */
+    threshold?: number;
+    /** Maximum number of results to return. */
+    limit?: number;
+}
+interface AddressSearchResponse {
+    results: AddressSearchResult[];
+}
+interface AddressInsightsParams extends RequestOptions {
+    /** Free-text address to look up. */
+    address?: string;
+    /** One or more GNAF address keys. */
+    addressKeys?: string[];
+    /** Legal parcel identifier. */
+    legalParcelId?: string;
+    /** Street locality PID. */
+    streetLocPid?: string;
+    /** Mesh block category 2021. */
+    mbCategory2021?: string[];
+}
+interface AddressInsightsResponse {
+    results: AddressRecord[];
+}
+interface BatchStandardiseParams extends RequestOptions {
+    /** Array of raw address strings to standardise. */
+    addresses: string[];
+}
+interface StandardisedAddress {
+    input: string;
+    matched: boolean;
+    result?: AddressRecord | null;
+}
+interface BatchStandardiseResponse {
+    results: StandardisedAddress[];
+}
+
+/**
+ * Client for the Address API domain.
+ *
+ * ```ts
+ * const results = await client.address.search({ q: '100 George St Sydney' });
+ * ```
+ */
+declare class AddressClient {
+    private readonly http;
+    /** @internal */
+    constructor(http: HttpClient);
+    /**
+     * Search for addresses matching a free-text query.
+     *
+     * `GET /v1/address/search`
+     */
+    search(params: AddressSearchParams): Promise<AddressSearchResponse>;
+    /**
+     * Retrieve detailed insights for one or more addresses.
+     *
+     * `GET /v1/address/insights`
+     */
+    insights(params: AddressInsightsParams): Promise<AddressInsightsResponse>;
+    /**
+     * Standardise a batch of raw address strings into structured records.
+     *
+     * `POST /v1/address/standardise`
+     */
+    standardise(params: BatchStandardiseParams): Promise<BatchStandardiseResponse>;
+}
+
+interface SoldPropertyRecord {
+    address_key?: string | null;
+    property_type?: string | null;
+    street_address?: string | null;
+    suburb?: string | null;
+    state?: string | null;
+    postcode?: string | null;
+    lat?: number | null;
+    lon?: number | null;
+    sold_date?: string | null;
+    sold_price?: number | null;
+    bedrooms?: number | null;
+    bathrooms?: number | null;
+    car_spaces?: number | null;
+    land_area?: number | null;
+}
+interface SoldSearchParams extends RequestOptions {
+    /** Free-text address for the search centre. */
+    address?: string;
+    /** GNAF address key. */
+    addressKey?: string;
+    /** Latitude for geographic search. */
+    lat?: number;
+    /** Longitude for geographic search. */
+    lon?: number;
+    /** Search radius in metres. */
+    radius?: number;
+    /** Proximity label (e.g. "nearby"). */
+    proximity?: string;
+    /** Filter by property type. */
+    propertyType?: string;
+    /** Minimum sale price filter. */
+    saleValueMin?: number;
+    /** Maximum sale price filter. */
+    saleValueMax?: number;
+    /** Include sales with unknown value. */
+    includeSaleValueUnknown?: boolean;
+    /** Minimum bedrooms filter. */
+    bedroomsMin?: number;
+    /** Maximum bedrooms filter. */
+    bedroomsMax?: number;
+    /** Minimum bathrooms filter. */
+    bathroomsMin?: number;
+    /** Maximum bathrooms filter. */
+    bathroomsMax?: number;
+    /** Minimum car spaces filter. */
+    carSpacesMin?: number;
+    /** Maximum car spaces filter. */
+    carSpacesMax?: number;
+    /** Earliest sale date (YYYY-MM-DD). */
+    startDate?: string;
+    /** Latest sale date (YYYY-MM-DD). */
+    endDate?: string;
+    /** Minimum land area in sqm. */
+    landAreaMin?: number;
+    /** Maximum land area in sqm. */
+    landAreaMax?: number;
+}
+interface SoldPropertiesResponse {
+    results: SoldPropertyRecord[];
+}
+
+/**
+ * Client for the Property API domain.
+ *
+ * ```ts
+ * const sold = await client.property.soldSearch({ address: '100 George St Sydney', radius: 2000 });
+ * ```
+ */
+declare class PropertyClient {
+    private readonly http;
+    /** @internal */
+    constructor(http: HttpClient);
+    /**
+     * Search for recently sold properties near a location.
+     *
+     * `GET /v1/property/sold/search`
+     */
+    soldSearch(params: SoldSearchParams): Promise<SoldPropertiesResponse>;
+}
+
+interface MarketSnapshot {
+    area_id?: string | null;
+    composite_key?: string | null;
+    state_name?: string | null;
+    region_reference?: string | null;
+    suburb?: string | null;
+    postcode?: string | null;
+    council_area_reference?: string | null;
+    council_area?: string | null;
+    period_end?: string | null;
+    property_type?: string | null;
+    bedrooms?: string | null;
+    typical_price?: number | null;
+    sales?: number | null;
+    annual_sales_volume?: number | null;
+    sales_ratio?: number | null;
+    clearance_rate?: number | null;
+    dom?: number | null;
+    discounting?: number | null;
+    years_to_own?: number | null;
+    som_percent?: number | null;
+    inventory?: number | null;
+    hold_period?: number | null;
+    rent?: number | null;
+    rentals?: number | null;
+    annual_rental_volume?: number | null;
+    rentals_ratio?: number | null;
+    vacancy_rate?: number | null;
+    yield_value?: number | null;
+    one_y_price_growth?: number | null;
+    three_y_price_growth?: number | null;
+    five_y_price_growth?: number | null;
+    ten_y_price_growth?: number | null;
+    one_m_rent_growth?: number | null;
+    one_q_rent_growth?: number | null;
+    six_m_rent_growth?: number | null;
+    one_y_rent_growth?: number | null;
+    three_y_rent_growth?: number | null;
+    five_y_rent_growth?: number | null;
+    ten_y_rent_growth?: number | null;
+    yield_1y_growth?: number | null;
+    yield_3y_growth?: number | null;
+    yield_5y_growth?: number | null;
+    yield_10y_growth?: number | null;
+    projected_annual_capital_growth_low?: number | null;
+    projected_annual_capital_growth_high?: number | null;
+    projected_annual_rent_increase?: number | null;
+    projected_annual_roi_low?: number | null;
+    projected_annual_roi_high?: number | null;
+    estimated_dwellings?: number | null;
+    adult_population?: number | null;
+    irsad?: number | null;
+    building_approvals_estimated?: number | null;
+    ba_ratio?: number | null;
+    school_rank?: number | null;
+    non_res_ba_per_capita_value?: number | null;
+    confidence?: string | null;
+    volatility_index?: number | null;
+    growth_rate_cycle?: number | null;
+    ro_ratio?: number | null;
+    uh_ratio?: number | null;
+    uhv_ratio?: number | null;
+    buy_si?: number | null;
+    rent_si?: number | null;
+    rcs_lower_risk?: number | null;
+    rcs_cashflow?: number | null;
+    rcs_capital_growth?: number | null;
+    rcs_overall?: number | null;
+    hapi_score?: number | null;
+    gpo_dist?: number | null;
+    ediv_ind?: number | null;
+    hrp_flood?: number | null;
+    hrp_fire?: number | null;
+    madi?: number | null;
+    gpd_3?: number | null;
+    gpd_5?: number | null;
+    gpd_10?: number | null;
+    gsp_3?: number | null;
+    gsp_5?: number | null;
+    gsp_10?: number | null;
+    min_grc?: number | null;
+    grc_price_index?: number | null;
+    lt_som_perc?: number | null;
+    lt_inventory?: number | null;
+    lt_dom?: number | null;
+    lt_vacancy_rate?: number | null;
+    lt_clearance_rate?: number | null;
+    lt_hold_period?: number | null;
+    lt_buy_si?: number | null;
+    lt_rent_si?: number | null;
+    st_som_perc?: number | null;
+    st_inventory?: number | null;
+    st_dom?: number | null;
+    st_vacancy_rate?: number | null;
+    st_clearance_rate?: number | null;
+    st_hold_period?: number | null;
+    st_buy_si?: number | null;
+    st_rent_si?: number | null;
+    area_link?: string | null;
+}
+interface PriceHistoryOut {
+    area_id: string;
+    period_end: string;
+    property_type: string;
+    typical_price: number | null;
+    sales: number | null;
+    typical_price_conf_low: number | null;
+    typical_price_conf_high: number | null;
+}
+interface RentHistoryOut {
+    area_id: string;
+    period_end: string;
+    property_type: string;
+    median_rent: number | null;
+    rentals: number | null;
+    median_rent_conf_low: number | null;
+    median_rent_conf_high: number | null;
+}
+interface YieldHistoryOut {
+    area_id: string;
+    period_end: string;
+    property_type: string;
+    yield: number | null;
+}
+interface FSDMonthlyOut {
+    area_id: string;
+    period_end: string;
+    property_type: string;
+    inventory: number | null;
+    vacancies: number | null;
+    clearance_rate: number | null;
+}
+interface FSDQuarterlyOut {
+    area_id: string;
+    period_end: string;
+    property_type: string;
+    buy_si: number | null;
+    rent_si: number | null;
+}
+interface FSDYearlyOut {
+    area_id: string;
+    period_end: string;
+    property_type: string;
+    hold_period: number | null;
+}
+interface EssentialsOut {
+    area_id: string;
+    period_end: string;
+    property_type: string;
+    typical_price: number | null;
+    rent: number | null;
+    sales: number | null;
+    rentals: number | null;
+    yield?: number | null;
+}
+interface GRCOut {
+    area_id: string;
+    period_end: string;
+    property_type: string;
+    price_chg: number | null;
+    rent_chg: number | null;
+    yield_chg: number | null;
+}
+interface DemandProfileOut {
+    area_id: string;
+    period_end: string;
+    dwelling_type: string;
+    bedrooms: string;
+    sales: number | null;
+}
+interface LogicNode {
+    field?: string | null;
+    eq?: string | number | boolean | null;
+    ne?: string | number | boolean | null;
+    gt?: number | null;
+    gte?: number | null;
+    lt?: number | null;
+    lte?: number | null;
+    in?: (string | number)[] | null;
+    nin?: (string | number)[] | null;
+    and?: LogicNode[] | null;
+    or?: LogicNode[] | null;
+    not?: LogicNode | null;
+}
+interface AdvancedSearchBody {
+    level: LevelEnum;
+    mode: string;
+    property_types: PropertyTypeEnum[];
+    area_ids?: string[] | null;
+    typical_price_min?: number | null;
+    typical_price_max?: number | null;
+    logic?: LogicNode | null;
+    limit?: number;
+    offset?: number;
+}
+interface SnapshotsParams extends RequestOptions {
+    level: LevelEnum;
+    propertyType: PropertyTypeEnum[];
+    areaId?: string[];
+    typicalPriceMin?: number;
+    typicalPriceMax?: number;
+    confidence?: string;
+    bedrooms?: string | string[];
+    limit?: number;
+    offset?: number;
+}
+interface MarketQueryParams extends RequestOptions {
+    body: AdvancedSearchBody;
+}
+interface TrendsParams extends RequestOptions {
+    level: LevelEnum;
+    areaId: string[];
+    propertyType?: PropertyTypeEnum[];
+    periodEndMin?: string;
+    periodEndMax?: string;
+    bedrooms?: string | string[];
+    limit?: number;
+    offset?: number;
+}
+
+type SnapshotsResponse = BaseResponse<MarketSnapshot>;
+type MarketQueryResponse = BaseResponse<MarketSnapshot>;
+type PriceResponse = BaseResponse<PriceHistoryOut>;
+type RentResponse = BaseResponse<RentHistoryOut>;
+type YieldResponse = BaseResponse<YieldHistoryOut>;
+type SupplyDemandResponse = BaseResponse<FSDMonthlyOut>;
+type SearchIndexResponse = BaseResponse<FSDQuarterlyOut>;
+type HoldPeriodResponse = BaseResponse<FSDYearlyOut>;
+type PerformanceResponse = BaseResponse<EssentialsOut>;
+type GrowthRatesResponse = BaseResponse<GRCOut>;
+type DemandProfileResponse = BaseResponse<DemandProfileOut>;
+
+/**
+ * Client for the Markets Trends API domain.
+ *
+ * Each method queries a specific time-series metric:
+ *
+ * ```ts
+ * const prices = await client.markets.trends.price({
+ *   level: 'suburb',
+ *   areaId: ['SAL10001'],
+ *   propertyType: ['house'],
+ * });
+ * ```
+ */
+declare class TrendsClient {
+    private readonly http;
+    /** @internal */
+    constructor(http: HttpClient);
+    /**
+     * Price history trends.
+     *
+     * `GET /internal-api/v1/markets/trends/price`
+     */
+    price(params: TrendsParams): Promise<PriceResponse>;
+    /**
+     * Rent history trends.
+     *
+     * `GET /internal-api/v1/markets/trends/rent`
+     */
+    rent(params: TrendsParams): Promise<RentResponse>;
+    /**
+     * Yield history trends.
+     *
+     * `GET /internal-api/v1/markets/trends/yield`
+     */
+    yieldHistory(params: TrendsParams): Promise<YieldResponse>;
+    /**
+     * Supply and demand (monthly frequency).
+     *
+     * `GET /internal-api/v1/markets/trends/supply-demand`
+     */
+    supplyDemand(params: TrendsParams): Promise<SupplyDemandResponse>;
+    /**
+     * Search interest index (quarterly frequency).
+     *
+     * `GET /internal-api/v1/markets/trends/search-index`
+     */
+    searchIndex(params: TrendsParams): Promise<SearchIndexResponse>;
+    /**
+     * Hold period (yearly frequency).
+     *
+     * `GET /internal-api/v1/markets/trends/hold-period`
+     */
+    holdPeriod(params: TrendsParams): Promise<HoldPeriodResponse>;
+    /**
+     * Performance essentials.
+     *
+     * `GET /internal-api/v1/markets/trends/performance`
+     */
+    performance(params: TrendsParams): Promise<PerformanceResponse>;
+    /**
+     * Growth rate cycle.
+     *
+     * `GET /internal-api/v1/markets/trends/growth-rates`
+     */
+    growthRates(params: TrendsParams): Promise<GrowthRatesResponse>;
+    /**
+     * Demand profile breakdown.
+     *
+     * `GET /internal-api/v1/markets/trends/demand-profile`
+     */
+    demandProfile(params: TrendsParams): Promise<DemandProfileResponse>;
+    private trend;
+}
+
+/**
+ * Client for the Markets API domain.
+ *
+ * ```ts
+ * const snapshots = await client.markets.snapshots({
+ *   level: 'suburb',
+ *   propertyType: ['house'],
+ * });
+ *
+ * const prices = await client.markets.trends.price({
+ *   level: 'suburb',
+ *   areaId: ['SAL10001'],
+ * });
+ * ```
+ */
+declare class MarketsClient {
+    private readonly http;
+    /** Sub-client for time-series trend endpoints. */
+    readonly trends: TrendsClient;
+    /** @internal */
+    constructor(http: HttpClient);
+    /**
+     * Retrieve market snapshot data with optional filters.
+     *
+     * `GET /internal-api/v1/markets/snapshots`
+     */
+    snapshots(params: SnapshotsParams): Promise<SnapshotsResponse>;
+    /**
+     * Advanced market query with logical filter expressions.
+     *
+     * `POST /internal-api/v1/markets/query`
+     */
+    query(body: AdvancedSearchBody, options?: RequestOptions): Promise<MarketQueryResponse>;
+}
+
+/**
+ * Top-level client for the HtAG Location Intelligence APIs.
+ *
+ * ```ts
+ * import { HtAgApiClient } from '@htag/sdk';
+ *
+ * const client = new HtAgApiClient({
+ *   apiKey: process.env.HTAG_API_KEY!,
+ *   environment: 'prod',
+ * });
+ *
+ * const results = await client.address.search({ q: '100 George St Sydney' });
+ * ```
+ */
+declare class HtAgApiClient {
+    /** Address search, insights and standardisation. */
+    readonly address: AddressClient;
+    /** Sold property search. */
+    readonly property: PropertyClient;
+    /** Market snapshots, advanced queries and time-series trends. */
+    readonly markets: MarketsClient;
+    constructor(options: HtAgClientOptions);
+}
+
+/**
+ * Base error class for all HtAG SDK errors.
+ */
+declare class HtAgError extends Error {
+    /** HTTP status code, if available. */
+    readonly status: number | undefined;
+    /** Raw response body, if available. */
+    readonly body: unknown;
+    /** The request URL that caused the error. */
+    readonly url: string | undefined;
+    constructor(message: string, options?: {
+        status?: number;
+        body?: unknown;
+        url?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when the server returns 401 or 403.
+ */
+declare class AuthenticationError extends HtAgError {
+    constructor(options: {
+        status: number;
+        body: unknown;
+        url: string;
+    });
+}
+/**
+ * Thrown when the server returns 429 after exhausting all retries.
+ */
+declare class RateLimitError extends HtAgError {
+    constructor(options: {
+        body: unknown;
+        url: string;
+    });
+}
+/**
+ * Thrown when the server returns 400 or 422.
+ */
+declare class ValidationError extends HtAgError {
+    constructor(options: {
+        status: number;
+        body: unknown;
+        url: string;
+    });
+}
+/**
+ * Thrown when the server returns a 5xx status after exhausting all retries.
+ */
+declare class ServerError extends HtAgError {
+    constructor(options: {
+        status: number;
+        body: unknown;
+        url: string;
+    });
+}
+
+export { AddressClient, type AddressInsightsParams, type AddressInsightsResponse, type AddressRecord, type AddressSearchParams, type AddressSearchResponse, type AddressSearchResult, type AdvancedSearchBody, AuthenticationError, type BaseResponse, type BatchStandardiseParams, type BatchStandardiseResponse, type DemandProfileOut, type DemandProfileResponse, type EssentialsOut, type FSDMonthlyOut, type FSDQuarterlyOut, type FSDYearlyOut, type GRCOut, type GrowthRatesResponse, type HoldPeriodResponse, HtAgApiClient, type HtAgClientOptions, HtAgError, type LevelEnum, type LogicNode, type MarketQueryParams, type MarketQueryResponse, type MarketSnapshot, MarketsClient, type PerformanceResponse, type PriceHistoryOut, type PriceResponse, PropertyClient, type PropertyTypeEnum, RateLimitError, type RentHistoryOut, type RentResponse, type RequestOptions, type ResolvedConfig, type SearchIndexResponse, ServerError, type SnapshotsParams, type SnapshotsResponse, type SoldPropertiesResponse, type SoldPropertyRecord, type SoldSearchParams, type StandardisedAddress, type SupplyDemandResponse, TrendsClient, type TrendsParams, ValidationError, type YieldHistoryOut, type YieldResponse };