mihrab-methods 0.0.0-stage → 1.0.0

package/dist/esm/core/api.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The library's calls. Each works for whichever authorities are loaded —
+ * `mihrab-methods` loads all five, `mihrab-methods/<authority>` one.
+ */
+import { type ComputeOptions } from './compute.js';
+import { type Authority, type Certification, type CivilDate, type DayTimes, type MethodInfo, type Place, type TimesOptions } from './types.js';
+/**
+ * Certified: every check of the authority's tables has every time on the
+ * printed minute (and checked something). The flag alone is not trusted.
+ */
+export declare function isCertified(authority: Authority): boolean;
+/** The authority's record from certification.json, or null. */
+export declare function certificationOf(authority: Authority): Certification | null;
+/** The span of dates the method was checked over (and so is certified for), or null. */
+export declare function certifiedSpan(authority: Authority): {
+    from: string;
+    to: string;
+} | null;
+/** The authority's places, each at the point its method is computed at. */
+export declare function placesOf(authority: Authority): Place[];
+/** The authorities this build has loaded. */
+export declare function loadedAuthorityIds(): Authority[];
+/** A place by its stable id (`<authority>:<key>`), among the loaded authorities. */
+export declare function placeById(id: string): Place | null;
+/** Great-circle distance, km. */
+export declare function distanceKm(lat1: number, lon1: number, lat2: number, lon2: number): number;
+export type NearestPlace = {
+    place: Place;
+    distanceKm: number;
+};
+/**
+ * The authority's place nearest a point — how an app finds the table for a
+ * location. `maxKm` (default: no limit) returns null beyond that distance.
+ * Türkiye's districts and Diyanet's worldwide places are both 'diyanet'.
+ */
+export declare function nearestPlace(authority: Authority, lat: number, lon: number, opts?: {
+    maxKm?: number;
+}): NearestPlace | null;
+/**
+ * The place's prayer times on a civil date, as the authority prints them:
+ * each prayer's exact moment and its wall-clock minute on the table's clock.
+ *
+ * Inside the dates the method was certified over, `status` is 'certified':
+ * the authority's own printed minute. Outside them it is 'method-only': the
+ * method alone, which is on the printed minute all but rarely and never a
+ * minute further — the honest answer for a date the authority has not
+ * published yet. `{ strict: true }` throws `UncertifiedMethodError` there
+ * instead. A method not certified at all throws either way: it is not for
+ * showing anyone their prayer times (`candidateTimes` runs it regardless).
+ */
+export declare function timesFor(place: Place, date: CivilDate, opts?: TimesOptions): DayTimes;
+/** `timesFor` for every date from `from` to `to`, both inclusive — a month's timetable, a year's. */
+export declare function timesForRange(place: Place, from: CivilDate, to: CivilDate, opts?: TimesOptions): DayTimes[];
+/**
+ * The method as it stands, certified or not, with or without its correction
+ * list (`corrections: false`): for research and for checking the method
+ * against the tables. `status` says what it would be served as.
+ */
+export declare function candidateTimes(place: Place, date: CivilDate, opts?: TimesOptions & ComputeOptions): DayTimes;
+/** What the method is: its parameters, revision, certification, correction list and sources. */
+export declare function methodInfo(authority: Authority): MethodInfo;

package/dist/esm/core/api.js

@@ -0,0 +1,162 @@
+/**
+ * The library's calls. Each works for whichever authorities are loaded —
+ * `mihrab-methods` loads all five, `mihrab-methods/<authority>` one.
+ */
+import { candidateInstants } from './compute.js';
+import { parseCivilDate, nextDay } from './civilDate.js';
+import { printedAt, tableClockAt } from './clock.js';
+import { authorityData, isLoaded, loadedAuthorities } from './registry.js';
+import { PRAYER_KEYS, UncertifiedMethodError, } from './types.js';
+/**
+ * Certified: every check of the authority's tables has every time on the
+ * printed minute (and checked something). The flag alone is not trusted.
+ */
+export function isCertified(authority) {
+    const c = certificationOf(authority);
+    return !!c && c.certified && c.checks.length > 0 && c.checks.every(k => k.times > 0 && k.off === 0);
+}
+/** The authority's record from certification.json, or null. */
+export function certificationOf(authority) {
+    return authorityData(authority).certification;
+}
+/** The span of dates the method was checked over (and so is certified for), or null. */
+export function certifiedSpan(authority) {
+    if (!isCertified(authority))
+        return null;
+    const checks = certificationOf(authority).checks;
+    return { from: checks.map(c => c.from).sort()[0], to: checks.map(c => c.to).sort().at(-1) };
+}
+/** The authority's places, each at the point its method is computed at. */
+export function placesOf(authority) {
+    return authorityData(authority).places;
+}
+/** The authorities this build has loaded. */
+export function loadedAuthorityIds() {
+    return loadedAuthorities();
+}
+/** A place by its stable id (`<authority>:<key>`), among the loaded authorities. */
+export function placeById(id) {
+    const i = id.indexOf(':');
+    if (i < 0)
+        return null;
+    const authority = id.slice(0, i);
+    if (!isLoaded(authority))
+        return null;
+    return byId(authority).get(id) ?? null;
+}
+const idIndexes = new Map();
+function byId(authority) {
+    let m = idIndexes.get(authority);
+    if (!m)
+        idIndexes.set(authority, (m = new Map(placesOf(authority).map(p => [p.id, p]))));
+    return m;
+}
+const RAD = Math.PI / 180;
+/** Great-circle distance, km. */
+export function distanceKm(lat1, lon1, lat2, lon2) {
+    const dLat = (lat2 - lat1) * RAD;
+    const dLon = (lon2 - lon1) * RAD;
+    const a = Math.sin(dLat / 2) ** 2 + Math.cos(lat1 * RAD) * Math.cos(lat2 * RAD) * Math.sin(dLon / 2) ** 2;
+    return 2 * 6371.0088 * Math.asin(Math.min(1, Math.sqrt(a)));
+}
+/**
+ * The authority's place nearest a point — how an app finds the table for a
+ * location. `maxKm` (default: no limit) returns null beyond that distance.
+ * Türkiye's districts and Diyanet's worldwide places are both 'diyanet'.
+ */
+export function nearestPlace(authority, lat, lon, opts = {}) {
+    if (!Number.isFinite(lat) || !Number.isFinite(lon))
+        return null;
+    let best = null;
+    for (const place of placesOf(authority)) {
+        const d = distanceKm(lat, lon, place.lat, place.lon);
+        if (!best || d < best.distanceKm)
+            best = { place, distanceKm: d };
+    }
+    if (best && opts.maxKm !== undefined && best.distanceKm > opts.maxKm)
+        return null;
+    return best;
+}
+function dayTimes(place, d, instants, status) {
+    const data = authorityData(place.authority);
+    const span = certifiedSpan(place.authority);
+    const clock = tableClockAt(place, d.year, d.month0, d.day);
+    let times = null;
+    if (instants) {
+        times = {};
+        for (const k of PRAYER_KEYS)
+            times[k] = { instant: instants[k], printed: printedAt(instants[k], clock.offsetMinutes) };
+    }
+    return {
+        authority: place.authority,
+        placeId: place.id,
+        date: d.iso,
+        status,
+        certifiedFrom: span?.from ?? null,
+        certifiedUntil: span?.to ?? null,
+        revision: data.revision,
+        clock,
+        times,
+    };
+}
+function statusFor(authority, iso) {
+    const span = certifiedSpan(authority);
+    if (!span)
+        return 'uncertified';
+    return iso < span.from || iso > span.to ? 'method-only' : 'certified';
+}
+/**
+ * The place's prayer times on a civil date, as the authority prints them:
+ * each prayer's exact moment and its wall-clock minute on the table's clock.
+ *
+ * Inside the dates the method was certified over, `status` is 'certified':
+ * the authority's own printed minute. Outside them it is 'method-only': the
+ * method alone, which is on the printed minute all but rarely and never a
+ * minute further — the honest answer for a date the authority has not
+ * published yet. `{ strict: true }` throws `UncertifiedMethodError` there
+ * instead. A method not certified at all throws either way: it is not for
+ * showing anyone their prayer times (`candidateTimes` runs it regardless).
+ */
+export function timesFor(place, date, opts = {}) {
+    if (!isCertified(place.authority))
+        throw new UncertifiedMethodError(place.authority);
+    const d = parseCivilDate(date);
+    const status = statusFor(place.authority, d.iso);
+    if (status === 'method-only' && opts.strict)
+        throw new UncertifiedMethodError(place.authority, d.iso);
+    return dayTimes(place, d, candidateInstants(place, d.year, d.month0, d.day, opts.asrShadow ?? 1), status);
+}
+/** `timesFor` for every date from `from` to `to`, both inclusive — a month's timetable, a year's. */
+export function timesForRange(place, from, to, opts = {}) {
+    const a = parseCivilDate(from);
+    const b = parseCivilDate(to);
+    if (a.iso > b.iso)
+        throw new RangeError(`The range runs backwards: ${a.iso} to ${b.iso}.`);
+    const out = [];
+    for (let d = a; d.iso <= b.iso; d = nextDay(d))
+        out.push(timesFor(place, d.iso, opts));
+    return out;
+}
+/**
+ * The method as it stands, certified or not, with or without its correction
+ * list (`corrections: false`): for research and for checking the method
+ * against the tables. `status` says what it would be served as.
+ */
+export function candidateTimes(place, date, opts = {}) {
+    const d = parseCivilDate(date);
+    return dayTimes(place, d, candidateInstants(place, d.year, d.month0, d.day, opts.asrShadow ?? 1, { corrections: opts.corrections }), statusFor(place.authority, d.iso));
+}
+/** What the method is: its parameters, revision, certification, correction list and sources. */
+export function methodInfo(authority) {
+    const data = authorityData(authority);
+    const cov = data.corrections.coverage();
+    return {
+        authority,
+        ...data.description,
+        revision: data.revision,
+        certified: isCertified(authority),
+        certification: data.certification,
+        corrections: { from: cov.from, to: cov.to, entries: data.corrections.entries() },
+        places: data.places.length,
+    };
+}

package/dist/esm/core/civilDate.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Civil dates as the library takes them: 'YYYY-MM-DD', or { year, month,
+ * day } with January = 1. The methods themselves count months from 0, as
+ * JavaScript's Date does; that habit stops at this file.
+ */
+import type { CivilDate } from './types.js';
+export type Ymd = {
+    year: number;
+    month0: number;
+    day: number;
+    iso: string;
+};
+export declare function parseCivilDate(date: CivilDate): Ymd;
+/** 'YYYY-MM-DD' from a year, a 0-based month and a day. */
+export declare function isoOf(year: number, month0: number, day: number): string;
+/** The day after, as a civil date (UTC arithmetic: no zone, no summer time). */
+export declare function nextDay(d: Ymd): Ymd;

package/dist/esm/core/civilDate.js

@@ -0,0 +1,36 @@
+const ISO = /^(\d{4})-(\d{2})-(\d{2})$/;
+export function parseCivilDate(date) {
+    let year, month, day;
+    if (typeof date === 'string') {
+        const m = ISO.exec(date);
+        if (!m)
+            throw new TypeError(`Not a date: ${JSON.stringify(date)} — expected 'YYYY-MM-DD' or { year, month, day }.`);
+        [year, month, day] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    }
+    else if (date && typeof date === 'object' && typeof date.year === 'number' && typeof date.month === 'number' && typeof date.day === 'number') {
+        ({ year, month, day } = date);
+    }
+    else {
+        throw new TypeError(typeof date === 'number'
+            ? 'timesFor(place, year, month, day) is no longer the call: pass one date, as \'YYYY-MM-DD\' or { year, month, day } with January = 1.'
+            : `Not a date: ${JSON.stringify(date)} — expected 'YYYY-MM-DD' or { year, month, day }.`);
+    }
+    if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(day) || month < 1 || month > 12 || day < 1 || day > 31) {
+        throw new RangeError(`Not a calendar date: ${isoOf(year, month - 1, day)} (months run 1–12).`);
+    }
+    // 31 April, 30 February: a Date would roll these over without a word.
+    const probe = new Date(Date.UTC(year, month - 1, day));
+    if (probe.getUTCMonth() !== month - 1 || probe.getUTCDate() !== day) {
+        throw new RangeError(`Not a calendar date: ${isoOf(year, month - 1, day)}.`);
+    }
+    return { year, month0: month - 1, day, iso: isoOf(year, month - 1, day) };
+}
+/** 'YYYY-MM-DD' from a year, a 0-based month and a day. */
+export function isoOf(year, month0, day) {
+    return `${String(year).padStart(4, '0')}-${String(month0 + 1).padStart(2, '0')}-${String(day).padStart(2, '0')}`;
+}
+/** The day after, as a civil date (UTC arithmetic: no zone, no summer time). */
+export function nextDay(d) {
+    const n = new Date(Date.UTC(d.year, d.month0, d.day + 1));
+    return { year: n.getUTCFullYear(), month0: n.getUTCMonth(), day: n.getUTCDate(), iso: isoOf(n.getUTCFullYear(), n.getUTCMonth(), n.getUTCDate()) };
+}

package/dist/esm/core/clock.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The clock a table prints a day in: the place's zone as kept at noon, or
+ * the table's own clock where it keeps one no zone does (`Place.clock`). A
+ * table prints the whole day in the clock kept at noon, so on the morning
+ * the clocks go forward a Fajr before the change is printed in the new time.
+ */
+import type { Place, TableClock } from './types.js';
+/** Minutes east of UTC that a zone keeps at noon UTC of a date (month 0-based). */
+export declare function clockOffsetAt(tz: string, year: number, month: number, day: number): number;
+/** The clock a place's table prints a date in: its own (`Place.clock`) where it has one, else its zone's. Month 0-based. */
+export declare function placeClockAt(place: Place, year: number, month: number, day: number): number;
+export declare function offsetLabel(offsetMinutes: number): string;
+export declare function tableClockAt(place: Place, year: number, month: number, day: number): TableClock;
+/** 'HH:MM' of an instant on a clock, as a table prints it. */
+export declare function printedAt(instant: Date, offsetMinutes: number): string;

package/dist/esm/core/clock.js

@@ -0,0 +1,39 @@
+const offsetFormats = new Map();
+/** Minutes east of UTC that a zone keeps at noon UTC of a date (month 0-based). */
+export function clockOffsetAt(tz, year, month, day) {
+    let f = offsetFormats.get(tz);
+    if (!f)
+        offsetFormats.set(tz, (f = new Intl.DateTimeFormat('en-US', { timeZone: tz, timeZoneName: 'longOffset' })));
+    const z = f.formatToParts(new Date(Date.UTC(year, month, day, 12))).find(x => x.type === 'timeZoneName').value;
+    const m = /GMT([+-])(\d\d):?(\d\d)?/.exec(z);
+    return m ? (m[1] === '-' ? -1 : 1) * (Number(m[2]) * 60 + Number(m[3] ?? 0)) : 0;
+}
+/** The clock a place's table prints a date in: its own (`Place.clock`) where it has one, else its zone's. Month 0-based. */
+export function placeClockAt(place, year, month, day) {
+    if (place.clock) {
+        const date = `${year}-${String(month + 1).padStart(2, '0')}-${String(day).padStart(2, '0')}`;
+        let off = place.clock[0][1];
+        for (const [from, o] of place.clock)
+            if (from <= date)
+                off = o;
+        return off;
+    }
+    return clockOffsetAt(place.tz, year, month, day);
+}
+export function offsetLabel(offsetMinutes) {
+    const sign = offsetMinutes < 0 ? '-' : '+';
+    const abs = Math.abs(offsetMinutes);
+    return `UTC${sign}${String(Math.floor(abs / 60)).padStart(2, '0')}:${String(abs % 60).padStart(2, '0')}`;
+}
+export function tableClockAt(place, year, month, day) {
+    const offsetMinutes = placeClockAt(place, year, month, day);
+    return place.clock
+        ? { zone: null, offsetMinutes, label: offsetLabel(offsetMinutes) }
+        : { zone: place.tz, offsetMinutes, label: place.tz };
+}
+/** 'HH:MM' of an instant on a clock, as a table prints it. */
+export function printedAt(instant, offsetMinutes) {
+    const local = Math.floor(instant.getTime() / 60_000) + offsetMinutes;
+    const m = ((local % 1440) + 1440) % 1440;
+    return `${String(Math.floor(m / 60)).padStart(2, '0')}:${String(m % 60).padStart(2, '0')}`;
+}

package/dist/esm/core/compute.d.ts

@@ -0,0 +1,10 @@
+import type { Instants, Place } from './types.js';
+export type ComputeOptions = {
+    corrections?: boolean;
+};
+/**
+ * The method as it stands, certified or not, for a civil date with the
+ * month 0-based. Null where the method gives no times for the day. Not for
+ * showing anyone their prayer times: `timesFor` is.
+ */
+export declare function candidateInstants(place: Place, year: number, month: number, day: number, asrShadow?: 1 | 2, opts?: ComputeOptions): Instants | null;

package/dist/esm/core/compute.js

@@ -0,0 +1,56 @@
+/**
+ * The methods, run for a place and a civil date (month 0-based, as the
+ * methods count): the authority's own formula, then its correction list.
+ * This is the computation `timesFor` and the checks share; the API around
+ * it is in `api.ts`.
+ */
+import { congressTimes } from '../methods/sweden.js';
+import { moroccoTimes } from '../methods/morocco.js';
+import { algeriaTimes } from '../methods/algeria.js';
+import { kemenagTimes } from '../methods/indonesia.js';
+import { authorityData } from './registry.js';
+import { placeClockAt } from './clock.js';
+/**
+ * The method as it stands, certified or not, for a civil date with the
+ * month 0-based. Null where the method gives no times for the day. Not for
+ * showing anyone their prayer times: `timesFor` is.
+ */
+export function candidateInstants(place, year, month, day, asrShadow = 1, opts = {}) {
+    const fix = opts.corrections === false ? null : authorityData(place.authority).corrections;
+    switch (place.authority) {
+        case 'sweden':
+        case 'diyanet': {
+            // The Congress method's own rounding is inside it; its instants land on the minute (rounded, as the app does).
+            const clock = placeClockAt(place, year, month, day);
+            const t = place.prayerPoints ? perPrayer(place, place.prayerPoints, year, month, day, asrShadow) : congressTimes(place.lat, place.lon, year, month, day, asrShadow, place.ishaDeg, clock);
+            // then the correction list: the few times Diyanet's program rounds the other way (the standard Asr only)
+            const c = fix?.correction(place.lat, place.lon, year, month, day);
+            const min = (d, k) => new Date((Math.round(d.getTime() / 60_000) + (k === 'asr' && asrShadow !== 1 ? 0 : (c?.[k] ?? 0))) * 60_000);
+            return { fajr: min(t.fajr, 'fajr'), sunrise: min(t.sunrise, 'sunrise'), dhuhr: min(t.dhuhr, 'dhuhr'), asr: min(t.asr, 'asr'), maghrib: min(t.maghrib, 'maghrib'), isha: min(t.isha, 'isha') };
+        }
+        case 'morocco':
+        case 'algeria':
+        case 'indonesia': {
+            const t = place.authority === 'morocco'
+                ? moroccoTimes(place.lat, place.lon, year, month, day, place.dipDeg ?? 0, asrShadow, place.dipMaghribDeg)
+                : place.authority === 'algeria'
+                    ? algeriaTimes(place.lat, place.lon, year, month, day, asrShadow)
+                    : kemenagTimes(place.lat, place.lon, year, month, day, { highland: place.highland, twilightDip: place.twilightDip, asrShadow, afternoon: place.afternoon });
+            // the correction list: the authority's few times on the other side of a minute (the standard Asr only)
+            const c = !t || !fix ? undefined : fix.correction(place.lat, place.lon, year, month, day);
+            if (!t || !c)
+                return t;
+            const mv = (d, k) => new Date(d.getTime() + (k === 'asr' && asrShadow !== 1 ? 0 : (c[k] ?? 0)) * 60_000);
+            return { fajr: mv(t.fajr, 'fajr'), sunrise: mv(t.sunrise, 'sunrise'), dhuhr: mv(t.dhuhr, 'dhuhr'), asr: mv(t.asr, 'asr'), maghrib: mv(t.maghrib, 'maghrib'), isha: mv(t.isha, 'isha') };
+        }
+    }
+}
+/** Türkiye's districts: each prayer at its own point for the year (the nearest year's beyond the tables). */
+function perPrayer(place, pts, year, month, day, asrShadow) {
+    const years = Object.keys(pts).map(Number).sort((a, b) => a - b);
+    const y = years.reduce((b, v) => (Math.abs(v - year) < Math.abs(b - year) ? v : b), years[0]);
+    const p = pts[String(y)];
+    const clock = placeClockAt(place, year, month, day);
+    const at = (i) => congressTimes(p[i][0], p[i][1], year, month, day, asrShadow, place.ishaDeg, clock);
+    return { fajr: at(0).fajr, sunrise: at(1).sunrise, dhuhr: at(2).dhuhr, asr: at(3).asr, maghrib: at(4).maghrib, isha: at(5).isha };
+}

package/dist/esm/core/correctionList.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A correction list, indexed for lookup: point → date → the minutes to add
+ * to each printed time. Built from the embedded data (or, for the tools,
+ * from a file read into the same shape).
+ */
+import type { CorrectionsFile, PrayerKey } from './types.js';
+export declare const pointKey: (lat: number, lon: number) => string;
+export declare class CorrectionList {
+    private source;
+    private index;
+    constructor(source: CorrectionsFile);
+    private load;
+    /** The minutes to add to the point's printed times on a date (month 0-based), if any. */
+    correction(lat: number, lon: number, year: number, month: number, day: number): Partial<Record<PrayerKey, number>> | undefined;
+    coverage(): {
+        from: string;
+        to: string;
+    };
+    entries(): number;
+    file(): CorrectionsFile;
+    /** Put another list in force (a newer one for the same method revision). */
+    replace(source: CorrectionsFile): void;
+}
+/** A list that does not have the shape of one is refused whole. */
+export declare function isCorrectionsFile(x: unknown): x is CorrectionsFile;

package/dist/esm/core/correctionList.js

@@ -0,0 +1,56 @@
+export const pointKey = (lat, lon) => `${lat.toFixed(3)},${lon.toFixed(3)}`;
+export class CorrectionList {
+    source;
+    index = null;
+    constructor(source) {
+        this.source = source;
+    }
+    load() {
+        if (this.index)
+            return this.index;
+        const index = new Map();
+        for (const [point, list] of Object.entries(this.source.points)) {
+            const byDate = new Map();
+            for (const e of list) {
+                const [date, key, step] = e.split(' ');
+                const c = byDate.get(date) ?? {};
+                c[key] = Number(step);
+                byDate.set(date, c);
+            }
+            index.set(point, byDate);
+        }
+        return (this.index = index);
+    }
+    /** The minutes to add to the point's printed times on a date (month 0-based), if any. */
+    correction(lat, lon, year, month, day) {
+        const date = `${year}-${String(month + 1).padStart(2, '0')}-${String(day).padStart(2, '0')}`;
+        return this.load().get(pointKey(lat, lon))?.get(date);
+    }
+    coverage() {
+        return { from: this.source.from, to: this.source.to };
+    }
+    entries() {
+        return Object.values(this.source.points).reduce((n, e) => n + e.length, 0);
+    }
+    file() {
+        return this.source;
+    }
+    /** Put another list in force (a newer one for the same method revision). */
+    replace(source) {
+        this.source = source;
+        this.index = null;
+    }
+}
+/** A list that does not have the shape of one is refused whole. */
+export function isCorrectionsFile(x) {
+    if (!x || typeof x !== 'object')
+        return false;
+    const c = x;
+    const date = /^\d{4}-\d{2}-\d{2}$/;
+    if (typeof c.from !== 'string' || typeof c.to !== 'string' || !date.test(c.from) || !date.test(c.to) || c.from > c.to)
+        return false;
+    if (!c.points || typeof c.points !== 'object')
+        return false;
+    const entry = /^\d{4}-\d{2}-\d{2} (fajr|sunrise|dhuhr|asr|maghrib|isha) [+-]1$/;
+    return Object.entries(c.points).every(([k, v]) => /^-?\d+\.\d{3},-?\d+\.\d{3}$/.test(k) && Array.isArray(v) && v.every(e => typeof e === 'string' && entry.test(e)));
+}

package/dist/esm/core/fetchLatest.d.ts

@@ -0,0 +1,57 @@
+import type { Authority, CorrectionsFile } from './types.js';
+/** Where the feed lives. A tagged release (`.../v1.2.0/...`) can replace `main` for a pinned address. */
+export declare const DEFAULT_FEED_URL = "https://raw.githubusercontent.com/MihrabHQ/mihrab-methods/main";
+export type FetchOptions = {
+    authority: Authority;
+    /** The revision this build computes; default: the loaded method's. */
+    revision?: number;
+    /** The feed's base URL (default `DEFAULT_FEED_URL`): `<base>/certification.json`, `<base>/data/corrections/<authority>.json`. */
+    baseUrl?: string;
+    /** The fetch to use (default: the global one). */
+    fetch?: typeof fetch;
+    /** SHA-256 of a UTF-8 string as lowercase hex; default: WebCrypto, else node:crypto, else the hash is not checked. */
+    sha256?: (text: string) => Promise<string>;
+    /** Put a newer list in force in this process (default true). */
+    apply?: boolean;
+};
+export type ListSummary = {
+    from: string;
+    to: string;
+    entries: number;
+};
+export type FetchResult = 
+/** The certification names the list this build already has (or an older one). */
+{
+    status: 'current';
+    have: ListSummary;
+    certified: boolean;
+}
+/** A newer list for this revision: its contents, and whether the hash matched (or could not be checked). */
+ | {
+    status: 'updated';
+    list: CorrectionsFile;
+    summary: ListSummary;
+    integrity: 'verified' | 'unchecked';
+    applied: boolean;
+}
+/** The method itself has moved on: its lists no longer fit this build, which should be updated. */
+ | {
+    status: 'method-moved';
+    remoteRevision: number;
+    have: ListSummary;
+}
+/** The authority has published tables the method is not yet certified on: keep the list in force. */
+ | {
+    status: 'uncertified';
+    have: ListSummary;
+}
+/** Something did not add up (a list not matching what the certification names, a bad hash): nothing taken. */
+ | {
+    status: 'rejected';
+    reason: string;
+    have: ListSummary;
+};
+export declare function summarize(list: CorrectionsFile): ListSummary;
+/** Put a list in force for the process — one verified by `fetchLatestCorrections`, or restored from the app's own storage. */
+export declare function applyCorrections(authority: Authority, list: CorrectionsFile, revision: number): boolean;
+export declare function fetchLatestCorrections(opts: FetchOptions): Promise<FetchResult>;

package/dist/esm/core/fetchLatest.js

@@ -0,0 +1,98 @@
+/**
+ * Keeping an app current without a release: the repository publishes
+ * `certification.json` and the correction lists it certifies, and an app
+ * that computes a method's revision can take any newer list certified for
+ * that revision. This is the check done right — the revision, the list's
+ * identity, and its SHA-256 as the certification names it.
+ */
+import { authorityData } from './registry.js';
+import { isCorrectionsFile } from './correctionList.js';
+/** Where the feed lives. A tagged release (`.../v1.2.0/...`) can replace `main` for a pinned address. */
+export const DEFAULT_FEED_URL = 'https://raw.githubusercontent.com/MihrabHQ/mihrab-methods/main';
+export function summarize(list) {
+    return { from: list.from, to: list.to, entries: Object.values(list.points).reduce((n, e) => n + e.length, 0) };
+}
+const same = (a, b) => a.from === b.from && a.to === b.to && a.entries === b.entries;
+async function defaultSha256(text) {
+    const bytes = new TextEncoder().encode(text);
+    const subtle = globalThis.crypto?.subtle;
+    if (subtle) {
+        const buf = await subtle.digest('SHA-256', bytes);
+        return [...new Uint8Array(buf)].map(b => b.toString(16).padStart(2, '0')).join('');
+    }
+    try {
+        const { createHash } = await import('node:crypto');
+        return createHash('sha256').update(bytes).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+/** Put a list in force for the process — one verified by `fetchLatestCorrections`, or restored from the app's own storage. */
+export function applyCorrections(authority, list, revision) {
+    const data = authorityData(authority);
+    if (revision !== data.revision || !isCorrectionsFile(list))
+        return false;
+    const now = data.corrections.coverage();
+    if (list.to < now.to)
+        return false;
+    data.corrections.replace(list);
+    return true;
+}
+export async function fetchLatestCorrections(opts) {
+    const data = authorityData(opts.authority);
+    const have = { ...data.corrections.coverage(), entries: data.corrections.entries() };
+    const revision = opts.revision ?? data.revision;
+    const base = (opts.baseUrl ?? DEFAULT_FEED_URL).replace(/\/+$/, '');
+    const doFetch = opts.fetch ?? globalThis.fetch;
+    if (!doFetch)
+        return { status: 'rejected', reason: 'no fetch available', have };
+    const certRes = await doFetch(`${base}/certification.json`);
+    if (!certRes.ok)
+        return { status: 'rejected', reason: `certification.json: HTTP ${certRes.status}`, have };
+    const cert = (await certRes.json());
+    const entry = cert?.[opts.authority];
+    if (!entry || typeof entry !== 'object' || typeof entry.certified !== 'boolean') {
+        return { status: 'rejected', reason: `certification.json has no entry for ${opts.authority}`, have };
+    }
+    if (typeof entry.revision === 'number' && entry.revision > revision) {
+        return { status: 'method-moved', remoteRevision: entry.revision, have };
+    }
+    if (!entry.certified)
+        return { status: 'uncertified', have };
+    if (entry.revision !== revision)
+        return { status: 'rejected', reason: `certified for revision ${entry.revision}, this build computes ${revision}`, have };
+    const named = entry.corrections;
+    if (!named || typeof named.from !== 'string' || typeof named.to !== 'string' || typeof named.entries !== 'number') {
+        return { status: 'rejected', reason: 'the certification names no correction list', have };
+    }
+    if (same(have, named) || named.to < have.to)
+        return { status: 'current', have, certified: true };
+    const listRes = await doFetch(`${base}/data/corrections/${opts.authority}.json`);
+    if (!listRes.ok)
+        return { status: 'rejected', reason: `${opts.authority}.json: HTTP ${listRes.status}`, have };
+    const text = await listRes.text();
+    let list;
+    try {
+        list = JSON.parse(text);
+    }
+    catch {
+        return { status: 'rejected', reason: 'the list is not JSON', have };
+    }
+    if (!isCorrectionsFile(list))
+        return { status: 'rejected', reason: 'the list does not have the shape of one', have };
+    const summary = summarize(list);
+    if (!same(summary, named))
+        return { status: 'rejected', reason: 'the list is not the one the certification names', have };
+    let integrity = 'unchecked';
+    if (named.sha256) {
+        const hash = opts.sha256 ? await opts.sha256(text) : await defaultSha256(text);
+        if (hash !== null) {
+            if (hash.toLowerCase() !== named.sha256.toLowerCase())
+                return { status: 'rejected', reason: 'the list’s SHA-256 is not the one the certification names', have };
+            integrity = 'verified';
+        }
+    }
+    const applied = opts.apply === false ? false : applyCorrections(opts.authority, list, revision);
+    return { status: 'updated', list, summary, integrity, applied };
+}

package/dist/esm/core/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The library without any authority's data: the calls, the types, the sun.
+ * Load an authority (`mihrab-methods/<authority>`, or `mihrab-methods` for
+ * all) before calling anything that needs its places or its list.
+ */
+export { candidateTimes, certificationOf, certifiedSpan, distanceKm, isCertified, loadedAuthorityIds, methodInfo, nearestPlace, placeById, placesOf, timesFor, timesForRange, type NearestPlace, } from './api.js';
+export { candidateInstants, type ComputeOptions } from './compute.js';
+export { parseCivilDate, isoOf } from './civilDate.js';
+export { placeClockAt, clockOffsetAt, tableClockAt, printedAt } from './clock.js';
+export { fetchLatestCorrections, applyCorrections, type FetchOptions, type FetchResult } from './fetchLatest.js';
+export { isCorrectionsFile, pointKey } from './correctionList.js';
+export { METHOD_REVISION } from '../methods/revisions.js';
+export { preciseApparentSun } from '../sun/preciseSun.js';
+export { AUTHORITIES, PRAYER_KEYS, UncertifiedMethodError, type Authority, type Certification, type CheckRecord, type CivilDate, type CorrectionsFile, type DayStatus, type DayTimes, type Instants, type MethodInfo, type Place, type PrayerKey, type PrayerTime, type TableClock, type TimesOptions, } from './types.js';