@verifyhash/wbgt-heat-stress 0.1.0 → 0.1.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 <OWNER-NAME PLACEHOLDER>
+Copyright (c) 2026 verifyhash
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,12 +1,5 @@
 # wbgt-heat-stress
 
-<!-- publish-prep -->
-> **TODO (owner): pick the final npm name/scope before publishing.**
-> The npm package name is **not** finalized. `package.json` keeps the working
-> slug `wbgt-heat-stress` as a placeholder — replace it (and the install line
-> below) with the real published name/scope before any `npm publish`.
-> Graduation to npm is a **needs-human** decision, not something this project does.
-
 A tiny, **zero-dependency** Node library for the three most-used heat-stress
 indices, each returned with a plain-language **risk category**:
 
@@ -35,11 +28,15 @@ math.
 
 ## Install / use
 
-Zero dependencies — vendor the folder or (after the owner finalizes the name)
-`npm install <final-name>`.
+```bash
+npm install @verifyhash/wbgt-heat-stress
+```
+
+Zero runtime dependencies — you can also vendor the folder directly. Source
+lives in the [verifyhash/libs](https://github.com/verifyhash/libs) monorepo.
 
 ```js
-const { heatIndex, humidex, wbgt, wbgtFlag } = require('wbgt-heat-stress');
+const { heatIndex, humidex, wbgt, wbgtFlag } = require('@verifyhash/wbgt-heat-stress');
 
 heatIndex(32.22, 70);
 // { heatIndexF: 105.9, heatIndexC: 41.1, risk: 'danger' }
@@ -56,6 +53,25 @@ wbgt(30, 50, { solarWm2: 900, windMs: 1.5 });
 wbgtFlag(31.5); // 'red'  — band a WBGT you measured elsewhere
 ```
 
+## API
+
+All six exports:
+
+- `heatIndex(tempC, relHumidityPct)` → `{ heatIndexF, heatIndexC, risk }` —
+  NWS Rothfusz heat index (see formulas below).
+- `humidex(tempC, dewPointC)` → `{ humidex, risk }` — Environment Canada humidex.
+- `wbgt(tempC, relHumidityPct, opts?)` → `{ wbgtC, flag, mode }` — approximate
+  WBGT; pass `{ solarWm2, windMs }` for the outdoor estimate.
+- `wbgtFlag(wbgtC)` → `'white' | 'green' | 'yellow' | 'red' | 'black'` — band a
+  WBGT value you measured or computed elsewhere (cut-points in the table below).
+- `heatIndexRisk(hiF)` → the NWS band for a heat index **in °F**:
+  `'none'` (<80), `'caution'` (80–90), `'extreme caution'` (90–103),
+  `'danger'` (103–124), `'extreme danger'` (≥124). Used internally by
+  `heatIndex`; exported so you can band a value from another source.
+- `humidexRisk(h)` → the Environment Canada band for a humidex value:
+  `'none'` (<30), `'some discomfort'` (30–39), `'great discomfort'` (40–45),
+  `'dangerous'` (≥46).
+
 ## Running the tests
 
 One command, no framework, no dependencies:
@@ -159,4 +175,4 @@ from a real sensor.
 
 ## License
 
-MIT — see `LICENSE`. (Copyright holder is a placeholder pending owner sign-off.)
+MIT — see `LICENSE`.

package/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Type declarations for @verifyhash/wbgt-heat-stress — zero-dependency
+ * heat-stress indices: NWS heat index, Environment Canada humidex, and a
+ * Wet-Bulb Globe Temperature (WBGT) APPROXIMATION with risk flags.
+ *
+ * All functions are pure; they throw TypeError on non-finite numeric inputs
+ * and RangeError on out-of-range values (e.g. RH outside [0, 100]).
+ */
+
+/** NWS heat-index caution band. */
+export type HeatIndexRisk =
+  | 'none'
+  | 'caution'
+  | 'extreme caution'
+  | 'danger'
+  | 'extreme danger';
+
+/** Environment Canada humidex comfort band. */
+export type HumidexRisk =
+  | 'none'
+  | 'some discomfort'
+  | 'great discomfort'
+  | 'dangerous';
+
+/** WBGT flag colour (US military / ACSM bands), white (low) … black (highest risk). */
+export type WbgtFlag = 'white' | 'green' | 'yellow' | 'red' | 'black';
+
+/** Result of heatIndex(). */
+export interface HeatIndexResult {
+  /** Apparent temperature, °C. */
+  heatIndexC: number;
+  /** Apparent temperature, °F (the regression's native unit). */
+  heatIndexF: number;
+  /** NWS caution band for the °F value. */
+  risk: HeatIndexRisk;
+}
+
+/** Result of humidex(). */
+export interface HumidexResult {
+  /** Humidex value (unitless comfort index on the Celsius scale), clamped to >= tempC. */
+  humidex: number;
+  /** Environment Canada comfort band. */
+  risk: HumidexRisk;
+}
+
+/** Options for wbgt() — providing solarWm2 switches to outdoor mode. */
+export interface WbgtOptions {
+  /** Global solar irradiance, W/m² (>= 0). Enables the outdoor solar-load heuristic. */
+  solarWm2?: number | null;
+  /** 10 m wind speed, m/s (>= 0). Only used in outdoor mode. Default 1. */
+  windMs?: number | null;
+}
+
+/** Result of wbgt(). */
+export interface WbgtResult {
+  /** Approximate Wet-Bulb Globe Temperature, °C. */
+  wbgtC: number;
+  /** Flag-colour band for the WBGT value. */
+  flag: WbgtFlag;
+  /** 'outdoor' when opts.solarWm2 was given, else 'indoor'. */
+  mode: 'indoor' | 'outdoor';
+}
+
+/**
+ * Apparent ("feels-like") temperature from air temperature (°C) and relative
+ * humidity (%, 0..100), following the US National Weather Service (Rothfusz
+ * regression with the documented low-temperature fallback and low/high
+ * humidity corrections; accurate to about ±1.3 °F).
+ */
+export function heatIndex(tempC: number, relHumidityPct: number): HeatIndexResult;
+
+/**
+ * Canadian humidex from air temperature and dew point (both °C).
+ * Throws RangeError when dewpointC exceeds tempC. Clamped so it is never
+ * reported below the air temperature.
+ */
+export function humidex(tempC: number, dewpointC: number): HumidexResult;
+
+/**
+ * Approximate Wet-Bulb Globe Temperature from air temperature (°C) and
+ * relative humidity (%, 0..100). Indoor/shaded by default (Australian BoM
+ * simplified regression); passing opts.solarWm2 adds a coarse, capped solar
+ * load term (a heuristic, NOT a validated outdoor model — measure with a
+ * globe sensor for real occupational decisions in the sun).
+ */
+export function wbgt(
+  tempC: number,
+  relHumidityPct: number,
+  opts?: WbgtOptions
+): WbgtResult;
+
+/**
+ * Classify a WBGT (°C) into the US military / ACSM flag-colour band:
+ * white < 27.8 °C · green 27.8–29.3 · yellow 29.4–31.0 · red 31.1–32.1 ·
+ * black >= 32.2 °C.
+ */
+export function wbgtFlag(wbgtC: number): WbgtFlag;
+
+/** Low-level: NWS caution band for a heat index given in °F (exported for testing / advanced use). */
+export function heatIndexRisk(hiF: number): HeatIndexRisk;
+
+/** Low-level: Environment Canada comfort band for a humidex value (exported for testing / advanced use). */
+export function humidexRisk(h: number): HumidexRisk;

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@verifyhash/wbgt-heat-stress",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Zero-dependency heat-stress indices: NWS heat index, Environment Canada humidex, and a Wet-Bulb Globe Temperature (WBGT) approximation with risk flags.",
   "main": "index.js",
+  "types": "index.d.ts",
   "type": "commonjs",
   "scripts": {
     "test": "node test/index.test.js"
@@ -23,7 +24,8 @@
   "license": "MIT",
   "files": [
     "index.js",
-    "README.md"
+    "README.md",
+    "index.d.ts"
   ],
   "publishConfig": {
     "access": "public"