@verifyhash/uv-index 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

@@ -11,6 +11,16 @@ a rough **burn-time** for fair skin.
 Everything runs locally with the Node standard library. No network calls, no npm
 dependencies, no API keys.
 
+## Install
+
+```bash
+npm install @verifyhash/uv-index
+```
+
+Published as [`@verifyhash/uv-index`](https://www.npmjs.com/package/@verifyhash/uv-index);
+source lives in the [verifyhash/libs](https://github.com/verifyhash/libs) monorepo.
+Zero runtime dependencies — you can also vendor the folder directly.
+
 ## Who it's for
 
 Developers building **sun-safety**, **weather**, or **outdoor-planning** features
@@ -59,7 +69,7 @@ console.log(r);
 this is an instantaneous estimate, not a daily one). To model a specific local
 clock time, convert it to UTC first.
 
-### Other exports
+## API — all exports
 
 ```js
 const {
@@ -67,7 +77,11 @@ const {
   categoryFor,     // (uvi) -> { category, min, max }  — WHO band for a UVI value
   burnTimeMinutes, // (uvi, skinType='II') -> minutes to one MED, or null at UVI 0
   solarElevation,  // (lat, lon, Date) -> sun elevation in degrees (vendored math)
-} = require('./uv-index');
+  MED_BY_SKIN_TYPE,// { I: 200, ..., VI: 1000 } — minimal erythemal dose (J/m²)
+                   // per Fitzpatrick skin type, the table burnTimeMinutes uses
+  REF_OZONE_DU,    // 300 — the reference total-column ozone (Dobson Units)
+                   // assumed when you don't pass ozoneDU
+} = require('@verifyhash/uv-index');
 ```
 
 ## How the number is built

package/index.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Type declarations for @verifyhash/uv-index — zero-dependency, network-free
+ * CLEAR-SKY UV-index estimator.
+ *
+ * It is a clear-sky MODEL: no clouds, no aerosols, no albedo boost; the ozone
+ * and elevation terms are simple approximations. Treat the number as a
+ * clear-sky ceiling, not a measurement. All functions are pure and throw
+ * TypeError on invalid input.
+ */
+
+/** Fitzpatrick skin type, I (very fair, always burns) … VI (deeply pigmented). */
+export type SkinType = 'I' | 'II' | 'III' | 'IV' | 'V' | 'VI';
+
+/** WHO/WMO UV exposure category name. */
+export type UVCategoryName =
+  | 'Low'
+  | 'Moderate'
+  | 'High'
+  | 'Very High'
+  | 'Extreme';
+
+/** A WHO/WMO exposure band: its name and its (rounded-UVI) bounds. */
+export interface UVCategoryBand {
+  /** 'Low' | 'Moderate' | 'High' | 'Very High' | 'Extreme'. */
+  category: UVCategoryName;
+  /** Lower bound of the band (rounded UVI), inclusive. */
+  min: number;
+  /** Upper bound of the band (rounded UVI), inclusive — null for the open-ended 'Extreme' band (11+). */
+  max: number | null;
+}
+
+/** Options for estimateUVIndex(). */
+export interface EstimateUVIndexOptions {
+  /** Latitude in degrees, + North, within [-90, 90]. */
+  lat: number;
+  /** Longitude in degrees, + East, within [-180, 180]. */
+  lon: number;
+  /** A full JS Date instant (UTC-based) — date AND time both matter. */
+  date: Date;
+  /** Total-column ozone in Dobson Units (> 0). Default 300. */
+  ozoneDU?: number;
+  /** Site elevation above sea level in metres (>= 0). Default 0. */
+  elevationM?: number;
+  /** Fitzpatrick skin type used for the burn-time guidance. Default 'II'. */
+  skinType?: SkinType;
+}
+
+/** Result of estimateUVIndex(). */
+export interface UVIndexEstimate {
+  /** Clear-sky erythemal UV index (unrounded, >= 0). */
+  uvi: number;
+  /** UVI rounded to the nearest whole number, as UVI is reported. */
+  uviRounded: number;
+  /** WHO exposure category for the estimated UVI. */
+  category: UVCategoryName;
+  /** Solar elevation above the horizon in degrees (negative when the sun is down). */
+  solarElevationDeg: number;
+  /** True when solar elevation > 0°. */
+  sunAboveHorizon: boolean;
+  /** Approximate minutes to one Minimal Erythemal Dose, or null when UVI is 0. */
+  burnTimeMinutes: number | null;
+  /** Echo of the resolved inputs (with defaults applied). */
+  inputs: {
+    lat: number;
+    lon: number;
+    ozoneDU: number;
+    elevationM: number;
+    skinType: SkinType;
+  };
+}
+
+/**
+ * Estimate the CLEAR-SKY UV index and derived guidance for a place and moment.
+ * Throws TypeError on a missing/invalid options object, invalid date,
+ * non-positive ozoneDU, or negative elevationM; lat/lon are validated by the
+ * vendored solar geometry.
+ */
+export function estimateUVIndex(opts: EstimateUVIndexOptions): UVIndexEstimate;
+
+/**
+ * Map a UV index to its WHO/WMO exposure category. Categorisation uses the
+ * value ROUNDED to the nearest whole number, exactly as UVI is reported:
+ * 0–2 Low · 3–5 Moderate · 6–7 High · 8–10 Very High · 11+ Extreme.
+ * Throws TypeError unless uvi is a finite number >= 0.
+ */
+export function categoryFor(uvi: number): UVCategoryBand;
+
+/**
+ * Approximate minutes of clear-sky exposure to one Minimal Erythemal Dose
+ * (visible sunburn onset) for a Fitzpatrick skin type (default 'II').
+ * Returns null when uvi is 0 (no meaningful burn risk). A physical
+ * order-of-magnitude figure, NOT medical advice.
+ */
+export function burnTimeMinutes(uvi: number, skinType?: SkinType): number | null;
+
+/**
+ * Solar elevation above the horizon in degrees for a lat/lon and UTC instant
+ * (vendored NOAA solar-position geometry; validates lat/lon and throws on
+ * out-of-range values).
+ */
+export function solarElevation(lat: number, lon: number, date: Date): number;
+
+/**
+ * Minimal Erythemal Dose (J/m² of erythemally-weighted UV) by Fitzpatrick
+ * skin type — exposed for advanced use / testing.
+ */
+export const MED_BY_SKIN_TYPE: Record<SkinType, number>;
+
+/** Reference total-column ozone (Dobson Units) the base coefficient is tuned to (300). */
+export const REF_OZONE_DU: number;

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@verifyhash/uv-index",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Zero-dependency, network-free clear-sky UV-index estimator: solar-elevation-driven UVI, WHO exposure category, and burn-time guidance from lat/lon/date/time (+ optional ozone and elevation).",
   "main": "index.js",
+  "types": "index.d.ts",
   "type": "commonjs",
   "scripts": {
     "test": "node test/index.test.js"
@@ -25,7 +26,8 @@
     "index.js",
     "lib/solar.js",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "index.d.ts"
   ],
   "publishConfig": {
     "access": "public"