@liiift-studio/sanity-visitor-insights 0.38.0 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liiift-studio/sanity-visitor-insights",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "Visitor-behaviour analytics for type-foundry Sanity Studios — GA4, Vercel and order data reconciled honestly",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/core/core.test.ts

@@ -501,3 +501,56 @@ describe('GA4 capture rate', () => {
 		expect(grossUp(100, model)).toBeNull()
 	})
 })
+
+describe('a day boundary survives a DST transition', () => {
+	/*
+	 * The two-pass offset resolution had no test. Reverting it to a single pass — the naive
+	 * implementation anyone would write first — left the whole suite green, on the function that
+	 * decides which orders fall inside the window every other figure is compared against.
+	 */
+	/*
+	 * These dates are chosen because the two passes DISAGREE on them.
+	 *
+	 * A first attempt used the US transition dates, and the mutation — reverting to a single pass —
+	 * went uncaught: for Los Angeles the naive probe at 00:00Z lands on the previous local afternoon,
+	 * which is on the same side of a 02:00 transition as local midnight is, so both passes measure
+	 * the same offset. The zones that discriminate are those far enough ahead of UTC that the naive
+	 * probe crosses the transition, which is what these are.
+	 */
+	it('resolves a fall-back date where the naive offset is the wrong one', () => {
+		// Sydney returns to +10 at 03:00 local on 2026-04-05, so local midnight that day is still
+		// +11. A single pass probes 00:00Z — already 11:00 local, after the change — and subtracts
+		// +10, putting the day boundary an hour late.
+		expect(zonedDayStartUtc('2026-04-05', 'Australia/Sydney')).toBe('2026-04-04T13:00:00.000Z')
+	})
+
+	it('resolves a spring-forward date where the naive offset errs the other way', () => {
+		expect(zonedDayStartUtc('2026-10-04', 'Australia/Sydney')).toBe('2026-10-03T14:00:00.000Z')
+	})
+
+	it('is unchanged on a transition date whose probe stays on one side', () => {
+		// The US dates, kept because they are the foundries' own zones — they pass either way, which
+		// is exactly why they could not guard the two-pass resolution.
+		expect(zonedDayStartUtc('2026-03-08', 'America/Los_Angeles')).toBe('2026-03-08T08:00:00.000Z')
+		expect(zonedDayStartUtc('2026-11-01', 'America/Los_Angeles')).toBe('2026-11-01T07:00:00.000Z')
+	})
+
+	it('handles a zone whose offset is not a whole hour', () => {
+		expect(zonedDayStartUtc('2026-06-15', 'Asia/Kolkata')).toBe('2026-06-14T18:30:00.000Z')
+	})
+
+	it('gives an ordinary day the plain offset', () => {
+		expect(zonedDayStartUtc('2026-06-15', 'America/New_York')).toBe('2026-06-15T04:00:00.000Z')
+	})
+
+	it('refuses a malformed date rather than resolving one', () => {
+		expect(() => zonedDayStartUtc('not-a-date', 'UTC')).toThrow(/Invalid ISO date/)
+	})
+
+	it('makes one day end exactly where the next begins', () => {
+		// The property nothing can double-count across, and the reason the unconverged midnight-DST
+		// case is a shift rather than an overlap.
+		expect(zonedDayEndUtc('2026-03-07', 'America/Los_Angeles'))
+			.toBe(zonedDayStartUtc('2026-03-08', 'America/Los_Angeles'))
+	})
+})

package/src/server/cache.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Tests for the report cache.
+ *
+ * It had none. A review's mutation table showed that removing expiry, removing eviction, and
+ * ignoring the per-result TTL callback entirely all left the suite green — on a module whose whole
+ * job is bounding GA4 fan-out against a property with a ten-concurrent ceiling, and which had just
+ * been changed to cache failures briefly.
+ *
+ * Timers are faked rather than slept on, so expiry is asserted at the boundary instead of
+ * approximately and the suite stays fast.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { DEFAULT_TTL_MS, cacheKey, clearCache, getCached, setCached, withCache } from './cache'
+
+describe('cacheKey', () => {
+	beforeEach(() => { clearCache() })
+
+	it('separates keys that differ in any part', () => {
+		expect(cacheKey(['vi', 'darden', 'overview'])).not.toBe(cacheKey(['vi', 'darden', 'journey']))
+	})
+
+	it('treats an absent part as empty rather than as the string "undefined"', () => {
+		expect(cacheKey(['vi', undefined])).toBe('vi|')
+	})
+
+	it('does not collide across a part boundary', () => {
+		// Without a separator, ['a','bc'] and ['ab','c'] would be the same key and two different
+		// sites could read each other's reports.
+		expect(cacheKey(['a', 'bc'])).not.toBe(cacheKey(['ab', 'c']))
+	})
+})
+
+describe('expiry', () => {
+	beforeEach(() => { clearCache(); vi.useFakeTimers() })
+	afterEach(() => { vi.useRealTimers() })
+
+	it('serves a value inside its TTL', () => {
+		setCached('k', 'value', 1000)
+		vi.advanceTimersByTime(999)
+		expect(getCached('k')).toBe('value')
+	})
+
+	it('drops a value at its TTL, not merely after it', () => {
+		// `expiresAt <= now` — the boundary belongs to the expired side, so a stale report cannot be
+		// served for one more millisecond.
+		setCached('k', 'value', 1000)
+		vi.advanceTimersByTime(1000)
+		expect(getCached('k')).toBeUndefined()
+	})
+
+	it('evicts on read rather than waiting for a sweep', () => {
+		// There is no timer in this module; a serverless instance may never run one.
+		setCached('k', 'value', 1000)
+		vi.advanceTimersByTime(1000)
+		getCached('k')
+		// Re-storing with a fresh TTL must work, which it cannot if the stale entry lingers.
+		setCached('k', 'second', 1000)
+		expect(getCached('k')).toBe('second')
+	})
+
+	it('defaults to the documented window', () => {
+		setCached('k', 'value')
+		vi.advanceTimersByTime(DEFAULT_TTL_MS - 1)
+		expect(getCached('k')).toBe('value')
+		vi.advanceTimersByTime(1)
+		expect(getCached('k')).toBeUndefined()
+	})
+})
+
+describe('bounding', () => {
+	beforeEach(() => { clearCache() })
+
+	it('evicts the oldest entry rather than growing without limit', () => {
+		// A long-lived instance must not accumulate every range any editor has ever opened.
+		for (let i = 0; i < 200; i++) setCached(`k${i}`, i, 60_000)
+		expect(getCached('k0')).toBe(0)
+		setCached('overflow', 'new', 60_000)
+		expect(getCached('k0')).toBeUndefined()
+		expect(getCached('overflow')).toBe('new')
+	})
+
+	it('overwrites in place without evicting anything', () => {
+		for (let i = 0; i < 200; i++) setCached(`k${i}`, i, 60_000)
+		setCached('k5', 'updated', 60_000)
+		expect(getCached('k0')).toBe(0)
+		expect(getCached('k5')).toBe('updated')
+	})
+})
+
+describe('withCache', () => {
+	beforeEach(() => { clearCache(); vi.useFakeTimers() })
+	afterEach(() => { vi.useRealTimers() })
+
+	it('computes once and serves the stored value after', async () => {
+		let calls = 0
+		const compute = async () => { calls += 1; return calls }
+		expect(await withCache('k', 60_000, compute)).toBe(1)
+		expect(await withCache('k', 60_000, compute)).toBe(1)
+		expect(calls).toBe(1)
+	})
+
+	it('lets the caller set a TTL from the result', async () => {
+		// The whole point of the callback: a healthy answer keeps the full window, a degraded one is
+		// held for seconds so a transient blip does not read as a five-minute outage.
+		await withCache('healthy', 60_000, async () => ({ ok: true }), (v) => (v.ok ? 60_000 : 1_000))
+		await withCache('degraded', 60_000, async () => ({ ok: false }), (v) => (v.ok ? 60_000 : 1_000))
+
+		vi.advanceTimersByTime(1_000)
+		expect(getCached('degraded')).toBeUndefined()
+		expect(getCached('healthy')).toBeDefined()
+	})
+
+	it('does not store at all when the callback returns zero', async () => {
+		let calls = 0
+		const compute = async () => { calls += 1; return calls }
+		await withCache('k', 60_000, compute, () => 0)
+		await withCache('k', 60_000, compute, () => 0)
+		expect(calls).toBe(2)
+	})
+
+	it('falls back to the fixed TTL when no callback is given', async () => {
+		await withCache('k', 1_000, async () => 'value')
+		vi.advanceTimersByTime(999)
+		expect(getCached('k')).toBe('value')
+		vi.advanceTimersByTime(1)
+		expect(getCached('k')).toBeUndefined()
+	})
+
+	it('does not cache a rejection', async () => {
+		// A thrown error must not be stored as an answer — the next caller has to be free to retry.
+		await expect(withCache('k', 60_000, async () => { throw new Error('upstream down') }))
+			.rejects.toThrow('upstream down')
+		expect(getCached('k')).toBeUndefined()
+	})
+})

package/src/server/reports/reports.test.ts

@@ -1815,3 +1815,43 @@ describe('Vercel buckets are labelled by the day they mostly cover', () => {
 		expect(formatInTimeZone(new Date(bucketStart), 'America/Los_Angeles')).toBe('2026-09-04')
 	})
 })
+
+describe('an order window is half-open, so no order lands in two ranges', () => {
+	it('excludes the end instant rather than including it', async () => {
+		// `_createdAt < $end` with $end being the START of the day after — so day N's window ends
+		// exactly where day N+1's begins. Making it `<=` would count an order placed at that instant
+		// in both the current window and the next, in the figure the tool calls exact.
+		const queries: string[] = []
+		const client = {
+			fetch: (query: string) => { queries.push(query); return Promise.resolve([]) },
+		} as never
+
+		await countOrders(client, orderQueryOptions(
+			{ documentType: 'order', statusField: 'orderStatus.status', countedStatuses: ['verified'] },
+			{ start: '2026-08-20', end: '2026-08-26', timezone: 'UTC' },
+		))
+
+		expect(queries[0]).toContain('_createdAt >= $start')
+		expect(queries[0]).toContain('_createdAt < $end')
+		expect(queries[0]).not.toContain('_createdAt <= $end')
+	})
+
+	it('ends the window at the start of the day after the last one', async () => {
+		// The bound has to be exclusive AND cover the whole final day; an exclusive bound at the
+		// final day's own start would silently drop every order placed on it. Asserted through the
+		// params the query is actually run with, rather than by widening the module's exports.
+		let params: Record<string, unknown> | undefined
+		const client = {
+			fetch: (_query: string, p: Record<string, unknown>) => { params = p; return Promise.resolve([]) },
+		} as never
+
+		await countOrders(client, orderQueryOptions(
+			{ documentType: 'order', statusField: 'orderStatus.status', countedStatuses: ['verified'] },
+			{ start: '2026-08-20', end: '2026-08-26', timezone: 'UTC' },
+		))
+
+		expect(params?.start).toBe('2026-08-20T00:00:00.000Z')
+		expect(params?.end).toBe('2026-08-27T00:00:00.000Z')
+	})
+
+})

package/src/server/vercel.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Tests for the real Vercel client.
+ *
+ * It had none. The test double in `testing/fakes.ts` implements `pageviews()` by returning a
+ * fixture, so no test had ever reached the client's chunking, its day filtering, its totals
+ * derivation or its failure reporting — and a review's mutation table showed that deleting the
+ * range filter, hard-coding `incompleteWindows` to zero, or switching the total between its two
+ * sources all left the suite green.
+ *
+ * `fetch` is stubbed per test rather than mocked at module level, so each case states exactly what
+ * the API gave back and what the client made of it.
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createVercelClient, dailyWindows, granularityFor } from './vercel'
+
+/** One aggregate bucket, as the API returns it. */
+function bucket(day: string, pageviews: number) {
+	return { timestamp: `${day}T00:00:00.000Z`, pageviews, visitors: pageviews }
+}
+
+/**
+ * Stub `fetch` for the two endpoints the client calls.
+ *
+ * @param series - buckets to return from `visits/aggregate`, or a thrower per call index
+ * @param totals - what `visits/count` reports for the whole range
+ */
+function stubFetch(
+	series: Array<ReturnType<typeof bucket>> | ((call: number) => Array<ReturnType<typeof bucket>>),
+	totals: { pageviews?: number; visitors?: number } | null = { pageviews: 999, visitors: 500 },
+) {
+	let aggregateCalls = 0
+	const urls: string[] = []
+	globalThis.fetch = (async (url: string) => {
+		urls.push(url)
+		const isCount = url.includes('visits/count')
+		const body = isCount
+			? { data: totals }
+			: { data: typeof series === 'function' ? series(aggregateCalls++) : series }
+		return { ok: true, status: 200, async json() { return body } }
+	}) as unknown as typeof fetch
+	return urls
+}
+
+const client = () => createVercelClient('token', 'proj', 'team')
+
+afterEach(() => { vi.restoreAllMocks() })
+
+describe('the day series', () => {
+	it('keeps only days inside the requested range', async () => {
+		// The API is asked for a range but the response is not trusted to respect it.
+		stubFetch([bucket('2026-08-19', 10), bucket('2026-08-20', 100), bucket('2026-08-26', 200), bucket('2026-08-27', 20)])
+		const result = await client().pageviews('2026-08-20', '2026-08-26')
+		expect(Object.keys(result.byDate).sort()).toEqual(['2026-08-20', '2026-08-26'])
+	})
+
+	it('sums repeated buckets for one day rather than overwriting', async () => {
+		// Chunked fetches can return the same day twice at a window boundary; the second must not
+		// silently replace the first.
+		stubFetch([bucket('2026-08-20', 100), bucket('2026-08-20', 50)])
+		const result = await client().pageviews('2026-08-20', '2026-08-26')
+		expect(result.byDate['2026-08-20']).toBe(150)
+	})
+
+	it('ignores a bucket with no timestamp instead of keying it undefined', async () => {
+		stubFetch([{ pageviews: 100 } as never, bucket('2026-08-21', 40)])
+		const result = await client().pageviews('2026-08-20', '2026-08-26')
+		expect(Object.keys(result.byDate)).toEqual(['2026-08-21'])
+	})
+})
+
+describe('the range total', () => {
+	it('comes from the day series when that series is whole', async () => {
+		// Summing the days covers exactly the window asked for; the count endpoint's bare dates are
+		// read in UTC and can start and end elsewhere.
+		stubFetch([bucket('2026-08-20', 100), bucket('2026-08-21', 200)], { pageviews: 999, visitors: 40 })
+		const result = await client().pageviews('2026-08-20', '2026-08-26')
+		expect(result.total).toBe(300)
+	})
+
+	it('falls back to the count endpoint when a window failed', async () => {
+		// A hole in the series must not be published as a smaller total.
+		let call = 0
+		globalThis.fetch = (async (url: string) => {
+			if (url.includes('visits/count')) {
+				return { ok: true, status: 200, async json() { return { data: { pageviews: 999, visitors: 40 } } } }
+			}
+			call += 1
+			if (call === 1) throw new Error('window down')
+			return { ok: true, status: 200, async json() { return { data: [bucket('2026-08-20', 100)] } } }
+		}) as unknown as typeof fetch
+
+		const result = await client().pageviews('2026-08-20', '2026-08-26')
+		expect(result.incompleteWindows).toBe(1)
+		expect(result.total).toBe(999)
+	})
+
+	it('reports an absent visitor count as absent, never as zero', async () => {
+		// This panel exists to tell "measured nothing" from "did not measure", and has to hold itself
+		// to that first.
+		stubFetch([bucket('2026-08-20', 100)], {})
+		const result = await client().pageviews('2026-08-20', '2026-08-26')
+		expect(result.visitors).toBeNull()
+	})
+
+	it('does not sum daily visitors, which would double-count returning people', async () => {
+		// A person visiting on three days is three daily visitors and one range visitor.
+		stubFetch([bucket('2026-08-20', 100), bucket('2026-08-21', 100)], { pageviews: 999, visitors: 40 })
+		const result = await client().pageviews('2026-08-20', '2026-08-26')
+		expect(result.visitors).toBe(40)
+	})
+})
+
+describe('long ranges', () => {
+	it('splits a quarter into day-bucketed windows', async () => {
+		const urls = stubFetch(() => [bucket('2026-08-20', 10)])
+		await client().pageviews('2026-06-08', '2026-09-05')
+		const aggregates = urls.filter((u) => u.includes('visits/aggregate'))
+		expect(aggregates.length).toBe(dailyWindows('2026-06-08', '2026-09-05').length)
+		for (const url of aggregates) expect(url).toContain('by=day')
+	})
+
+	it('reports a coarse fallback as not daily, so its total is not published as one', async () => {
+		// Beyond the window cap the client makes one `by: month` call. Summing month buckets and
+		// filtering them by a day comparison drops one straddling the start and keeps one straddling
+		// the end — and `incompleteWindows` stays zero, so the flag built to say "do not trust this"
+		// reported it sound.
+		const urls = stubFetch([bucket('2025-09-01', 5000)])
+		const result = await client().pageviews('2025-08-15', '2026-09-05')
+		expect(urls.some((u) => u.includes(`by=${granularityFor('2025-08-15', '2026-09-05')}`))).toBe(true)
+		expect(result.daily).toBe(false)
+		expect(result.total).toBe(999)
+	})
+})