@verifyhash/solar-calc 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 @@
 # solar-calc
 
-<!-- publish-prep -->
-> **TODO (owner): pick the final npm name/scope before publishing.**
-> The npm package name is **not** finalized by this project. Convention used here:
-> `package.json` keeps the working slug `solar-calc` as a placeholder — replace it
-> (and the `npm install` line below) with the real published name/scope before
-> running `npm publish`.
-
 A tiny, **zero-dependency** Node library for solar geometry: sunrise, sunset,
 solar noon, day length, the Sun's elevation and azimuth at any instant, plus
 civil-twilight and golden-hour boundaries — for any latitude, longitude, and
@@ -149,6 +142,15 @@ golden hour runs **`goldenHourEveningStart` → sunset**.
 |----------|---------|
 | `localClockMinutes(instant, tz?)` | minutes-after-midnight `[0, 1440)` on the local clock for a returned event instant, or `null` if passed `null` |
 
+### Internals exposed for testing
+
+- `_sunPosition(t)` — the raw NOAA kernel behind everything above. Takes the
+  Julian **century** `t` (centuries since J2000.0) and returns
+  `{ declination, eqTime }`: the Sun's declination in degrees and the equation
+  of time in minutes (how far a sundial runs ahead of a mean clock). Exported
+  with the underscore prefix so the test suite can pin it against NOAA
+  reference values — treat it as internal; its shape is not covered by semver.
+
 ## Running the tests
 
 One command, no dependencies:
@@ -170,15 +172,12 @@ MIT.
 
 ## Install
 
-> Placeholder name: the `solar-calc` below is the working slug, not a finalized
-> npm name — see the owner TODO near the top of this README.
-
 ```sh
-npm install solar-calc
+npm install @verifyhash/solar-calc
 ```
 
 ```js
-const solar = require('solar-calc');
+const solar = require('@verifyhash/solar-calc');
 
 const lat = 40.7128, lon = -74.006, tz = -4; // New York City, EDT
 const date = { year: 2021, month: 6, day: 21 };

package/index.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Type declarations for @verifyhash/solar-calc — zero-dependency solar
+ * position & daylight math (NOAA algorithm).
+ *
+ * Conventions: lat in degrees (+N), lon in degrees (+E), tz = local clock's
+ * offset from UTC in hours (default 0). Daily event functions return the true
+ * UTC instant of the event as a Date, or null when the event does not occur
+ * that day (polar night / midnight sun).
+ */
+
+/**
+ * Date input for the daily functions: either a JS Date (only its calendar
+ * date is used, read in UTC) or a plain { year, month, day } object with a
+ * 1-based month (1 = January).
+ */
+export type DateInput = Date | { year: number; month: number; day: number };
+
+/**
+ * Sun declination in degrees for the given date (evaluated at local solar
+ * noon). Positive toward the North.
+ */
+export function declination(dateInput: DateInput, tz?: number): number;
+
+/**
+ * Equation of time in minutes (apparent minus mean solar time) for the given
+ * date. Roughly −14 … +16 minutes across a year.
+ */
+export function equationOfTime(dateInput: DateInput, tz?: number): number;
+
+/** Solar noon as a UTC instant. Always defined. */
+export function solarNoon(
+  lat: number,
+  lon: number,
+  dateInput: DateInput,
+  tz?: number
+): Date;
+
+/** Sunrise (upper limb clearing the horizon) as a UTC instant, or null. */
+export function sunrise(
+  lat: number,
+  lon: number,
+  dateInput: DateInput,
+  tz?: number
+): Date | null;
+
+/** Sunset (upper limb touching the horizon) as a UTC instant, or null. */
+export function sunset(
+  lat: number,
+  lon: number,
+  dateInput: DateInput,
+  tz?: number
+): Date | null;
+
+/**
+ * Length of the day (sunrise → sunset) in minutes. Normal day: (0, 1440);
+ * polar night: 0; midnight sun: 1440.
+ */
+export function dayLengthMinutes(
+  lat: number,
+  lon: number,
+  dateInput: DateInput,
+  tz?: number
+): number;
+
+/** Start of civil dawn (Sun 6° below horizon, rising) as a UTC instant, or null. */
+export function civilDawn(
+  lat: number,
+  lon: number,
+  dateInput: DateInput,
+  tz?: number
+): Date | null;
+
+/** End of civil dusk (Sun 6° below horizon, setting) as a UTC instant, or null. */
+export function civilDusk(
+  lat: number,
+  lon: number,
+  dateInput: DateInput,
+  tz?: number
+): Date | null;
+
+/** End of the morning golden hour (Sun reaching 6° elevation), or null. */
+export function goldenHourMorningEnd(
+  lat: number,
+  lon: number,
+  dateInput: DateInput,
+  tz?: number
+): Date | null;
+
+/** Start of the evening golden hour (Sun descending to 6° elevation), or null. */
+export function goldenHourEveningStart(
+  lat: number,
+  lon: number,
+  dateInput: DateInput,
+  tz?: number
+): Date | null;
+
+/**
+ * Geometric solar elevation in degrees above the horizon for a full UTC Date
+ * instant (no tz needed — the instant pins the moment). No refraction added.
+ */
+export function solarElevation(lat: number, lon: number, date: Date): number;
+
+/**
+ * Solar azimuth in degrees, clockwise from true North (0 = N, 90 = E,
+ * 180 = S, 270 = W), for a full UTC Date instant.
+ */
+export function solarAzimuth(lat: number, lon: number, date: Date): number;
+
+/**
+ * Convert a UTC instant (e.g. from sunrise()) to minutes-after-midnight on
+ * the LOCAL clock for the given tz offset (hours). Returns a number in
+ * [0, 1440), or null when passed null/undefined.
+ */
+export function localClockMinutes(
+  instant: Date | null | undefined,
+  tz?: number
+): number | null;
+
+/**
+ * Internal NOAA solve exposed for advanced use / testing: Sun declination
+ * (degrees) and equation of time (minutes) for Julian centuries t since
+ * J2000.0.
+ */
+export function _sunPosition(t: number): { declination: number; eqTime: number };

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@verifyhash/solar-calc",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Zero-dependency solar position & daylight math (NOAA algorithm): sunrise, sunset, solar noon, day length, elevation, azimuth, civil twilight, and golden hour for any latitude/longitude/date.",
   "main": "index.js",
+  "types": "index.d.ts",
   "type": "commonjs",
   "scripts": {
     "test": "node test/solar.test.js"
@@ -24,7 +25,8 @@
   "license": "MIT",
   "files": [
     "index.js",
-    "README.md"
+    "README.md",
+    "index.d.ts"
   ],
   "publishConfig": {
     "access": "public"