@identafly/hatch-forecast-client

TypeScript/JavaScript client for IdentaFly’s Hatch Forecast HTTP API (createClient, exported types).

Requirements

• Node.js 18+ (global fetch) or modern browsers.
• ESM only ("type": "module"): use import / import(), not require.

Authentication: Authorization: Bearer <uuid> with your Widget API Key id on every method except getUsgsStation, which does not send a key. Obtain a key from the IdentaFly portal.

Locations: Pass externalId — your property id (widget_locations.external_id), not our internal UUID.

Thumbnails in responses may be data:image/…;base64,… or https:// URLs (safe to use as img src).

Errors: Failed requests throw Error; where the API returns JSON, err.status and err.body may be set. Shapes mirror ApiErrorBody exported from this package (error.code, error.message, requestId).

Install

yarn add @identafly/hatch-forecast-client

Methods (return value of createClient)

| Kind | Method | Purpose | | ---------- | -------------------------- | ----------------------------------------------------------------------------- | | Read | getHatchForecast | Hatch forecast for externalId. | | Read | getUsgsForWidgetLocation | USGS gage for that location (authenticated). | | Read | getUsgsStation | USGS by NWIS site id (no API key — server proxies NWIS). | | Create | registerLocations | Batch-register locations (property_id, coords, optional usgs_station_id). | | Update | updateLocation | PATCH name / usgs_station_id for a propertyId. | | Delete | deleteLocation | Delete by propertyId. |

Exported types include LocationRegistrationInput, LocationRegistrationResult, RegisterLocationsResponse, UpdateLocationInput, HatchForecastResponse, ForecastGroup, UsgsStationResponse, and parseUsgsSiteIdFromLocationColumn for parsing stored usgs_station_id values.

Usage

Reads

import {
  createClient,
  parseUsgsSiteIdFromLocationColumn
} from '@identafly/hatch-forecast-client';

const client = createClient({
  apiKey: '<your-widget-api-key-uuid>'
});

const hatch = await client.getHatchForecast({ externalId: 'my-property-123' });
const gage = await client.getUsgsForWidgetLocation({
  externalId: 'my-property-123'
});

await client.getUsgsStation({ stationId: '09085000' });

const siteId = parseUsgsSiteIdFromLocationColumn(row.usgs_station_id);
if (siteId) await client.getUsgsStation({ stationId: siteId });

In browsers, call USGS only through getUsgsStation / getUsgsForWidgetLocation on your configured baseUrl — direct requests to NWIS commonly fail (CORS).

Locations

await client.registerLocations({
  locations: [
    {
      property_id: 'site-a',
      name: 'Upper River',
      latitude: 39.81,
      longitude: -79.36,
      usgs_station_id: '03081000'
    }
  ]
});

await client.updateLocation({
  propertyId: 'site-a',
  updates: { name: 'Upper River (updated)' }
});

await client.deleteLocation({ propertyId: 'site-a' });

registerLocations: on success (200) check results, successCount, failureCount; some rows can fail while others succeed. On total batch failure you may get 400 with the same results shape instead of thrown errors—see runtime behavior on your baseUrl.

Other methods throw Error on non-OK responses when no batch body applies.

Reuse

Create one createClient({ apiKey, baseUrl? }) per key/environment and reuse it (thin wrapper around fetch).

export const client = createClient({
  apiKey: process.env.MY_WIDGET_API_KEY_ID!
});