townshipamerica 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,185 @@
+interface TownshipClientOptions {
+    /** Township America API key. */
+    apiKey: string;
+    /** Override the default API base URL. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000). */
+    timeout?: number;
+}
+interface GeoJSONPoint {
+    type: "Point";
+    coordinates: [longitude: number, latitude: number];
+}
+interface GeoJSONPolygon {
+    type: "Polygon";
+    coordinates: number[][][];
+}
+type Unit = "Township" | "First Division" | "Second Division";
+interface FeatureProperties {
+    shape: "grid" | "centroid";
+    search_term: string | number[];
+    legal_location: string;
+    alternate_legal_location?: string;
+    unit?: Unit;
+    survey_system?: string;
+    county?: string;
+    state?: string;
+}
+interface GeoJSONFeature<G = GeoJSONPoint | GeoJSONPolygon> {
+    type: "Feature";
+    geometry: G;
+    properties: FeatureProperties;
+}
+interface GeoJSONFeatureCollection {
+    type: "FeatureCollection";
+    features: GeoJSONFeature[];
+}
+interface SearchResult {
+    /** The normalized legal land description. */
+    legalLocation: string;
+    /** Latitude of the centroid. */
+    latitude: number;
+    /** Longitude of the centroid. */
+    longitude: number;
+    /** US state where the land unit is located. */
+    state: string | undefined;
+    /** County where the land unit is located. */
+    county: string | undefined;
+    /** The land unit type (Township, First Division, Second Division). */
+    unit: string | undefined;
+    /** The survey system (PLSS). */
+    surveySystem: string | undefined;
+    /** Alternate legal land description if available. */
+    alternateLegalLocation: string | undefined;
+    /** Grid boundary polygon, or null if no boundary returned. */
+    boundary: GeoJSONPolygon | null;
+    /** The raw GeoJSON FeatureCollection from the API. */
+    raw: GeoJSONFeatureCollection;
+}
+interface ReverseOptions {
+    /** Precision level: 'Township', 'First Division', 'Second Division', or 'all'. */
+    unit?: Unit | "all";
+}
+interface AutocompleteOptions {
+    /** Maximum number of suggestions (1–10, default 3). */
+    limit?: number;
+    /** [longitude, latitude] to bias results toward. */
+    proximity?: [number, number];
+}
+interface BatchSearchOptions {
+    /** Max items per HTTP request (default 100, max 100). */
+    chunkSize?: number;
+}
+interface BatchReverseOptions {
+    /** Precision level: 'Township', 'First Division', 'Second Division', or 'all'. */
+    unit?: Unit | "all";
+    /** Max items per HTTP request (default 100, max 100). */
+    chunkSize?: number;
+}
+
+declare class TownshipClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(options: TownshipClientOptions);
+    private request;
+    private handleError;
+    /**
+     * 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.
+     */
+    search(legalLocation: string): Promise<SearchResult>;
+    /**
+     * 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').
+     */
+    reverse(longitude: number, latitude: number, options?: ReverseOptions): Promise<SearchResult | SearchResult[]>;
+    /**
+     * 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.
+     */
+    autocomplete(query: string, options?: AutocompleteOptions): Promise<GeoJSONFeatureCollection>;
+    /**
+     * 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.
+     */
+    batchSearch(locations: string[], options?: BatchSearchOptions): Promise<(SearchResult | null)[]>;
+    /**
+     * 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.
+     */
+    batchReverse(coordinates: [number, number][], options?: BatchReverseOptions): Promise<(SearchResult | null)[]>;
+    /**
+     * 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.
+     */
+    boundary(legalLocation: string): Promise<GeoJSONPolygon | null>;
+    /**
+     * 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.
+     */
+    raw(legalLocation: string): Promise<GeoJSONFeatureCollection>;
+}
+
+/**
+ * Base error class for all Township SDK errors.
+ */
+declare class TownshipError extends Error {
+    readonly statusCode: number | null;
+    constructor(message: string, statusCode?: number | null);
+}
+/**
+ * Thrown when the API key is missing or invalid (HTTP 401).
+ */
+declare class AuthenticationError extends TownshipError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when no result is found for the given input.
+ */
+declare class NotFoundError extends TownshipError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the API rate limit is exceeded (HTTP 429).
+ */
+declare class RateLimitError extends TownshipError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the request is malformed (HTTP 400).
+ */
+declare class ValidationError extends TownshipError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the batch payload exceeds the maximum size (HTTP 413).
+ */
+declare class PayloadTooLargeError extends TownshipError {
+    constructor(message?: string);
+}
+
+export { AuthenticationError, type AutocompleteOptions, type BatchReverseOptions, type BatchSearchOptions, type FeatureProperties, type GeoJSONFeature, type GeoJSONFeatureCollection, type GeoJSONPoint, type GeoJSONPolygon, NotFoundError, PayloadTooLargeError, RateLimitError, type ReverseOptions, type SearchResult, TownshipClient, type TownshipClientOptions, TownshipError, type Unit, ValidationError };

package/dist/index.d.ts

@@ -0,0 +1,185 @@
+interface TownshipClientOptions {
+    /** Township America API key. */
+    apiKey: string;
+    /** Override the default API base URL. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000). */
+    timeout?: number;
+}
+interface GeoJSONPoint {
+    type: "Point";
+    coordinates: [longitude: number, latitude: number];
+}
+interface GeoJSONPolygon {
+    type: "Polygon";
+    coordinates: number[][][];
+}
+type Unit = "Township" | "First Division" | "Second Division";
+interface FeatureProperties {
+    shape: "grid" | "centroid";
+    search_term: string | number[];
+    legal_location: string;
+    alternate_legal_location?: string;
+    unit?: Unit;
+    survey_system?: string;
+    county?: string;
+    state?: string;
+}
+interface GeoJSONFeature<G = GeoJSONPoint | GeoJSONPolygon> {
+    type: "Feature";
+    geometry: G;
+    properties: FeatureProperties;
+}
+interface GeoJSONFeatureCollection {
+    type: "FeatureCollection";
+    features: GeoJSONFeature[];
+}
+interface SearchResult {
+    /** The normalized legal land description. */
+    legalLocation: string;
+    /** Latitude of the centroid. */
+    latitude: number;
+    /** Longitude of the centroid. */
+    longitude: number;
+    /** US state where the land unit is located. */
+    state: string | undefined;
+    /** County where the land unit is located. */
+    county: string | undefined;
+    /** The land unit type (Township, First Division, Second Division). */
+    unit: string | undefined;
+    /** The survey system (PLSS). */
+    surveySystem: string | undefined;
+    /** Alternate legal land description if available. */
+    alternateLegalLocation: string | undefined;
+    /** Grid boundary polygon, or null if no boundary returned. */
+    boundary: GeoJSONPolygon | null;
+    /** The raw GeoJSON FeatureCollection from the API. */
+    raw: GeoJSONFeatureCollection;
+}
+interface ReverseOptions {
+    /** Precision level: 'Township', 'First Division', 'Second Division', or 'all'. */
+    unit?: Unit | "all";
+}
+interface AutocompleteOptions {
+    /** Maximum number of suggestions (1–10, default 3). */
+    limit?: number;
+    /** [longitude, latitude] to bias results toward. */
+    proximity?: [number, number];
+}
+interface BatchSearchOptions {
+    /** Max items per HTTP request (default 100, max 100). */
+    chunkSize?: number;
+}
+interface BatchReverseOptions {
+    /** Precision level: 'Township', 'First Division', 'Second Division', or 'all'. */
+    unit?: Unit | "all";
+    /** Max items per HTTP request (default 100, max 100). */
+    chunkSize?: number;
+}
+
+declare class TownshipClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(options: TownshipClientOptions);
+    private request;
+    private handleError;
+    /**
+     * 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.
+     */
+    search(legalLocation: string): Promise<SearchResult>;
+    /**
+     * 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').
+     */
+    reverse(longitude: number, latitude: number, options?: ReverseOptions): Promise<SearchResult | SearchResult[]>;
+    /**
+     * 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.
+     */
+    autocomplete(query: string, options?: AutocompleteOptions): Promise<GeoJSONFeatureCollection>;
+    /**
+     * 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.
+     */
+    batchSearch(locations: string[], options?: BatchSearchOptions): Promise<(SearchResult | null)[]>;
+    /**
+     * 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.
+     */
+    batchReverse(coordinates: [number, number][], options?: BatchReverseOptions): Promise<(SearchResult | null)[]>;
+    /**
+     * 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.
+     */
+    boundary(legalLocation: string): Promise<GeoJSONPolygon | null>;
+    /**
+     * 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.
+     */
+    raw(legalLocation: string): Promise<GeoJSONFeatureCollection>;
+}
+
+/**
+ * Base error class for all Township SDK errors.
+ */
+declare class TownshipError extends Error {
+    readonly statusCode: number | null;
+    constructor(message: string, statusCode?: number | null);
+}
+/**
+ * Thrown when the API key is missing or invalid (HTTP 401).
+ */
+declare class AuthenticationError extends TownshipError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when no result is found for the given input.
+ */
+declare class NotFoundError extends TownshipError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the API rate limit is exceeded (HTTP 429).
+ */
+declare class RateLimitError extends TownshipError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the request is malformed (HTTP 400).
+ */
+declare class ValidationError extends TownshipError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the batch payload exceeds the maximum size (HTTP 413).
+ */
+declare class PayloadTooLargeError extends TownshipError {
+    constructor(message?: string);
+}
+
+export { AuthenticationError, type AutocompleteOptions, type BatchReverseOptions, type BatchSearchOptions, type FeatureProperties, type GeoJSONFeature, type GeoJSONFeatureCollection, type GeoJSONPoint, type GeoJSONPolygon, NotFoundError, PayloadTooLargeError, RateLimitError, type ReverseOptions, type SearchResult, TownshipClient, type TownshipClientOptions, TownshipError, type Unit, ValidationError };

package/dist/index.js

@@ -0,0 +1,307 @@
+// 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;
+  }
+};
+export {
+  AuthenticationError,
+  NotFoundError,
+  PayloadTooLargeError,
+  RateLimitError,
+  TownshipClient,
+  TownshipError,
+  ValidationError
+};
+//# sourceMappingURL=index.js.map