htag-sdk 0.9.1 → 1.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 The official TypeScript SDK for the [HtAG](https://htagai.com) Location Intelligence API.
 
-Provides typed access to Australian address data, property sales records, and market analytics. Zero runtime dependencies — uses native `fetch`.
+Provides typed access to Australian address data, property valuations, sales records, and market analytics. Zero runtime dependencies -- uses native `fetch`.
 
 ```typescript
 import { HtAgApiClient } from 'htag-sdk';
@@ -12,9 +12,9 @@ const client = new HtAgApiClient({
   environment: 'prod',
 });
 
-const results = await client.address.search({ q: '100 George St Sydney' });
+const results = await client.address.geocode({ address: '100 George St Sydney' });
 for (const r of results.results) {
-  console.log(`${r.address_label}  (score ${r.score.toFixed(2)})`);
+  console.log(`${r.address_label}  (${r.address_key})`);
 }
 ```
 
@@ -62,72 +62,39 @@ const client = new HtAgApiClient({
 ### 3. Make Requests
 
 ```typescript
-// Search for addresses
-const results = await client.address.search({ q: '15 Miranda Court Noble Park' });
+// Geocode an address
+const results = await client.address.geocode({ address: '15 Miranda Court Noble Park' });
 console.log(`${results.total} matches`);
 
-// Get insights for an address
-const insights = await client.address.insights({
-  address: '15 Miranda Court, Noble Park VIC 3174',
+// Get property estimates
+const est = await client.property.estimates({
+  addressKey: '15MIRANDACOURTNOBLEPARKvic3174',
 });
-for (const record of insights.results) {
-  console.log(`Bushfire: ${record.bushfire}, Flood: ${record.flood}`);
+for (const record of est.results) {
+  console.log(`Price estimate: $${record.price_estimate?.toLocaleString()}`);
+  console.log(`Last sold: $${record.last_sold_price?.toLocaleString()} on ${record.last_sold_date}`);
 }
 ```
 
 ## Usage
 
-### Address Search
+### Address Geocode
 
-Find addresses by free-text query with fuzzy matching.
+Resolve a free-text address to structured location data with geographic identifiers.
 
 ```typescript
-const results = await client.address.search({
-  q: '100 Hickox St Traralgon',
-  threshold: 0.3,   // minimum match score (0.1 - 1.0)
+const results = await client.address.geocode({
+  address: '100 Hickox St Traralgon',
   limit: 5,         // max results (1 - 50)
 });
 
 for (const match of results.results) {
   console.log(match.address_label);
   console.log(`  Key: ${match.address_key}`);
-  console.log(`  Score: ${match.score.toFixed(2)}`);
   console.log(`  Location: ${match.lat}, ${match.lon}`);
 }
 ```
 
-### Address Insights
-
-Retrieve enriched data for addresses including risk flags, SEIFA scores, and zoning.
-
-Provide exactly one of `address`, `addressKeys`, or `legalParcelId`:
-
-```typescript
-// By address string
-const insights = await client.address.insights({
-  address: '15 Miranda Court, Noble Park VIC 3174',
-});
-
-// By GNAF address keys (up to 50)
-const insights2 = await client.address.insights({
-  addressKeys: ['100102HICKOXSTREETTRARALGONVIC3844'],
-});
-
-// By legal parcel ID
-const insights3 = await client.address.insights({
-  legalParcelId: '2\\TP574754',
-});
-
-for (const record of insights.results) {
-  console.log(`Address: ${record.address_label}`);
-  console.log(`  Bushfire risk: ${record.bushfire}`);
-  console.log(`  Flood risk: ${record.flood}`);
-  console.log(`  Heritage: ${record.heritage}`);
-  console.log(`  SEIFA (IRSAD): ${record.IRSAD}`);
-  console.log(`  Zoning: ${record.zoning}`);
-}
-```
-
 ### Address Standardisation
 
 Standardise raw address strings into structured, canonical components.
@@ -142,7 +109,7 @@ const result = await client.address.standardise({
 
 for (const item of result.results) {
   if (item.error) {
-    console.log(`Failed: ${item.input_address} — ${item.error}`);
+    console.log(`Failed: ${item.input_address} -- ${item.error}`);
   } else {
     const addr = item.standardised_address!;
     console.log(item.input_address);
@@ -153,6 +120,78 @@ for (const item of result.results) {
 }
 ```
 
+### Address Environment
+
+Retrieve environmental risk data for an address including flood, bushfire, heritage, and zoning.
+
+```typescript
+const env = await client.address.environment({
+  address: '15 Miranda Court, Noble Park VIC 3174',
+});
+for (const record of env.results) {
+  console.log(`Bushfire: ${record.bushfire}, Flood: ${record.flood}`);
+  console.log(`Heritage: ${record.heritage}, Zoning: ${record.zoning}`);
+}
+```
+
+### Address Demographics
+
+Retrieve socio-economic indices (SEIFA) and housing tenure data.
+
+```typescript
+const demo = await client.address.demographics({
+  address: '15 Miranda Court, Noble Park VIC 3174',
+});
+for (const record of demo.results) {
+  console.log(`IRSAD: ${record.IRSAD}, IER: ${record.IER}`);
+}
+```
+
+### Property Summary
+
+Retrieve physical property attributes for an address.
+
+```typescript
+const summary = await client.property.summary({
+  addressKey: '100102HICKOXSTREETTRARALGONVIC3844',
+});
+for (const record of summary.results) {
+  console.log(`Type: ${record.property_type}`);
+  console.log(`Beds: ${record.beds}, Baths: ${record.baths}, Parking: ${record.parking}`);
+  console.log(`Land: ${record.lot_size} sqm, Floor: ${record.floor_area} sqm`);
+}
+```
+
+### Property Estimates
+
+Retrieve valuation estimates and transaction history for an address.
+
+```typescript
+const est = await client.property.estimates({
+  addressKey: '100102HICKOXSTREETTRARALGONVIC3844',
+});
+for (const record of est.results) {
+  console.log(`Price estimate: $${record.price_estimate?.toLocaleString()}`);
+  console.log(`Rent estimate: $${record.rent_estimate}/wk`);
+  console.log(`Last sold: $${record.last_sold_price?.toLocaleString()} on ${record.last_sold_date}`);
+}
+```
+
+### Property Market
+
+Retrieve market position indicators for an address.
+
+```typescript
+const mkt = await client.property.market({
+  addressKey: '100102HICKOXSTREETTRARALGONVIC3844',
+});
+for (const record of mkt.results) {
+  console.log(`Rental %: ${record.rental_percentage}`);
+  console.log(`Years to own: ${record.years_to_own}`);
+  console.log(`Hold period: ${record.hold_period} years`);
+}
+```
+
 ### Sold Property Search
 
 Search for recently sold properties near an address or coordinates.
@@ -171,7 +210,7 @@ const sold = await client.property.soldSearch({
 console.log(`${sold.total} properties found`);
 for (const prop of sold.results) {
   const price = prop.sold_price ? `$${prop.sold_price.toLocaleString()}` : 'undisclosed';
-  console.log(`  ${prop.street_address}, ${prop.suburb} — ${price} (${prop.sold_date})`);
+  console.log(`  ${prop.street_address}, ${prop.suburb} -- ${price} (${prop.sold_date})`);
 }
 ```
 
@@ -194,51 +233,38 @@ All filter parameters are optional:
 
 > Parameters use camelCase in TypeScript and are automatically converted to snake_case for the API.
 
-### Market Snapshots
+### Market Summary
 
-Get current market metrics at suburb or LGA level.
+Get headline market metrics at suburb or LGA level.
 
 ```typescript
-const snapshots = await client.markets.snapshots({
+const summary = await client.markets.summary({
   level: 'suburb',
-  propertyType: ['house'],
   areaId: ['SAL10001'],
-  limit: 10,
+  propertyType: ['house'],
 });
 
-for (const snap of snapshots.results) {
-  console.log(`${snap.suburb} (${snap.state_name})`);
-  console.log(`  Typical price: $${snap.typical_price?.toLocaleString()}`);
-  console.log(`  Rent: $${snap.rent}/wk`);
-  if (snap.yield != null) console.log(`  Yield: ${(snap.yield * 100).toFixed(1)}%`);
-  if (snap.one_y_price_growth != null) {
-    console.log(`  1Y growth: ${(snap.one_y_price_growth * 100).toFixed(1)}%`);
-  }
+for (const record of summary.results) {
+  console.log(`${record.suburb} (${record.state_name})`);
+  console.log(`  Typical price: $${record.typical_price?.toLocaleString()}`);
+  console.log(`  Rent: $${record.rent}/wk`);
 }
 ```
 
-### Market Query (Advanced)
+### Market Growth
 
-Run complex market searches with filter logic using AND/OR/NOT operators.
+Retrieve cumulative or annualised growth rates for price, rent, and yield.
 
 ```typescript
-const results = await client.markets.query({
+const growth = await client.markets.growthCumulative({
   level: 'suburb',
-  mode: 'search',
-  property_types: ['house'],
-  typical_price_min: 500_000,
-  typical_price_max: 1_500_000,
-  logic: {
-    and: [
-      { field: 'one_y_price_growth', gte: 0.05 },
-      { field: 'vacancy_rate', lte: 0.03 },
-    ],
-  },
-  limit: 20,
+  areaId: ['SAL10001'],
+  propertyType: ['house'],
 });
 
-for (const snap of results.results) {
-  console.log(`${snap.suburb}: $${snap.typical_price?.toLocaleString()}`);
+for (const record of growth.results) {
+  console.log(`1Y price growth: ${record.one_y_price_growth}`);
+  console.log(`5Y price growth: ${record.five_y_price_growth}`);
 }
 ```
 
@@ -261,50 +287,52 @@ for (const p of prices.results) {
 
 // Rent history
 const rents = await client.markets.trends.rent({
-  level: 'suburb',
-  areaId: ['SAL10001'],
+  level: 'suburb', areaId: ['SAL10001'],
 });
 
 // Yield history
 const yields = await client.markets.trends.yieldHistory({
-  level: 'suburb',
-  areaId: ['SAL10001'],
-});
-
-// Supply & demand (inventory, vacancies, clearance rate)
-const supply = await client.markets.trends.supplyDemand({
-  level: 'suburb',
-  areaId: ['SAL10001'],
+  level: 'suburb', areaId: ['SAL10001'],
 });
 
 // Search interest index (buy/rent search indices)
 const search = await client.markets.trends.searchIndex({
-  level: 'suburb',
-  areaId: ['SAL10001'],
+  level: 'suburb', areaId: ['SAL10001'],
 });
 
 // Hold period
 const hold = await client.markets.trends.holdPeriod({
-  level: 'suburb',
-  areaId: ['SAL10001'],
-});
-
-// Performance essentials (price, rent, sales, rentals, yield)
-const perf = await client.markets.trends.performance({
-  level: 'suburb',
-  areaId: ['SAL10001'],
+  level: 'suburb', areaId: ['SAL10001'],
 });
 
 // Growth rates (price, rent, yield changes)
 const growth = await client.markets.trends.growthRates({
-  level: 'suburb',
-  areaId: ['SAL10001'],
+  level: 'suburb', areaId: ['SAL10001'],
 });
 
 // Demand profile (sales by dwelling type and bedrooms)
 const demand = await client.markets.trends.demandProfile({
-  level: 'suburb',
-  areaId: ['SAL10001'],
+  level: 'suburb', areaId: ['SAL10001'],
+});
+
+// Stock on market
+const som = await client.markets.trends.stockOnMarket({
+  level: 'suburb', areaId: ['SAL10001'],
+});
+
+// Days on market
+const dom = await client.markets.trends.daysOnMarket({
+  level: 'suburb', areaId: ['SAL10001'],
+});
+
+// Clearance rate
+const cr = await client.markets.trends.clearanceRate({
+  level: 'suburb', areaId: ['SAL10001'],
+});
+
+// Vacancy rate
+const vac = await client.markets.trends.vacancy({
+  level: 'suburb', areaId: ['SAL10001'],
 });
 ```
 
@@ -321,6 +349,56 @@ Common trend parameters:
 | `limit` | number | Max results (default 100, max 1000) |
 | `offset` | number | Pagination offset |
 
+## Internal API
+
+Some endpoints require the `internal_api` scope on your API key. These are accessed via the `client.internal` namespace:
+
+```typescript
+// Address search (trigram similarity matching)
+const results = await client.internal.address.search({ q: '100 George St Sydney' });
+
+// Address insights (enriched address data)
+const insights = await client.internal.address.insights({
+  address: '15 Miranda Court, Noble Park VIC 3174',
+});
+
+// Automated Valuation Model (batch, up to 50 properties)
+const avm = await client.internal.property.avm({
+  addressKey: ['100102HICKOXSTREETTRARALGONVIC3844'],
+});
+
+// Market snapshots with filtering
+const snapshots = await client.internal.markets.snapshots({
+  level: 'suburb',
+  propertyType: ['house'],
+  areaId: ['SAL10001'],
+});
+
+// Advanced market query with logical filters
+const queryResults = await client.internal.markets.query({
+  level: 'suburb',
+  mode: 'search',
+  property_types: ['house'],
+  typical_price_min: 500_000,
+  logic: {
+    and: [
+      { field: 'one_y_price_growth', gte: 0.05 },
+      { field: 'vacancy_rate', lte: 0.03 },
+    ],
+  },
+});
+
+// Internal trend endpoints
+const supply = await client.internal.markets.trends.supplyDemand({
+  level: 'suburb', areaId: ['SAL10001'],
+});
+const perf = await client.internal.markets.trends.performance({
+  level: 'suburb', areaId: ['SAL10001'],
+});
+```
+
+If you call an internal method without the required scope, the API will return a 403 error.
+
 ## Request Cancellation
 
 All methods accept an `AbortSignal` for cancellation:
@@ -332,8 +410,8 @@ const controller = new AbortController();
 setTimeout(() => controller.abort(), 5000);
 
 try {
-  const results = await client.address.search({
-    q: '100 George St',
+  const results = await client.address.geocode({
+    address: '100 George St',
     signal: controller.signal,
   });
 } catch (err) {
@@ -360,20 +438,20 @@ import {
 const client = new HtAgApiClient({ apiKey: 'sk-...' });
 
 try {
-  const results = await client.address.search({ q: 'Syd' });
+  const results = await client.address.geocode({ address: 'Syd' });
 } catch (err) {
   if (err instanceof AuthenticationError) {
-    // 401 or 403 — bad API key
+    // 401 or 403 -- bad API key or insufficient scope
     console.error(`Auth failed (HTTP ${err.status})`);
   } else if (err instanceof RateLimitError) {
-    // 429 — throttled (after exhausting retries)
+    // 429 -- throttled (after exhausting retries)
     console.error('Rate limited, try again later');
   } else if (err instanceof ValidationError) {
-    // 400 or 422 — bad request params
+    // 400 or 422 -- bad request params
     console.error(`Invalid request: ${err.message}`);
     console.error('Details:', err.body);
   } else if (err instanceof ServerError) {
-    // 5xx — upstream failure (after exhausting retries)
+    // 5xx -- upstream failure (after exhausting retries)
     console.error(`Server error (HTTP ${err.status})`);
   } else if (err instanceof HtAgError) {
     // Network/timeout/other
@@ -383,11 +461,11 @@ try {
 ```
 
 All errors carry:
-- `message` — human-readable description
-- `status` — HTTP status code (if applicable)
-- `body` — raw response body
-- `url` — the request URL that failed
-- `cause` — the underlying error (for network failures)
+- `message` -- human-readable description
+- `status` -- HTTP status code (if applicable)
+- `body` -- raw response body
+- `url` -- the request URL that failed
+- `cause` -- the underlying error (for network failures)
 
 ## Retries
 
@@ -414,7 +492,7 @@ const client = new HtAgApiClient({
 |--------|------|---------|-------------|
 | `apiKey` | string | required | Your HtAG API key |
 | `environment` | `'dev'` \| `'prod'` | `'prod'` | API environment |
-| `baseUrl` | string | — | Custom base URL (overrides environment) |
+| `baseUrl` | string | -- | Custom base URL (overrides environment) |
 | `timeout` | number | `30000` | Request timeout in milliseconds |
 | `maxRetries` | number | `3` | Maximum retry attempts |
 | `retryBaseDelay` | number | `500` | Base delay between retries in ms |
@@ -438,9 +516,12 @@ All types are exported for use in your application:
 ```typescript
 import type {
   AddressRecord,
-  AddressSearchResult,
+  GeocodeRecord,
   SoldPropertyRecord,
-  MarketSnapshot,
+  PropertySummaryRecord,
+  PropertyEstimatesRecord,
+  PropertyMarketRecord,
+  MarketSummaryRecord,
   PriceHistoryOut,
   RentHistoryOut,
   BaseResponse,