townshipamerica 1.0.1 → 2.0.0

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/townshipamerica)](https://www.npmjs.com/package/townshipamerica)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
-Official TypeScript SDK for the [Township America API](https://townshipamerica.com/api) — convert US PLSS (Public Land Survey System) legal land descriptions to GPS coordinates and back.
+Official TypeScript SDK for the [Township America API](https://townshipamerica.com/api) — convert US PLSS (Public Land Survey System) and Texas TXSS legal land descriptions to GPS coordinates and back.
 
 [Documentation](https://townshipamerica.com/api) · [GitHub](https://github.com/townshipamerica/typescript-sdk) · [npm](https://www.npmjs.com/package/townshipamerica)
 
@@ -21,23 +21,27 @@ import { TownshipClient } from "townshipamerica";
 const client = new TownshipClient({ apiKey: "YOUR_API_KEY" });
 
 // PLSS to GPS
-const result = await client.search("NW 25 24N 1E 6th Meridian");
-console.log(result.latitude, result.longitude); // 41.077932 -104.01924
-console.log(result.state); // "Colorado"
-console.log(result.county); // "Weld"
+const plss = await client.search("NW 25 24N 1E 6th Meridian");
+console.log(plss.latitude, plss.longitude); // 41.077932 -104.01924
+console.log(plss.surveySystem); // "PLSS"
 
-// GPS to PLSS
+// Texas TXSS to GPS
+const tx = await client.search("A-175 Reeves County");
+console.log(tx.surveySystem); // "TXSS"
+console.log(tx.state); // "TX"
+
+// GPS to legal description (PLSS or TXSS depending on location)
 const reverse = await client.reverse(-104.01924, 41.077932);
-console.log(reverse.legalLocation); // "NW 25 24N 1E 6th Meridian"
+console.log(reverse.legalLocation);
 
-// Autocomplete
-const suggestions = await client.autocomplete("NW 25", { limit: 5 });
+// Autocomplete (PLSS or TXSS)
+const suggestions = await client.autocomplete("A-175", { limit: 5 });
 console.log(suggestions.features[0].properties.legal_location);
 
-// Batch (up to 100 per request, auto-chunks larger arrays)
+// Batch — mix PLSS and TXSS in one call (up to 100 per request, auto-chunks larger arrays)
 const batch = await client.batchSearch([
   "NW 25 24N 1E 6th Meridian",
-  "NE 12 4N 5E Indian Meridian"
+  "A-175 Reeves County"
 ]);
 ```
 
@@ -55,10 +59,11 @@ const batch = await client.batchSearch([
 
 ### `client.search(legalLocation)`
 
-Convert a PLSS legal land description to GPS coordinates.
+Convert a PLSS or Texas TXSS legal land description to GPS coordinates.
 
 ```typescript
-const result = await client.search("NE 12 4N 5E Indian Meridian");
+const plss = await client.search("NE 12 4N 5E Indian Meridian");
+const tx = await client.search("A-175 Reeves County");
 ```
 
 **Returns:** `SearchResult`
@@ -70,17 +75,19 @@ const result = await client.search("NE 12 4N 5E Indian Meridian");
 | `longitude`              | `number`                   | Centroid longitude                                 |
 | `state`                  | `string`                   | US state                                           |
 | `county`                 | `string`                   | County                                             |
-| `unit`                   | `string`                   | `Township`, `First Division`, or `Second Division` |
-| `surveySystem`           | `string`                   | `PLSS`                                             |
+| `unit`                   | `string \| null`           | PLSS unit, or `null` for TXSS                      |
+| `surveySystem`           | `"PLSS" \| "TXSS"`         | Survey system                                      |
 | `alternateLegalLocation` | `string`                   | Alternate description format                       |
-| `boundary`               | `GeoJSONPolygon \| null`   | Grid boundary polygon                              |
+| `boundary`               | `GeoJSONBoundary \| null`  | Grid boundary polygon (Polygon or MultiPolygon)    |
 | `raw`                    | `GeoJSONFeatureCollection` | Raw API response                                   |
 
+TXSS responses also include `abstract_no`, `block_no`, `survey_name`, and `acreage` on feature properties when available.
+
 ---
 
 ### `client.reverse(longitude, latitude, options?)`
 
-Find the PLSS description at GPS coordinates.
+Find the legal land description at GPS coordinates (PLSS or Texas TXSS).
 
 ```typescript
 const result = await client.reverse(-104.01924, 41.077932, {
@@ -100,7 +107,7 @@ const result = await client.reverse(-104.01924, 41.077932, {
 
 ### `client.autocomplete(query, options?)`
 
-Get autocomplete suggestions for a partial PLSS description.
+Get autocomplete suggestions for a partial PLSS or Texas TXSS description.
 
 ```typescript
 const fc = await client.autocomplete("NW 25", { limit: 5 });
@@ -171,7 +178,7 @@ const polygon = await client.boundary("NW 25 24N 1E 6th Meridian");
 // polygon.coordinates === [[[lng, lat], ...]]
 ```
 
-**Returns:** `GeoJSONPolygon | null`
+**Returns:** `GeoJSONPolygon | GeoJSONMultiPolygon | null`
 
 ---
 
@@ -187,6 +194,131 @@ const fc = await client.raw("NW 25 24N 1E 6th Meridian");
 
 ---
 
+### `client.energyReport(legalLocation, options?)`
+
+Energy parcel report for a PLSS section — state-regulator wells, operators,
+BLM federal leases, ONRR county royalties, orphaned wells, pipelines,
+FracFocus disclosures, and development constraints.
+
+```typescript
+const report = await client.energyReport("25 24N 1E 6th Meridian");
+console.log(report.summary.wells_in_section);
+console.log(report.wells?.in_section.rows[0]?.api_number);
+
+// Only the sections you need — the rest are never queried
+const slim = await client.energyReport("25 24N 1E 6th Meridian", {
+  include: ["wells", "pipelines"]
+});
+
+// Attach the parcel boundary under parcel.geometry
+const withGeometry = await client.energyReport("25 24N 1E 6th Meridian", {
+  include: ["geometry"]
+});
+```
+
+**Options:** `include` — any of `wells`, `operators`, `leases`, `royalties`,
+`orphaned_wells`, `pipelines`, `fracfocus`, `constraints`, `geometry`.
+
+**Returns:** `EnergyReport`. Array sections are
+`{total, returned, truncated, more, rows}` envelopes; a failed section lands
+in `meta.unavailable` instead of failing the report.
+
+---
+
+### `client.federalLandReport(legalLocation, options?)`
+
+Federal-land parcel report for a PLSS tract — surface management, BLM O&G and
+geothermal leases, rights-of-way, flood zones, mining claims, wetlands,
+firesheds, soils, crop history, orphaned wells, critical habitat, public
+access, wildfire risk, and elevation.
+
+```typescript
+const report = await client.federalLandReport("NW 25 24N 1E 6th Meridian");
+console.log(report.surface_management?.rows[0]?.agency);
+
+const slim = await client.federalLandReport("NW 25 24N 1E 6th Meridian", {
+  include: ["og_leases", "flood_zones"]
+});
+```
+
+**Options:** `include` — any of `surface_management`, `og_leases`,
+`geothermal_leases`, `rights_of_way`, `flood_zones`, `mining_claims`,
+`wetlands`, `fireshed`, `soils`, `crop_history`, `orphaned_wells`,
+`critical_habitat`, `public_access`, `wildfire_risk_communities`,
+`elevation`, `geometry`.
+
+**Returns:** `FederalLandReport`. `report_scope` is `"containing_section"`
+when the tract is finer than the stored grid (the section is named by
+`report_section`); a layer the state has no data for is listed in
+`meta.unavailable` with reason `no_state_coverage`.
+
+---
+
+### `client.texasReport(legalLocation, options?)`
+
+Texas abstract report for a TXSS legal description — GLO state leases and
+pooled units, PSF lands, state-agency lands, upland leases, RRC wells and T-4
+pipelines, pending permits, coastal erosion, federal overlays (flood zones,
+wetlands, firesheds, soils, orphaned wells, critical habitat, wildfire risk),
+elevation, and RRC lease production.
+
+```typescript
+const report = await client.texasReport("A-175 Reeves County");
+console.log(report.active_wells?.rows[0]?.api_number);
+console.log(report.production?.summary.total_cum_boe);
+
+const slim = await client.texasReport("A-175 Reeves County", {
+  include: ["state_leases", "production"]
+});
+```
+
+**Options:** `include` — any of `state_leases`, `state_units`, `psf_lands`,
+`state_agency_lands`, `upland_leases`, `active_wells`, `pipelines`,
+`pending_permits`, `coastal_erosion`, `flood_zones`, `wetlands`, `fireshed`,
+`soils`, `orphaned_wells`, `critical_habitat`, `wildfire_risk_communities`,
+`elevation`, `production`, `geometry`.
+
+**Returns:** `TexasReport`
+
+---
+
+### `client.texasProduction(options)`
+
+RRC lease production for a Texas abstract — per-lease lifetime totals,
+trailing-12-month volumes, and the 60-month monthly series. Key by a legal
+description OR the registry ids.
+
+```typescript
+const byLocation = await client.texasProduction({ legalLocation: "A-175 Reeves County" });
+const byKeys = await client.texasProduction({ countyFips: "48389", abstractNo: "175" });
+console.log(byKeys.summary.total_cum_boe);
+```
+
+**Options:** `{ legalLocation }` or `{ countyFips, abstractNo, blockNo? }`
+
+**Returns:** `TexasProduction`. Production is reported by RRC at the lease
+level — rows are the leases whose wells fall on the abstract, never
+sub-allocated to the tract.
+
+---
+
+### `client.texasWell(api)`
+
+Per-well allocated production for a Texas well by API number (API-8 or
+API-14) — summary scalars for every lease edge, the monthly series (when
+provisioned), and an Arps decline fit.
+
+```typescript
+const well = await client.texasWell("42-389-32345");
+console.log(well.units[0]?.cum_boe);
+if (well.decline.available) console.log(well.decline.value?.di);
+```
+
+**Returns:** `TexasWell`. Volumes are allocated estimates — RRC reports
+production by lease, never by well.
+
+---
+
 ## Error Handling
 
 All errors extend `TownshipError`:
@@ -217,7 +349,43 @@ try {
 }
 ```
 
-## PLSS Format Examples
+Errors from the Energy, Federal Land, and Texas APIs also carry a
+machine-readable `code` (e.g. `invalid_parameter`, `plss_not_supported`,
+`ambiguous_location`, `not_found`, `rate_limit_exceeded`); it is `null` for
+endpoints that do not send one:
+
+```typescript
+try {
+  await client.texasReport("NW 25 24N 1E 6th Meridian");
+} catch (error) {
+  if (error instanceof ValidationError && error.code === "plss_not_supported") {
+    // Use federalLandReport or energyReport for PLSS descriptions
+  }
+}
+```
+
+## What's new in v2.0.0
+
+v2.0.0 adds the parcel-report APIs:
+
+- `client.energyReport(legalLocation, { include? })` — Energy API report
+- `client.federalLandReport(legalLocation, { include? })` — Federal Land API report
+- `client.texasReport(legalLocation, { include? })` — Texas abstract report
+- `client.texasProduction({ legalLocation } | { countyFips, abstractNo, blockNo? })` — RRC lease production
+- `client.texasWell(api)` — per-well allocated production + Arps decline fit
+
+Breaking changes:
+
+- Error classes gained a third constructor parameter and a readonly `code`
+  property (`string | null`). If you subclass or construct SDK errors
+  directly, update the constructor calls; `instanceof` checks are unaffected.
+- Error bodies of the form `{"error": {"code", "message"}}` (Energy, Federal
+  Land, and Texas APIs) are now parsed into `error.message`/`error.code`.
+  Legacy `{"error": "..."}` / `{"message": "..."}` bodies parse as before.
+
+## Format Examples
+
+### PLSS (30 states)
 
 ```
 NW 25 24N 1E 6th Meridian     → Quarter Section (First Division)
@@ -227,6 +395,15 @@ NE 12 4N 5E Indian Meridian   → Named meridian
 7 2N 3E Black Hills Meridian  → Section with named meridian
 ```
 
+### Texas TXSS
+
+```
+A-175 Reeves County
+Abstract 175 Reeves County Texas
+Block 25 Section 14 Pecos County
+Survey H&TC, Travis County
+```
+
 ## License
 
 MIT — [Maps & Apps Inc.](https://townshipamerica.com)

package/dist/index.cjs

@@ -32,39 +32,40 @@ module.exports = __toCommonJS(index_exports);
 
 // src/errors.ts
 var TownshipError = class extends Error {
-  constructor(message, statusCode = null) {
+  constructor(message, statusCode = null, code = null) {
     super(message);
     this.statusCode = statusCode;
+    this.code = code;
     this.name = "TownshipError";
   }
 };
 var AuthenticationError = class extends TownshipError {
-  constructor(message = "Invalid or missing API key") {
-    super(message, 401);
+  constructor(message = "Invalid or missing API key", code = null) {
+    super(message, 401, code);
     this.name = "AuthenticationError";
   }
 };
 var NotFoundError = class extends TownshipError {
-  constructor(message = "Location not found") {
-    super(message, 404);
+  constructor(message = "Location not found", code = null) {
+    super(message, 404, code);
     this.name = "NotFoundError";
   }
 };
 var RateLimitError = class extends TownshipError {
-  constructor(message = "Rate limit exceeded. Please slow down your requests.") {
-    super(message, 429);
+  constructor(message = "Rate limit exceeded. Please slow down your requests.", code = null) {
+    super(message, 429, code);
     this.name = "RateLimitError";
   }
 };
 var ValidationError = class extends TownshipError {
-  constructor(message = "Invalid request") {
-    super(message, 400);
+  constructor(message = "Invalid request", code = null) {
+    super(message, 400, code);
     this.name = "ValidationError";
   }
 };
 var PayloadTooLargeError = class extends TownshipError {
-  constructor(message = "Batch payload exceeds the maximum of 100 records per request") {
-    super(message, 413);
+  constructor(message = "Batch payload exceeds the maximum of 100 records per request", code = null) {
+    super(message, 413, code);
     this.name = "PayloadTooLargeError";
   }
 };
@@ -116,7 +117,7 @@ var TownshipClient = class {
         ...init,
         headers: {
           "X-API-Key": this.apiKey,
-          "User-Agent": "townshipamerica-js/1.0.0",
+          "User-Agent": "townshipamerica-js/2.0.0",
           ...init?.headers ?? {}
         },
         signal: controller.signal
@@ -137,25 +138,31 @@ var TownshipClient = class {
   }
   async handleError(response) {
     let message;
+    let code = null;
     try {
       const body = await response.json();
-      message = body.error ?? body.message ?? response.statusText;
+      if (body.error && typeof body.error === "object") {
+        message = body.error.message ?? response.statusText;
+        code = body.error.code ?? null;
+      } else {
+        message = (typeof body.error === "string" ? body.error : void 0) ?? body.message ?? response.statusText;
+      }
     } catch {
       message = response.statusText;
     }
     const status = response.status;
-    if (status === 400) throw new ValidationError(message);
-    if (status === 401) throw new AuthenticationError(message);
-    if (status === 404) throw new NotFoundError(message);
-    if (status === 413) throw new PayloadTooLargeError(message);
-    if (status === 429) throw new RateLimitError(message);
-    throw new TownshipError(message, status);
+    if (status === 400) throw new ValidationError(message, code);
+    if (status === 401) throw new AuthenticationError(message, code);
+    if (status === 404) throw new NotFoundError(message, code);
+    if (status === 413) throw new PayloadTooLargeError(message, code);
+    if (status === 429) throw new RateLimitError(message, code);
+    throw new TownshipError(message, status, code);
   }
   // --- Search ---
   /**
-   * Convert a PLSS legal land description to GPS coordinates.
+   * Convert a PLSS or Texas TXSS legal land description to GPS coordinates.
    *
-   * @param legalLocation - e.g. "NW 25 24N 1E 6th Meridian"
+   * @param legalLocation - e.g. "NW 25 24N 1E 6th Meridian" or "A-175 Reeves County"
    * @returns A SearchResult with coordinates, boundary, and metadata.
    * @throws {ValidationError} If the location string is invalid.
    * @throws {NotFoundError} If no match is found.
@@ -171,11 +178,11 @@ var TownshipClient = class {
     return toSearchResult(data);
   }
   /**
-   * Find the PLSS legal land description at the given GPS coordinates.
+   * Find the legal land description at the given GPS coordinates (PLSS or Texas TXSS).
    *
    * @param longitude - Longitude (x) coordinate.
    * @param latitude - Latitude (y) coordinate.
-   * @param options - Optional unit filter.
+   * @param options - Optional PLSS unit filter (ignored for TXSS results).
    * @returns A SearchResult or array of SearchResults (when unit is 'all').
    */
   async reverse(longitude, latitude, options) {
@@ -207,7 +214,7 @@ var TownshipClient = class {
   }
   // --- Autocomplete ---
   /**
-   * Get autocomplete suggestions for a partial PLSS description.
+   * Get autocomplete suggestions for a partial PLSS or Texas TXSS description.
    *
    * @param query - Partial search query (minimum 2 characters).
    * @param options - Optional limit (1–10, default 3) and proximity.
@@ -225,10 +232,10 @@ var TownshipClient = class {
   }
   // --- Batch ---
   /**
-   * Convert multiple PLSS descriptions to GPS coordinates in one request.
-   * Auto-chunks if more than 100 items.
+   * Convert multiple legal land descriptions to GPS coordinates in one request.
+   * Auto-chunks if more than 100 items. Mix PLSS and Texas TXSS inputs freely.
    *
-   * @param locations - Array of PLSS legal land descriptions.
+   * @param locations - Array of legal land descriptions.
    * @param options - Optional chunk size.
    * @returns Array of SearchResult or null for each input.
    */
@@ -256,11 +263,11 @@ var TownshipClient = class {
     return results;
   }
   /**
-   * Find PLSS descriptions for multiple coordinate pairs in one request.
+   * Find legal land descriptions for multiple coordinate pairs in one request.
    * Auto-chunks if more than 100 items.
    *
    * @param coordinates - Array of [longitude, latitude] pairs.
-   * @param options - Optional unit filter and chunk size.
+   * @param options - Optional PLSS unit filter and chunk size.
    * @returns Array of SearchResult or null for each input.
    */
   async batchReverse(coordinates, options) {
@@ -326,6 +333,137 @@ var TownshipClient = class {
     }
     return data;
   }
+  // --- Energy API ---
+  /**
+   * Get the energy parcel report for a PLSS section. Covers state-regulator
+   * wells, operators, federal leases, county royalties, orphaned wells,
+   * pipelines, FracFocus disclosures, and development constraints.
+   *
+   * @param legalLocation - A PLSS legal description, e.g. "NW 25 24N 1E 6th Meridian"
+   * @param options - Optional section projection (`include`)
+   * @returns The energy report
+   *
+   * @example
+   * ```ts
+   * const report = await client.energyReport('25 24N 1E 6th Meridian')
+   * console.log(report.summary.wells_in_section)
+   * console.log(report.wells?.in_section.rows[0]?.api_number)
+   *
+   * // Only the sections you need — the rest are never queried
+   * const slim = await client.energyReport('25 24N 1E 6th Meridian', {
+   *   include: ['wells', 'pipelines']
+   * })
+   * ```
+   */
+  async energyReport(legalLocation, options) {
+    const params = new URLSearchParams({ legal_location: legalLocation });
+    if (options?.include?.length) params.set("include", options.include.join(","));
+    return this.request(`/energy/report?${params}`);
+  }
+  // --- Federal Land API ---
+  /**
+   * Get the federal-land parcel report for a PLSS tract. Covers surface
+   * management, BLM leases and rights-of-way, flood zones, mining claims,
+   * wetlands, firesheds, soils, crop history, orphaned wells, critical
+   * habitat, public access, wildfire risk, and elevation.
+   *
+   * @param legalLocation - A PLSS legal description, e.g. "NW 25 24N 1E 6th Meridian"
+   * @param options - Optional section projection (`include`)
+   * @returns The federal-land report
+   *
+   * @example
+   * ```ts
+   * const report = await client.federalLandReport('NW 25 24N 1E 6th Meridian')
+   * console.log(report.surface_management?.rows[0]?.agency)
+   *
+   * // Only the sections you need — the pruned layers' queries never run
+   * const slim = await client.federalLandReport('NW 25 24N 1E 6th Meridian', {
+   *   include: ['og_leases', 'flood_zones']
+   * })
+   * ```
+   */
+  async federalLandReport(legalLocation, options) {
+    const params = new URLSearchParams({ legal_location: legalLocation });
+    if (options?.include?.length) params.set("include", options.include.join(","));
+    return this.request(`/federal-land/report?${params}`);
+  }
+  // --- Texas API ---
+  /**
+   * Get the Texas abstract report for a TXSS legal description. Covers GLO
+   * state leases and units, PSF lands, RRC wells and pipelines, pending
+   * permits, coastal erosion, federal overlays, and RRC lease production.
+   *
+   * @param legalLocation - A Texas legal description, e.g. "A-175 Reeves County"
+   * @param options - Optional section projection (`include`)
+   * @returns The Texas report
+   *
+   * @example
+   * ```ts
+   * const report = await client.texasReport('A-175 Reeves County')
+   * console.log(report.active_wells?.rows[0]?.api_number)
+   * console.log(report.production?.summary.total_cum_boe)
+   *
+   * // Only the sections you need — the rest are never queried
+   * const slim = await client.texasReport('A-175 Reeves County', {
+   *   include: ['state_leases', 'production']
+   * })
+   * ```
+   */
+  async texasReport(legalLocation, options) {
+    const params = new URLSearchParams({ legal_location: legalLocation });
+    if (options?.include?.length) params.set("include", options.include.join(","));
+    return this.request(`/texas/report?${params}`);
+  }
+  /**
+   * Get RRC lease production for a Texas abstract — per-lease lifetime
+   * totals, trailing-12-month volumes, and the 60-month monthly series.
+   * Production is reported by RRC at the LEASE level: rows are the leases
+   * whose wells fall on the abstract, never sub-allocated to the tract.
+   *
+   * @param options - Either `{legalLocation}` or `{countyFips, abstractNo, blockNo?}`
+   * @returns The abstract production rollup
+   *
+   * @example
+   * ```ts
+   * const byLocation = await client.texasProduction({ legalLocation: 'A-175 Reeves County' })
+   * const byKeys = await client.texasProduction({ countyFips: '48389', abstractNo: '175' })
+   * console.log(byKeys.summary.total_cum_boe)
+   * ```
+   */
+  async texasProduction(options) {
+    const params = new URLSearchParams();
+    if (options.legalLocation != null) {
+      params.set("legal_location", options.legalLocation);
+    } else if (options.countyFips != null && options.abstractNo != null) {
+      params.set("county_fips", options.countyFips);
+      params.set("abstract_no", options.abstractNo);
+      if (options.blockNo != null) params.set("block_no", options.blockNo);
+    } else {
+      throw new TownshipError(
+        "texasProduction requires either legalLocation or countyFips + abstractNo"
+      );
+    }
+    return this.request(`/texas/production?${params}`);
+  }
+  /**
+   * Get per-well allocated production for a Texas well by API number —
+   * summary scalars for every lease edge, the monthly series (when
+   * provisioned), and an Arps decline fit. Volumes are allocated estimates:
+   * RRC reports production by lease, never by well.
+   *
+   * @param api - API-8 or API-14 number (e.g. "42-389-32345" or "42389323450000")
+   * @returns The well's units, series, and decline analysis
+   *
+   * @example
+   * ```ts
+   * const well = await client.texasWell('42-389-32345')
+   * console.log(well.units[0]?.cum_boe)
+   * console.log(well.decline.available && well.decline.value?.di)
+   * ```
+   */
+  async texasWell(api) {
+    return this.request(`/texas/wells/${encodeURIComponent(api)}`);
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {