townshipamerica 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maps & Apps Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,227 @@
+# townshipamerica
+
+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.
+
+## Install
+
+```bash
+npm install townshipamerica
+```
+
+## Quick Start
+
+```typescript
+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"
+
+// GPS to PLSS
+const reverse = await client.reverse(-104.01924, 41.077932);
+console.log(reverse.legalLocation); // "NW 25 24N 1E 6th Meridian"
+
+// Autocomplete
+const suggestions = await client.autocomplete("NW 25", { limit: 5 });
+console.log(suggestions.features[0].properties.legal_location);
+
+// Batch (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"
+]);
+```
+
+## API Reference
+
+### `new TownshipClient(options)`
+
+| Option    | Type     | Default                                 | Description                                                                        |
+| --------- | -------- | --------------------------------------- | ---------------------------------------------------------------------------------- |
+| `apiKey`  | `string` | —                                       | **Required.** Your API key from [townshipamerica.com](https://townshipamerica.com) |
+| `baseUrl` | `string` | `https://developer.townshipamerica.com` | Override the API base URL                                                          |
+| `timeout` | `number` | `30000`                                 | Request timeout in milliseconds                                                    |
+
+---
+
+### `client.search(legalLocation)`
+
+Convert a PLSS legal land description to GPS coordinates.
+
+```typescript
+const result = await client.search("NE 12 4N 5E Indian Meridian");
+```
+
+**Returns:** `SearchResult`
+
+| Field                    | Type                       | Description                                        |
+| ------------------------ | -------------------------- | -------------------------------------------------- |
+| `legalLocation`          | `string`                   | Normalized legal description                       |
+| `latitude`               | `number`                   | Centroid latitude                                  |
+| `longitude`              | `number`                   | Centroid longitude                                 |
+| `state`                  | `string`                   | US state                                           |
+| `county`                 | `string`                   | County                                             |
+| `unit`                   | `string`                   | `Township`, `First Division`, or `Second Division` |
+| `surveySystem`           | `string`                   | `PLSS`                                             |
+| `alternateLegalLocation` | `string`                   | Alternate description format                       |
+| `boundary`               | `GeoJSONPolygon \| null`   | Grid boundary polygon                              |
+| `raw`                    | `GeoJSONFeatureCollection` | Raw API response                                   |
+
+---
+
+### `client.reverse(longitude, latitude, options?)`
+
+Find the PLSS description at GPS coordinates.
+
+```typescript
+const result = await client.reverse(-104.01924, 41.077932, {
+  unit: "First Division"
+});
+```
+
+**Options:**
+
+| Option | Type                                                           | Description      |
+| ------ | -------------------------------------------------------------- | ---------------- |
+| `unit` | `'Township' \| 'First Division' \| 'Second Division' \| 'all'` | Precision filter |
+
+**Returns:** `SearchResult` (single unit) or `SearchResult[]` (when `unit: 'all'`)
+
+---
+
+### `client.autocomplete(query, options?)`
+
+Get autocomplete suggestions for a partial PLSS description.
+
+```typescript
+const fc = await client.autocomplete("NW 25", { limit: 5 });
+for (const feature of fc.features) {
+  console.log(feature.properties.legal_location);
+}
+```
+
+**Options:**
+
+| Option      | Type         | Description                           |
+| ----------- | ------------ | ------------------------------------- |
+| `limit`     | `number`     | Max suggestions, 1–10 (default 3)     |
+| `proximity` | `[lng, lat]` | Bias results toward these coordinates |
+
+**Returns:** `GeoJSONFeatureCollection`
+
+---
+
+### `client.batchSearch(locations, options?)`
+
+Convert multiple descriptions in one request. Automatically chunks arrays larger than 100.
+
+```typescript
+const results = await client.batchSearch([
+  "NW 25 24N 1E 6th Meridian",
+  "NE 12 4N 5E Indian Meridian"
+]);
+// results[0] is SearchResult or null (if no match)
+```
+
+**Returns:** `(SearchResult | null)[]`
+
+---
+
+### `client.batchReverse(coordinates, options?)`
+
+Reverse geocode multiple coordinate pairs. Automatically chunks arrays larger than 100.
+
+```typescript
+const results = await client.batchReverse(
+  [
+    [-104.01924, 41.077932],
+    [-104.648933, 41.454928]
+  ],
+  { unit: "Township" }
+);
+```
+
+**Options:**
+
+| Option      | Type                                                           | Description                         |
+| ----------- | -------------------------------------------------------------- | ----------------------------------- |
+| `unit`      | `'Township' \| 'First Division' \| 'Second Division' \| 'all'` | Precision filter                    |
+| `chunkSize` | `number`                                                       | Items per request (default/max 100) |
+
+**Returns:** `(SearchResult | null)[]`
+
+---
+
+### `client.boundary(legalLocation)`
+
+Get just the boundary polygon for a legal description.
+
+```typescript
+const polygon = await client.boundary("NW 25 24N 1E 6th Meridian");
+// polygon.type === 'Polygon'
+// polygon.coordinates === [[[lng, lat], ...]]
+```
+
+**Returns:** `GeoJSONPolygon | null`
+
+---
+
+### `client.raw(legalLocation)`
+
+Get the raw GeoJSON FeatureCollection from the API (no transformation).
+
+```typescript
+const fc = await client.raw("NW 25 24N 1E 6th Meridian");
+```
+
+**Returns:** `GeoJSONFeatureCollection`
+
+---
+
+## Error Handling
+
+All errors extend `TownshipError`:
+
+```typescript
+import {
+  TownshipClient,
+  TownshipError,
+  AuthenticationError,
+  ValidationError,
+  NotFoundError,
+  RateLimitError,
+  PayloadTooLargeError
+} from "townshipamerica";
+
+try {
+  await client.search("NW 25 24N 1E 6th Meridian");
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    // Invalid API key (401)
+  } else if (error instanceof NotFoundError) {
+    // No results found
+  } else if (error instanceof RateLimitError) {
+    // Too many requests (429)
+  } else if (error instanceof ValidationError) {
+    // Bad request (400)
+  }
+}
+```
+
+## PLSS Format Examples
+
+```
+NW 25 24N 1E 6th Meridian     → Quarter Section (First Division)
+25 24N 1E 6th Meridian         → Section (Second Division)
+24N 1E 6th Meridian            → Township
+NE 12 4N 5E Indian Meridian   → Named meridian
+7 2N 3E Black Hills Meridian  → Section with named meridian
+```
+
+## License
+
+MIT — [Maps & Apps Inc.](https://townshipamerica.com)

package/dist/index.cjs

@@ -0,0 +1,340 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthenticationError: () => AuthenticationError,
+  NotFoundError: () => NotFoundError,
+  PayloadTooLargeError: () => PayloadTooLargeError,
+  RateLimitError: () => RateLimitError,
+  TownshipClient: () => TownshipClient,
+  TownshipError: () => TownshipError,
+  ValidationError: () => ValidationError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var TownshipError = class extends Error {
+  constructor(message, statusCode = null) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = "TownshipError";
+  }
+};
+var AuthenticationError = class extends TownshipError {
+  constructor(message = "Invalid or missing API key") {
+    super(message, 401);
+    this.name = "AuthenticationError";
+  }
+};
+var NotFoundError = class extends TownshipError {
+  constructor(message = "Location not found") {
+    super(message, 404);
+    this.name = "NotFoundError";
+  }
+};
+var RateLimitError = class extends TownshipError {
+  constructor(message = "Rate limit exceeded. Please slow down your requests.") {
+    super(message, 429);
+    this.name = "RateLimitError";
+  }
+};
+var ValidationError = class extends TownshipError {
+  constructor(message = "Invalid request") {
+    super(message, 400);
+    this.name = "ValidationError";
+  }
+};
+var PayloadTooLargeError = class extends TownshipError {
+  constructor(message = "Batch payload exceeds the maximum of 100 records per request") {
+    super(message, 413);
+    this.name = "PayloadTooLargeError";
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://developer.townshipamerica.com";
+var DEFAULT_TIMEOUT = 3e4;
+var MAX_BATCH_SIZE = 100;
+function toSearchResult(fc) {
+  const centroid = fc.features.find((f) => f.properties.shape === "centroid");
+  const grid = fc.features.find((f) => f.properties.shape === "grid");
+  const props = centroid?.properties ?? grid?.properties;
+  if (!props) {
+    throw new TownshipError("Unexpected API response: no features returned");
+  }
+  const [lng, lat] = centroid ? centroid.geometry.coordinates : [0, 0];
+  return {
+    legalLocation: props.legal_location,
+    latitude: lat,
+    longitude: lng,
+    state: props.state,
+    county: props.county,
+    unit: props.unit,
+    surveySystem: props.survey_system,
+    alternateLegalLocation: props.alternate_legal_location,
+    boundary: grid ? grid.geometry : null,
+    raw: fc
+  };
+}
+var TownshipClient = class {
+  baseUrl;
+  apiKey;
+  timeout;
+  constructor(options) {
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    if (!this.apiKey) {
+      throw new TownshipError("apiKey is required");
+    }
+  }
+  // --- Internal ---
+  async request(path, init) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        ...init,
+        headers: {
+          "X-API-Key": this.apiKey,
+          "User-Agent": "townshipamerica-js/1.0.0",
+          ...init?.headers ?? {}
+        },
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        await this.handleError(response);
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof TownshipError) throw error;
+      if (error instanceof DOMException && error.name === "AbortError") {
+        throw new TownshipError("Request timed out");
+      }
+      throw new TownshipError(error instanceof Error ? error.message : "Unknown error");
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async handleError(response) {
+    let message;
+    try {
+      const body = await response.json();
+      message = body.error ?? 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);
+  }
+  // --- Search ---
+  /**
+   * Convert a PLSS legal land description to GPS coordinates.
+   *
+   * @param legalLocation - e.g. "NW 25 24N 1E 6th Meridian"
+   * @returns A SearchResult with coordinates, boundary, and metadata.
+   * @throws {ValidationError} If the location string is invalid.
+   * @throws {NotFoundError} If no match is found.
+   */
+  async search(legalLocation) {
+    const params = new URLSearchParams({ location: legalLocation });
+    const data = await this.request(
+      `/search/legal-location?${params}`
+    );
+    if (!("features" in data) || !data.features?.length) {
+      throw new NotFoundError(`No results found for "${legalLocation}"`);
+    }
+    return toSearchResult(data);
+  }
+  /**
+   * Find the PLSS legal land description at the given GPS coordinates.
+   *
+   * @param longitude - Longitude (x) coordinate.
+   * @param latitude - Latitude (y) coordinate.
+   * @param options - Optional unit filter.
+   * @returns A SearchResult or array of SearchResults (when unit is 'all').
+   */
+  async reverse(longitude, latitude, options) {
+    const params = new URLSearchParams({
+      location: `${longitude},${latitude}`
+    });
+    if (options?.unit) {
+      params.set("unit", options.unit);
+    }
+    const data = await this.request(
+      `/search/coordinates?${params}`
+    );
+    if (!("features" in data) || !data.features?.length) {
+      throw new NotFoundError(`No results found for coordinates [${longitude}, ${latitude}]`);
+    }
+    const fc = data;
+    if (options?.unit === "all") {
+      const groups = /* @__PURE__ */ new Map();
+      for (const feature of fc.features) {
+        const key = feature.properties.legal_location;
+        if (!groups.has(key)) groups.set(key, []);
+        groups.get(key).push(feature);
+      }
+      return Array.from(groups.values()).map((features) => {
+        return toSearchResult({ type: "FeatureCollection", features });
+      });
+    }
+    return toSearchResult(fc);
+  }
+  // --- Autocomplete ---
+  /**
+   * Get autocomplete suggestions for a partial PLSS description.
+   *
+   * @param query - Partial search query (minimum 2 characters).
+   * @param options - Optional limit (1–10, default 3) and proximity.
+   * @returns Raw GeoJSON FeatureCollection with suggestion features.
+   */
+  async autocomplete(query, options) {
+    const params = new URLSearchParams({ location: query });
+    if (options?.limit != null) {
+      params.set("limit", String(options.limit));
+    }
+    if (options?.proximity) {
+      params.set("proximity", `${options.proximity[0]},${options.proximity[1]}`);
+    }
+    return this.request(`/autocomplete/legal-location?${params}`);
+  }
+  // --- Batch ---
+  /**
+   * Convert multiple PLSS descriptions to GPS coordinates in one request.
+   * Auto-chunks if more than 100 items.
+   *
+   * @param locations - Array of PLSS legal land descriptions.
+   * @param options - Optional chunk size.
+   * @returns Array of SearchResult or null for each input.
+   */
+  async batchSearch(locations, options) {
+    const chunkSize = Math.min(options?.chunkSize ?? MAX_BATCH_SIZE, MAX_BATCH_SIZE);
+    const results = [];
+    for (let i = 0; i < locations.length; i += chunkSize) {
+      const chunk = locations.slice(i, i + chunkSize);
+      const data = await this.request(
+        "/batch/legal-location",
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(chunk)
+        }
+      );
+      for (const fc of data) {
+        if (!fc || !fc.features?.length) {
+          results.push(null);
+        } else {
+          results.push(toSearchResult(fc));
+        }
+      }
+    }
+    return results;
+  }
+  /**
+   * Find PLSS 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.
+   * @returns Array of SearchResult or null for each input.
+   */
+  async batchReverse(coordinates, options) {
+    const chunkSize = Math.min(options?.chunkSize ?? MAX_BATCH_SIZE, MAX_BATCH_SIZE);
+    const results = [];
+    for (let i = 0; i < coordinates.length; i += chunkSize) {
+      const chunk = coordinates.slice(i, i + chunkSize);
+      const body = { coordinates: chunk };
+      if (options?.unit) {
+        body.unit = options.unit;
+      }
+      const data = await this.request("/batch/coordinates", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body)
+      });
+      if (Array.isArray(data)) {
+        for (const fc of data) {
+          if (!fc || !fc.features?.length) {
+            results.push(null);
+          } else {
+            results.push(toSearchResult(fc));
+          }
+        }
+      } else if (data && "features" in data) {
+        const groups = /* @__PURE__ */ new Map();
+        for (const feature of data.features) {
+          const key = JSON.stringify(feature.properties.search_term);
+          if (!groups.has(key)) groups.set(key, []);
+          groups.get(key).push(feature);
+        }
+        for (const features of groups.values()) {
+          results.push(toSearchResult({ type: "FeatureCollection", features }));
+        }
+      }
+    }
+    return results;
+  }
+  // --- Convenience ---
+  /**
+   * Get the boundary polygon for a legal land description.
+   *
+   * @param legalLocation - e.g. "NW 25 24N 1E 6th Meridian"
+   * @returns The boundary GeoJSON Polygon, or null if not found.
+   */
+  async boundary(legalLocation) {
+    const result = await this.search(legalLocation);
+    return result.boundary;
+  }
+  /**
+   * Get the raw GeoJSON FeatureCollection for a legal land description.
+   *
+   * @param legalLocation - e.g. "NW 25 24N 1E 6th Meridian"
+   * @returns The raw GeoJSON FeatureCollection from the API.
+   */
+  async raw(legalLocation) {
+    const params = new URLSearchParams({ location: legalLocation });
+    const data = await this.request(
+      `/search/legal-location?${params}`
+    );
+    if (!("features" in data)) {
+      return { type: "FeatureCollection", features: [] };
+    }
+    return data;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthenticationError,
+  NotFoundError,
+  PayloadTooLargeError,
+  RateLimitError,
+  TownshipClient,
+  TownshipError,
+  ValidationError
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/client.ts"],"sourcesContent":["export { TownshipClient } from \"./client.js\";\nexport {\n  TownshipError,\n  AuthenticationError,\n  NotFoundError,\n  RateLimitError,\n  ValidationError,\n  PayloadTooLargeError\n} from \"./errors.js\";\nexport type {\n  TownshipClientOptions,\n  GeoJSONPoint,\n  GeoJSONPolygon,\n  GeoJSONFeature,\n  GeoJSONFeatureCollection,\n  FeatureProperties,\n  Unit,\n  SearchResult,\n  ReverseOptions,\n  AutocompleteOptions,\n  BatchSearchOptions,\n  BatchReverseOptions\n} from \"./types.js\";\n","/**\n * Base error class for all Township SDK errors.\n */\nexport class TownshipError extends Error {\n  constructor(\n    message: string,\n    public readonly statusCode: number | null = null\n  ) {\n    super(message);\n    this.name = \"TownshipError\";\n  }\n}\n\n/**\n * Thrown when the API key is missing or invalid (HTTP 401).\n */\nexport class AuthenticationError extends TownshipError {\n  constructor(message = \"Invalid or missing API key\") {\n    super(message, 401);\n    this.name = \"AuthenticationError\";\n  }\n}\n\n/**\n * Thrown when no result is found for the given input.\n */\nexport class NotFoundError extends TownshipError {\n  constructor(message = \"Location not found\") {\n    super(message, 404);\n    this.name = \"NotFoundError\";\n  }\n}\n\n/**\n * Thrown when the API rate limit is exceeded (HTTP 429).\n */\nexport class RateLimitError extends TownshipError {\n  constructor(message = \"Rate limit exceeded. Please slow down your requests.\") {\n    super(message, 429);\n    this.name = \"RateLimitError\";\n  }\n}\n\n/**\n * Thrown when the request is malformed (HTTP 400).\n */\nexport class ValidationError extends TownshipError {\n  constructor(message = \"Invalid request\") {\n    super(message, 400);\n    this.name = \"ValidationError\";\n  }\n}\n\n/**\n * Thrown when the batch payload exceeds the maximum size (HTTP 413).\n */\nexport class PayloadTooLargeError extends TownshipError {\n  constructor(message = \"Batch payload exceeds the maximum of 100 records per request\") {\n    super(message, 413);\n    this.name = \"PayloadTooLargeError\";\n  }\n}\n","import {\n  AuthenticationError,\n  NotFoundError,\n  PayloadTooLargeError,\n  RateLimitError,\n  TownshipError,\n  ValidationError\n} from \"./errors.js\";\nimport type {\n  AutocompleteOptions,\n  BatchReverseOptions,\n  BatchSearchOptions,\n  GeoJSONFeatureCollection,\n  GeoJSONPolygon,\n  ReverseOptions,\n  SearchResult,\n  TownshipClientOptions\n} from \"./types.js\";\n\nconst DEFAULT_BASE_URL = \"https://developer.townshipamerica.com\";\nconst DEFAULT_TIMEOUT = 30_000;\nconst MAX_BATCH_SIZE = 100;\n\nfunction toSearchResult(fc: GeoJSONFeatureCollection): SearchResult {\n  const centroid = fc.features.find((f) => f.properties.shape === \"centroid\");\n  const grid = fc.features.find((f) => f.properties.shape === \"grid\");\n\n  const props = centroid?.properties ?? grid?.properties;\n  if (!props) {\n    throw new TownshipError(\"Unexpected API response: no features returned\");\n  }\n\n  const [lng, lat] = centroid ? (centroid.geometry.coordinates as [number, number]) : [0, 0];\n\n  return {\n    legalLocation: props.legal_location,\n    latitude: lat,\n    longitude: lng,\n    state: props.state,\n    county: props.county,\n    unit: props.unit,\n    surveySystem: props.survey_system,\n    alternateLegalLocation: props.alternate_legal_location,\n    boundary: grid ? (grid.geometry as GeoJSONPolygon) : null,\n    raw: fc\n  };\n}\n\nexport class TownshipClient {\n  private readonly baseUrl: string;\n  private readonly apiKey: string;\n  private readonly timeout: number;\n\n  constructor(options: TownshipClientOptions) {\n    this.apiKey = options.apiKey;\n    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, \"\");\n    this.timeout = options.timeout ?? DEFAULT_TIMEOUT;\n\n    if (!this.apiKey) {\n      throw new TownshipError(\"apiKey is required\");\n    }\n  }\n\n  // --- Internal ---\n\n  private async request<T>(path: string, init?: RequestInit): Promise<T> {\n    const url = `${this.baseUrl}${path}`;\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeout);\n\n    try {\n      const response = await fetch(url, {\n        ...init,\n        headers: {\n          \"X-API-Key\": this.apiKey,\n          \"User-Agent\": \"townshipamerica-js/1.0.0\",\n          ...(init?.headers ?? {})\n        },\n        signal: controller.signal\n      });\n\n      if (!response.ok) {\n        await this.handleError(response);\n      }\n\n      return (await response.json()) as T;\n    } catch (error) {\n      if (error instanceof TownshipError) throw error;\n      if (error instanceof DOMException && error.name === \"AbortError\") {\n        throw new TownshipError(\"Request timed out\");\n      }\n      throw new TownshipError(error instanceof Error ? error.message : \"Unknown error\");\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n\n  private async handleError(response: Response): Promise<never> {\n    let message: string;\n    try {\n      const body = (await response.json()) as Record<string, unknown>;\n      message = (body.error ?? body.message ?? response.statusText) as string;\n    } catch {\n      message = response.statusText;\n    }\n\n    const status = response.status;\n    if (status === 400) throw new ValidationError(message);\n    if (status === 401) throw new AuthenticationError(message);\n    if (status === 404) throw new NotFoundError(message);\n    if (status === 413) throw new PayloadTooLargeError(message);\n    if (status === 429) throw new RateLimitError(message);\n    throw new TownshipError(message, status);\n  }\n\n  // --- Search ---\n\n  /**\n   * Convert a PLSS legal land description to GPS coordinates.\n   *\n   * @param legalLocation - e.g. \"NW 25 24N 1E 6th Meridian\"\n   * @returns A SearchResult with coordinates, boundary, and metadata.\n   * @throws {ValidationError} If the location string is invalid.\n   * @throws {NotFoundError} If no match is found.\n   */\n  async search(legalLocation: string): Promise<SearchResult> {\n    const params = new URLSearchParams({ location: legalLocation });\n    const data = await this.request<GeoJSONFeatureCollection | Record<string, never>>(\n      `/search/legal-location?${params}`\n    );\n\n    if (!(\"features\" in data) || !data.features?.length) {\n      throw new NotFoundError(`No results found for \"${legalLocation}\"`);\n    }\n\n    return toSearchResult(data as GeoJSONFeatureCollection);\n  }\n\n  /**\n   * Find the PLSS legal land description at the given GPS coordinates.\n   *\n   * @param longitude - Longitude (x) coordinate.\n   * @param latitude - Latitude (y) coordinate.\n   * @param options - Optional unit filter.\n   * @returns A SearchResult or array of SearchResults (when unit is 'all').\n   */\n  async reverse(\n    longitude: number,\n    latitude: number,\n    options?: ReverseOptions\n  ): Promise<SearchResult | SearchResult[]> {\n    const params = new URLSearchParams({\n      location: `${longitude},${latitude}`\n    });\n    if (options?.unit) {\n      params.set(\"unit\", options.unit);\n    }\n\n    const data = await this.request<GeoJSONFeatureCollection | Record<string, never>>(\n      `/search/coordinates?${params}`\n    );\n\n    if (!(\"features\" in data) || !data.features?.length) {\n      throw new NotFoundError(`No results found for coordinates [${longitude}, ${latitude}]`);\n    }\n\n    const fc = data as GeoJSONFeatureCollection;\n\n    if (options?.unit === \"all\") {\n      const groups = new Map<string, typeof fc.features>();\n      for (const feature of fc.features) {\n        const key = feature.properties.legal_location;\n        if (!groups.has(key)) groups.set(key, []);\n        groups.get(key)!.push(feature);\n      }\n\n      return Array.from(groups.values()).map((features) => {\n        return toSearchResult({ type: \"FeatureCollection\", features });\n      });\n    }\n\n    return toSearchResult(fc);\n  }\n\n  // --- Autocomplete ---\n\n  /**\n   * Get autocomplete suggestions for a partial PLSS description.\n   *\n   * @param query - Partial search query (minimum 2 characters).\n   * @param options - Optional limit (1–10, default 3) and proximity.\n   * @returns Raw GeoJSON FeatureCollection with suggestion features.\n   */\n  async autocomplete(\n    query: string,\n    options?: AutocompleteOptions\n  ): Promise<GeoJSONFeatureCollection> {\n    const params = new URLSearchParams({ location: query });\n    if (options?.limit != null) {\n      params.set(\"limit\", String(options.limit));\n    }\n    if (options?.proximity) {\n      params.set(\"proximity\", `${options.proximity[0]},${options.proximity[1]}`);\n    }\n\n    return this.request<GeoJSONFeatureCollection>(`/autocomplete/legal-location?${params}`);\n  }\n\n  // --- Batch ---\n\n  /**\n   * Convert multiple PLSS descriptions to GPS coordinates in one request.\n   * Auto-chunks if more than 100 items.\n   *\n   * @param locations - Array of PLSS legal land descriptions.\n   * @param options - Optional chunk size.\n   * @returns Array of SearchResult or null for each input.\n   */\n  async batchSearch(\n    locations: string[],\n    options?: BatchSearchOptions\n  ): Promise<(SearchResult | null)[]> {\n    const chunkSize = Math.min(options?.chunkSize ?? MAX_BATCH_SIZE, MAX_BATCH_SIZE);\n    const results: (SearchResult | null)[] = [];\n\n    for (let i = 0; i < locations.length; i += chunkSize) {\n      const chunk = locations.slice(i, i + chunkSize);\n      const data = await this.request<(GeoJSONFeatureCollection | null)[]>(\n        \"/batch/legal-location\",\n        {\n          method: \"POST\",\n          headers: { \"Content-Type\": \"application/json\" },\n          body: JSON.stringify(chunk)\n        }\n      );\n\n      for (const fc of data) {\n        if (!fc || !fc.features?.length) {\n          results.push(null);\n        } else {\n          results.push(toSearchResult(fc));\n        }\n      }\n    }\n\n    return results;\n  }\n\n  /**\n   * Find PLSS descriptions for multiple coordinate pairs in one request.\n   * Auto-chunks if more than 100 items.\n   *\n   * @param coordinates - Array of [longitude, latitude] pairs.\n   * @param options - Optional unit filter and chunk size.\n   * @returns Array of SearchResult or null for each input.\n   */\n  async batchReverse(\n    coordinates: [number, number][],\n    options?: BatchReverseOptions\n  ): Promise<(SearchResult | null)[]> {\n    const chunkSize = Math.min(options?.chunkSize ?? MAX_BATCH_SIZE, MAX_BATCH_SIZE);\n    const results: (SearchResult | null)[] = [];\n\n    for (let i = 0; i < coordinates.length; i += chunkSize) {\n      const chunk = coordinates.slice(i, i + chunkSize);\n      const body: Record<string, unknown> = { coordinates: chunk };\n      if (options?.unit) {\n        body.unit = options.unit;\n      }\n\n      const data = await this.request<\n        (GeoJSONFeatureCollection | null)[] | GeoJSONFeatureCollection\n      >(\"/batch/coordinates\", {\n        method: \"POST\",\n        headers: { \"Content-Type\": \"application/json\" },\n        body: JSON.stringify(body)\n      });\n\n      if (Array.isArray(data)) {\n        for (const fc of data) {\n          if (!fc || !fc.features?.length) {\n            results.push(null);\n          } else {\n            results.push(toSearchResult(fc));\n          }\n        }\n      } else if (data && \"features\" in data) {\n        // unit=all returns a single FeatureCollection — split by legal_location\n        const groups = new Map<string, typeof data.features>();\n        for (const feature of data.features) {\n          const key = JSON.stringify(feature.properties.search_term);\n          if (!groups.has(key)) groups.set(key, []);\n          groups.get(key)!.push(feature);\n        }\n        for (const features of groups.values()) {\n          results.push(toSearchResult({ type: \"FeatureCollection\", features }));\n        }\n      }\n    }\n\n    return results;\n  }\n\n  // --- Convenience ---\n\n  /**\n   * Get the boundary polygon for a legal land description.\n   *\n   * @param legalLocation - e.g. \"NW 25 24N 1E 6th Meridian\"\n   * @returns The boundary GeoJSON Polygon, or null if not found.\n   */\n  async boundary(legalLocation: string): Promise<GeoJSONPolygon | null> {\n    const result = await this.search(legalLocation);\n    return result.boundary;\n  }\n\n  /**\n   * Get the raw GeoJSON FeatureCollection for a legal land description.\n   *\n   * @param legalLocation - e.g. \"NW 25 24N 1E 6th Meridian\"\n   * @returns The raw GeoJSON FeatureCollection from the API.\n   */\n  async raw(legalLocation: string): Promise<GeoJSONFeatureCollection> {\n    const params = new URLSearchParams({ location: legalLocation });\n    const data = await this.request<GeoJSONFeatureCollection | Record<string, never>>(\n      `/search/legal-location?${params}`\n    );\n\n    if (!(\"features\" in data)) {\n      return { type: \"FeatureCollection\", features: [] };\n    }\n\n    return data as GeoJSONFeatureCollection;\n  }\n}\n"],"mappings":"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","names":[]}