search-rotation 0.4.9

package/dist/persistence.js

@@ -0,0 +1,80 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+const sleeper = new Int32Array(new SharedArrayBuffer(4));
+/** Synchronous Lamport bakery lock for local processes. Each contender owns a
+ * unique directory for its whole lifetime; stale recovery never unlinks a
+ * successor's lock. Missing ticket means choosing=true. Only dead PIDs are
+ * recovered: slow live owners are never evicted on a wall-clock timeout.
+ * Limitation: after a crash, OS PID reuse can make an abandoned contender look
+ * alive. Writes then time out safely until that PID exits or the abandoned
+ * directory is removed while all search-rotation processes are stopped. */
+export function withFileLock(file, action, timeoutMs = 10_000) {
+    const root = `${file}.lock`;
+    fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+    const id = `${process.pid}-${randomUUID()}`;
+    const own = path.join(root, id);
+    fs.mkdirSync(own, { mode: 0o700 });
+    const started = Date.now();
+    const ticket = (name) => {
+        const dir = path.join(root, name);
+        const pid = Number(name.split('-')[0]);
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            return null;
+        try {
+            process.kill(pid, 0);
+        }
+        catch (error) {
+            if (error.code === 'ESRCH') {
+                fs.rmSync(dir, { recursive: true, force: true });
+                return null;
+            }
+        }
+        try {
+            return Number(fs.readFileSync(path.join(dir, 'ticket'), 'utf8')) || 0;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            return fs.existsSync(dir) ? 0 : null;
+        }
+    };
+    try {
+        let mine = 1;
+        for (const name of fs.readdirSync(root))
+            if (name !== id)
+                mine = Math.max(mine, (ticket(name) ?? 0) + 1);
+        atomicWriteFile(path.join(own, 'ticket'), String(mine));
+        while (true) {
+            let blocked = false;
+            for (const name of fs.readdirSync(root)) {
+                if (name === id)
+                    continue;
+                const other = ticket(name);
+                if (other !== null && (other === 0 || other < mine || (other === mine && name < id))) {
+                    blocked = true;
+                    break;
+                }
+            }
+            if (!blocked)
+                return action();
+            if (Date.now() - started >= timeoutMs)
+                throw new Error(`Persistence lock timeout: ${path.basename(file)}`);
+            Atomics.wait(sleeper, 0, 0, 5);
+        }
+    }
+    finally {
+        fs.rmSync(own, { recursive: true, force: true });
+    }
+}
+/** Unique temp names plus rename keep concurrent readers on complete snapshots. */
+export function atomicWriteFile(file, content) {
+    const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        fs.writeFileSync(tmp, content, { mode: 0o600, flag: 'wx' });
+        fs.renameSync(tmp, file);
+    }
+    finally {
+        fs.rmSync(tmp, { force: true });
+    }
+}

package/dist/quota.js

@@ -0,0 +1,37 @@
+export function computeRemainingPct(used, limit, remote) {
+    if (remote && typeof remote.limit === 'number' && remote.limit > 0) {
+        const remaining = remote.remaining ?? remote.limit - (remote.used ?? 0);
+        return Math.max(0, Math.min(1, remaining / remote.limit));
+    }
+    if (limit > 0) {
+        const total = used.consumed ?? Number(used.search) + Number(used.fetch);
+        return Number.isFinite(total) ? Math.max(0, Math.min(1, (limit - total) / limit)) : null;
+    }
+    return null;
+}
+export function requestCost(adapter, kind, input) {
+    const value = adapter.estimateCost?.(kind, input) ?? adapter.meta.quota?.costs?.[kind] ?? 1;
+    return Number.isFinite(value) && value >= 0 ? value : 1;
+}
+export function quotaStatus(adapter, ctx, cfg, usage, remote) {
+    const policy = adapter.meta.quota;
+    const period = adapter.meta.keyless === 'ip' && !ctx.apiKey ? 'ip' : policy?.period ?? 'month';
+    const unit = policy?.unit ?? 'requests';
+    if (period === 'ip' || !ctx.apiKey) {
+        const count = usage.get(adapter.meta.id);
+        // Successful calls observed by this installation, never the shared IP balance.
+        return { period, unit: 'requests', limit: null, used: count.search + count.fetch, source: 'local', estimated: false };
+    }
+    const count = period === 'day' ? usage.getDay(adapter.meta.id, policy?.timeZone) : usage.get(adapter.meta.id);
+    const localUsed = unit === 'credits' ? count.consumed ?? count.search + count.fetch : count.search + count.fetch;
+    const limit = period === 'day'
+        ? cfg.settings.dailyLimits?.[adapter.meta.id] ?? policy?.limit ?? 0
+        : cfg.settings.monthlyLimits[adapter.meta.id] ?? policy?.limit ?? adapter.meta.monthlyFree;
+    if (remote && typeof remote.limit === 'number' && remote.limit > 0 && (remote.used !== undefined || remote.remaining !== undefined)) {
+        return { period, unit, limit: remote.limit, used: Math.max(0, remote.used ?? remote.limit - remote.remaining), source: 'remote', estimated: remote.estimated ?? false, timeZone: policy?.timeZone };
+    }
+    return { period, unit, limit: limit > 0 ? limit : null, used: localUsed, source: limit > 0 ? 'local' : 'unknown', estimated: policy?.estimated ?? true, timeZone: policy?.timeZone };
+}
+export function remainingPct(quota) {
+    return quota.limit && quota.used !== null ? Math.max(0, Math.min(1, (quota.limit - quota.used) / quota.limit)) : null;
+}

package/dist/router.js

@@ -0,0 +1,183 @@
+import { quotaStatus, remainingPct, requestCost } from './quota.js';
+import { fetchRemoteQuotaCached, recordRemoteConsumption } from './status.js';
+import { HttpError } from './engines/base.js';
+import { hasTimeFilter, normalizeSearchTime, describeSearchTime } from './search-time.js';
+import { abortable } from './abort.js';
+export class RouterError extends Error {
+    attempts;
+    constructor(message, attempts) {
+        super(message);
+        this.attempts = attempts;
+        this.name = 'RouterError';
+    }
+}
+export class SearchRouter {
+    opts;
+    rr = new Map();
+    health = new Map();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    now() { return this.opts.now?.() ?? Date.now(); }
+    state(c) {
+        const id = c.adapter.meta.id;
+        const identity = JSON.stringify([c.ctx.apiKey, c.ctx.extra]);
+        let state = this.health.get(id);
+        if (!state || state.identity !== identity) {
+            state = { identity, failures: 0, until: 0, reserved: 0 };
+            this.health.set(id, state);
+        }
+        return state;
+    }
+    failure(c, err) {
+        const state = this.state(c);
+        state.failures++;
+        const status = err instanceof HttpError ? err.status : undefined;
+        let delay = 0;
+        if (status === 429) {
+            const header = err.retryAfter;
+            const seconds = header?.trim() ? Number(header) : NaN;
+            const date = header ? Date.parse(header) : NaN;
+            delay = Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : Number.isFinite(date) ? Math.max(0, date - this.now()) : 30_000;
+        }
+        else if (status === 401 || status === 403)
+            delay = 60_000;
+        else if (state.failures >= 2)
+            delay = Math.min(300_000, 30_000 * 2 ** Math.min(4, state.failures - 2));
+        state.until = this.now() + delay;
+    }
+    async chain(kind, signal, prefer, onlyEngine, searchInput) {
+        signal.throwIfAborted();
+        const cfg = this.opts.getConfig();
+        const byId = new Map(this.opts.adapters.map(a => [a.meta.id, a]));
+        const order = onlyEngine ? [onlyEngine] : kind === 'fetch' ? cfg.fetchOrder : cfg.engines.map(e => e.id);
+        const entries = [];
+        for (const id of new Set(order)) {
+            const adapter = byId.get(id);
+            const e = cfg.engines.find(e => e.id === id);
+            if (!adapter || !e || (!onlyEngine && !e.enabled) || !(kind === 'search' ? adapter.search : adapter.fetchUrl))
+                continue;
+            if (!onlyEngine && !e.apiKey && adapter.meta.keylessCapabilities && !adapter.meta.keylessCapabilities.includes(kind))
+                continue;
+            const c = { adapter, ctx: { apiKey: e.apiKey, extra: e.extra, signal } };
+            if (searchInput && hasTimeFilter(searchInput) && !adapter.supportsSearchTime?.(searchInput, c.ctx))
+                continue;
+            if (this.state(c).until > this.now())
+                continue;
+            entries.push(c);
+        }
+        const rated = await abortable(Promise.all(entries.map(async (c) => {
+            const remote = c.adapter.meta.quotaEndpoint ? (await fetchRemoteQuotaCached(c.adapter, c.ctx)).quota : null;
+            const pct = remainingPct(quotaStatus(c.adapter, c.ctx, cfg, this.opts.usage, remote));
+            return { c, pct };
+        })), signal);
+        const groups = [
+            rated.filter(r => r.pct === null || r.pct > 0.1),
+            rated.filter(r => r.pct !== null && r.pct > 0 && r.pct <= 0.1),
+            cfg.settings.strictFreeMode ? [] : rated.filter(r => r.pct !== null && r.pct <= 0),
+        ];
+        // Filtered and unfiltered calls must not advance each other's rotation cursor.
+        const pool = JSON.stringify([kind, Boolean(searchInput && hasTimeFilter(searchInput)), rated.map(r => r.c.adapter.meta.id).sort()]);
+        const turn = prefer ? 0 : (this.rr.get(pool) ?? 0);
+        if (!prefer)
+            this.rr.set(pool, turn + 1);
+        let ordered = groups.flatMap(group => {
+            const start = group.length ? turn % group.length : 0;
+            return [...group.slice(start), ...group.slice(0, start)];
+        }).map(r => r.c);
+        if (prefer)
+            ordered = [...ordered.filter(c => c.adapter.meta.id === prefer), ...ordered.filter(c => c.adapter.meta.id !== prefer)];
+        return ordered;
+    }
+    recordUsage(c, kind, input, error) {
+        try {
+            this.opts.usage.record(c.adapter.meta.id, kind, error, requestCost(c.adapter, kind, input), c.adapter.meta.quota?.timeZone);
+        }
+        catch {
+            console.error('[search-rotation] Verbrauch konnte nicht gespeichert werden; Dateirechte/Sperre prüfen.');
+        }
+    }
+    async execute(kind, input, opts) {
+        const start = Date.now();
+        const cfg = this.opts.getConfig();
+        const timeoutMs = cfg.settings.requestTimeoutMs ?? 60_000;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(new Error(`Zeitlimit nach ${timeoutMs} ms überschritten`)), timeoutMs);
+        const signal = opts.signal ? AbortSignal.any([opts.signal, controller.signal]) : controller.signal;
+        const attempts = [];
+        const rawInput = kind === 'search' ? [input.query, hasTimeFilter(input) ? `[${describeSearchTime(input)}]` : ''].filter(Boolean).join(' ') : input.url;
+        try {
+            const chain = await this.chain(kind, signal, opts.onlyEngine ?? opts.preferEngine, opts.onlyEngine, kind === 'search' ? input : undefined);
+            if (!chain.length)
+                throw new RouterError(`Keine aktivierte ${kind === 'search' ? 'Such-Engine' : 'Fetch-Engine'} verfügbar. ${kind === 'search' && hasTimeFilter(input) ? 'Für diesen Zeitfilter ist aktuell keine kompatible Engine verfügbar. ' : ''}Engines, Cooldown und Gratis-Kontingent prüfen.`, attempts);
+            for (const c of chain) {
+                signal.throwIfAborted();
+                let reservation;
+                const cost = requestCost(c.adapter, kind, input);
+                // Check and reserve synchronously after obtaining the current snapshot.
+                if (cfg.settings.strictFreeMode) {
+                    const remote = c.adapter.meta.quotaEndpoint ? (await fetchRemoteQuotaCached(c.adapter, c.ctx)).quota : null;
+                    const quota = quotaStatus(c.adapter, c.ctx, cfg, this.opts.usage, remote);
+                    const health = this.state(c);
+                    if (quota.limit !== null && quota.used !== null && quota.used + health.reserved + cost > quota.limit)
+                        continue;
+                    health.reserved += cost;
+                    reservation = health;
+                }
+                const at = Date.now();
+                let value;
+                try {
+                    value = await abortable(kind === 'search'
+                        ? c.adapter.search(input, c.ctx)
+                        : c.adapter.fetchUrl(input, c.ctx), signal);
+                    signal.throwIfAborted();
+                }
+                catch (err) {
+                    if (signal.aborted)
+                        throw signal.reason;
+                    const error = err instanceof Error ? err.message : String(err);
+                    this.failure(c, err);
+                    this.recordUsage(c, kind, input, error);
+                    attempts.push({ engine: c.adapter.meta.id, ok: false, ms: Date.now() - at, error });
+                    continue;
+                }
+                finally {
+                    if (reservation)
+                        reservation.reserved -= cost;
+                }
+                const health = this.state(c);
+                health.failures = 0;
+                health.until = 0;
+                this.recordUsage(c, kind, input);
+                recordRemoteConsumption(c.adapter, c.ctx, requestCost(c.adapter, kind, input));
+                attempts.push({ engine: c.adapter.meta.id, ok: true, ms: Date.now() - at });
+                this.opts.history?.record({ kind, input: rawInput, engine: c.adapter.meta.id, ok: true, ms: Date.now() - start, attempts,
+                    result: typeof value === 'string' ? { chars: value.length, markdown: value } : { count: value.items.length, items: value.items } });
+                return { value, engine: c.adapter.meta.id, attempts };
+            }
+            const message = attempts.length === chain.length
+                ? `Alle ${attempts.length} ${kind === 'search' ? 'Such-Engines' : 'Fetch-Engines'} fehlgeschlagen.`
+                : 'Gratis-Kontingent erschöpft; keine weitere Engine verfügbar.';
+            throw new RouterError(message, attempts);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.opts.history?.record({ kind, input: rawInput, engine: null, ok: false, ms: Date.now() - start, attempts, error: message });
+            throw err instanceof RouterError ? err : new RouterError(message, attempts);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async search(input, opts = {}) {
+        input = normalizeSearchTime(input, this.now());
+        const configured = this.opts.getConfig().settings.defaultNumResults;
+        const numResults = input.numResults ?? (configured === null ? undefined : configured ?? 8);
+        const { value, engine, attempts } = await this.execute('search', { ...input, numResults }, opts);
+        return { ...value, engine, attempts };
+    }
+    async fetchUrl(input, opts = {}) {
+        const { value, engine, attempts } = await this.execute('fetch', input, opts);
+        return { markdown: value, engine, attempts };
+    }
+}

package/dist/search-time.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+export const timeRangeSchema = z.enum(['day', 'week', 'month', 'year']);
+export const dateSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Expected YYYY-MM-DD').refine(value => {
+    const date = new Date(`${value}T00:00:00.000Z`);
+    return Number.isFinite(date.getTime()) && date.toISOString().slice(0, 10) === value;
+}, 'Invalid calendar date');
+export function hasTimeFilter(input) {
+    return input.timeRange !== undefined || input.startDate !== undefined || input.endDate !== undefined;
+}
+/** Resolve once per request so every failover receives identical UTC date bounds. */
+export function normalizeSearchTime(input, now) {
+    if (input.timeRange !== undefined)
+        timeRangeSchema.parse(input.timeRange);
+    if (input.startDate !== undefined)
+        dateSchema.parse(input.startDate);
+    if (input.endDate !== undefined)
+        dateSchema.parse(input.endDate);
+    if (input.timeRange !== undefined && (input.startDate !== undefined || input.endDate !== undefined)) {
+        throw new Error('timeRange cannot be combined with startDate or endDate');
+    }
+    if (input.startDate && input.endDate && input.startDate > input.endDate) {
+        throw new Error('startDate must be on or before endDate');
+    }
+    if (!input.timeRange)
+        return input;
+    const days = { day: 1, week: 7, month: 30, year: 365 }[input.timeRange];
+    return { ...input, startDate: new Date(now - days * 86_400_000).toISOString().slice(0, 10), endDate: new Date(now).toISOString().slice(0, 10) };
+}
+export function describeSearchTime(input) {
+    return [input.timeRange, input.startDate && `from ${input.startDate}`, input.endDate && `through ${input.endDate}`].filter(Boolean).join(' ');
+}

package/dist/status.js

@@ -0,0 +1,141 @@
+import { quotaStatus, remainingPct } from "./quota.js";
+import { createHash } from "node:crypto";
+import { abortable } from "./abort.js";
+const remoteCache = new Map();
+const REMOTE_TTL_MS = 5 * 60 * 1000;
+const pendingQuotas = new Map();
+let cacheGeneration = 0;
+export function maskKey(key) {
+    if (!key)
+        return "";
+    if (key.length <= 10)
+        return `${key.slice(0, 2)}…${key.slice(-2)}`;
+    return `${key.slice(0, 6)}…${key.slice(-4)}`;
+}
+/** Remote-Quota-Cache leeren (z. B. nach dem Hinterlegen eines neuen Keys). */
+export function clearRemoteQuotaCache() {
+    remoteCache.clear();
+    // Old callers may finish, but their snapshots must not refill this generation.
+    cacheGeneration++;
+    pendingQuotas.clear();
+}
+/** Remote-Quota vom Anbieter abrufen, 5 Minuten gecacht. */
+export async function fetchRemoteQuotaCached(adapter, ctx) {
+    if (!adapter.remoteQuota || !ctx.apiKey)
+        return { quota: null };
+    ctx.signal?.throwIfAborted();
+    const key = cacheKey(adapter, ctx);
+    const cached = remoteCache.get(key);
+    if (cached && Date.now() - cached.at < REMOTE_TTL_MS) {
+        return { quota: cached.quota, error: cached.error };
+    }
+    let pending = pendingQuotas.get(key);
+    if (!pending) {
+        const generation = cacheGeneration;
+        const controller = new AbortController();
+        const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(20_000)]);
+        const entry = { controller, waiters: 0, consumed: 0, settled: false, promise: Promise.resolve({ quota: null }) };
+        pendingQuotas.set(key, entry);
+        entry.promise = (async () => {
+            try {
+                const snapshot = await abortable(Promise.resolve().then(() => {
+                    signal.throwIfAborted();
+                    return adapter.remoteQuota({ ...ctx, signal });
+                }), signal);
+                // Provider snapshots may predate requests completed while fetching.
+                // Conservatively add that consumption instead of restoring spent quota.
+                const quota = addConsumption(snapshot, entry.consumed);
+                if (cacheGeneration === generation && pendingQuotas.get(key) === entry)
+                    remoteCache.set(key, { at: Date.now(), quota });
+                return { quota };
+            }
+            catch (err) {
+                if (controller.signal.aborted)
+                    throw controller.signal.reason;
+                const error = err instanceof Error ? err.message : String(err);
+                if (cacheGeneration === generation && pendingQuotas.get(key) === entry)
+                    remoteCache.set(key, { at: Date.now(), quota: null, error });
+                return { quota: null, error };
+            }
+            finally {
+                entry.settled = true;
+                if (pendingQuotas.get(key) === entry)
+                    pendingQuotas.delete(key);
+            }
+        })();
+        pending = entry;
+    }
+    pending.waiters++;
+    try {
+        return await abortable(pending.promise, ctx.signal);
+    }
+    finally {
+        pending.waiters--;
+        if (pending.waiters === 0 && !pending.settled) {
+            if (pendingQuotas.get(key) === pending)
+                pendingQuotas.delete(key);
+            pending.controller.abort(new Error("Keine wartenden Quota-Aufrufe mehr"));
+        }
+    }
+}
+export async function buildStatus(cfg, usage, adapters) {
+    const searchPos = new Map(cfg.engines.map((e, i) => [e.id, i]));
+    const fetchPos = new Map(cfg.fetchOrder.map((id, i) => [id, i]));
+    const rows = adapters.map(async (adapter) => {
+        const meta = adapter.meta;
+        const e = cfg.engines.find((x) => x.id === meta.id);
+        const used = usage.get(meta.id);
+        const monthlyLimit = !e?.apiKey ? 0 : cfg.settings.monthlyLimits[meta.id] ?? meta.monthlyFree;
+        const { quota, error } = await fetchRemoteQuotaCached(adapter, {
+            apiKey: e?.apiKey,
+            extra: e?.extra,
+        });
+        return {
+            id: meta.id,
+            label: meta.label,
+            homepage: meta.homepage,
+            signupUrl: meta.signupUrl,
+            capabilities: !e?.apiKey && meta.keylessCapabilities ? meta.keylessCapabilities : meta.capabilities,
+            supportedCapabilities: meta.capabilities,
+            keylessCapabilities: meta.keyless === "ip" ? meta.keylessCapabilities ?? meta.capabilities : [],
+            keyless: meta.keyless,
+            notes: meta.notes,
+            extraFields: meta.extraFields ?? [],
+            enabled: e?.enabled ?? true,
+            searchPosition: searchPos.get(meta.id) ?? -1,
+            fetchPosition: fetchPos.has(meta.id) ? fetchPos.get(meta.id) : -1,
+            hasKey: Boolean(e?.apiKey),
+            keyMasked: maskKey(e?.apiKey),
+            extrasSet: Object.fromEntries((meta.extraFields ?? []).map((f) => [f.key, Boolean(e?.extra?.[f.key])])),
+            monthlyLimit,
+            used,
+            remote: quota,
+            remoteError: error,
+            remainingPct: remainingPct(quotaStatus(adapter, { apiKey: e?.apiKey }, cfg, usage, quota)),
+            quota: quotaStatus(adapter, { apiKey: e?.apiKey }, cfg, usage, quota),
+            lastError: used.lastError,
+        };
+    });
+    return Promise.all(rows);
+}
+function cacheKey(adapter, ctx) {
+    return adapter.meta.id + ':' + createHash('sha256').update(JSON.stringify([ctx.apiKey, ctx.extra])).digest('hex');
+}
+/** Account for requests made since the last provider snapshot. */
+export function recordRemoteConsumption(adapter, ctx, units) {
+    if (!Number.isFinite(units) || units <= 0)
+        return;
+    const key = cacheKey(adapter, ctx);
+    const pending = pendingQuotas.get(key);
+    if (pending)
+        pending.consumed += units;
+    const entry = remoteCache.get(key);
+    if (entry?.quota)
+        entry.quota = addConsumption(entry.quota, units);
+}
+function addConsumption(q, units) {
+    if (!units || !q.limit || (q.used === undefined && q.remaining === undefined))
+        return q;
+    const used = (q.used ?? q.limit - q.remaining) + units;
+    return { ...q, used, remaining: Math.max(0, q.limit - used), estimated: true };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/usage.js

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import path from "node:path";
+import { atomicWriteFile, withFileLock } from "./persistence.js";
+/** Lokale Verbrauchszähler pro Engine und Kalendermonat (UTC). */
+export class UsageStore {
+    file;
+    data = {};
+    constructor(dir) {
+        this.file = path.join(dir, "usage.json");
+        this.load();
+    }
+    load() {
+        this.data = {};
+        try {
+            const raw = JSON.parse(fs.readFileSync(this.file, "utf8"));
+            if (!raw || typeof raw !== "object" || Array.isArray(raw))
+                return;
+            for (const [month, engines] of Object.entries(raw)) {
+                if (!engines || typeof engines !== "object" || Array.isArray(engines))
+                    continue;
+                const cleanMonth = {};
+                for (const [engine, u] of Object.entries(engines)) {
+                    if (!u || typeof u !== "object")
+                        continue;
+                    const rec = u;
+                    // Krumme Zähler (NaN/Strings) würden pct = NaN erzeugen und die
+                    // Engine still aus der Rotation werfen — strikt säubern.
+                    const num = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : 0;
+                    cleanMonth[engine] = {
+                        search: num(rec.search),
+                        fetch: num(rec.fetch),
+                        errors: num(rec.errors),
+                        consumed: typeof rec.consumed === "number" && Number.isFinite(rec.consumed) && rec.consumed >= 0
+                            ? rec.consumed : num(rec.search) + num(rec.fetch),
+                        lastError: typeof rec.lastError === "string" ? rec.lastError : undefined,
+                        lastUsed: typeof rec.lastUsed === "string" ? rec.lastUsed : undefined,
+                    };
+                }
+                this.data[month] = cleanMonth;
+            }
+        }
+        catch (error) {
+            // A missing or malformed snapshot may be initialized for compatibility.
+            // Other I/O failures must abort the transaction, never erase counters.
+            if (!(error instanceof SyntaxError) && error.code !== "ENOENT")
+                throw error;
+            this.data = {};
+        }
+    }
+    monthKey(date = new Date()) {
+        return `${date.getUTCFullYear()}-${String(date.getUTCMonth() + 1).padStart(2, "0")}`;
+    }
+    /** Provider-local calendar day; Google uses America/Los_Angeles. */
+    dayKey(date = new Date(), timeZone = "UTC") {
+        const parts = new Intl.DateTimeFormat("en-CA", { timeZone, year: "numeric", month: "2-digit", day: "2-digit" }).formatToParts(date);
+        const part = (type) => parts.find(p => p.type === type).value;
+        return `${part("year")}-${part("month")}-${part("day")}`;
+    }
+    record(engine, kind, error, consumption = 1, timeZone = "UTC") {
+        if (!Number.isFinite(consumption) || consumption < 0)
+            throw new Error("Invalid quota consumption");
+        const now = new Date();
+        const day = this.dayKey(now, timeZone);
+        withFileLock(this.file, () => {
+            this.load();
+            // YYYY-MM monthly records remain unchanged; YYYY-MM-DD adds daily buckets.
+            for (const key of [this.monthKey(now), day]) {
+                const bucket = (this.data[key] ??= {});
+                const e = (bucket[engine] ??= { search: 0, fetch: 0, errors: 0, consumed: 0 });
+                if (error) {
+                    e.errors += 1;
+                    e.lastError = `${now.toISOString()}: ${error}`;
+                }
+                else {
+                    e.consumed = (e.consumed ?? e.search + e.fetch) + consumption;
+                    e[kind] += 1;
+                    e.lastUsed = now.toISOString();
+                }
+            }
+            const cutoff = new Date(now.getTime() - 62 * 86_400_000).toISOString().slice(0, 10);
+            for (const key of Object.keys(this.data))
+                if (/^\d{4}-\d{2}-\d{2}$/.test(key) && key < cutoff)
+                    delete this.data[key];
+            atomicWriteFile(this.file, JSON.stringify(this.data, null, 2));
+        });
+    }
+    get(engine) {
+        this.load();
+        return this.data[this.monthKey()]?.[engine] ?? { search: 0, fetch: 0, errors: 0 };
+    }
+    getDay(engine, timeZone = "UTC") {
+        this.load();
+        return this.data[this.dayKey(new Date(), timeZone)]?.[engine] ?? { search: 0, fetch: 0, errors: 0 };
+    }
+}

package/dist/version.js

@@ -0,0 +1,5 @@
+import { createRequire } from "node:module";
+// Version aus package.json — einzige Quelle, kein doppeltes Pflegen beim Bumpen.
+// Resolution: dist/version.js → ../package.json (liegt im npm-Paket und im Repo immer neben dist).
+const pkg = createRequire(import.meta.url)("../package.json");
+export const VERSION = pkg.version;