@liiift-studio/sanity-visitor-insights 0.2.0 → 0.2.2

package/dist/testing.d.mts

@@ -1,4 +1,4 @@
-import { G as Ga4Client, a as Ga4ReportRequest, S as SanityQueryClient, b as Ga4Report, c as VercelPageviews, V as VercelClient } from './vercel-D19ArNAY.mjs';
+import { G as Ga4Client, b as Ga4ReportRequest, S as SanityQueryClient, a as Ga4Report, d as VercelPageviews, V as VercelClient } from './vercel-BMEO-Jcw.mjs';
 
 /**
  * Test doubles and fixture builders for the report layer.
@@ -48,8 +48,14 @@ interface Ga4Script {
 declare function createFakeGa4Client(script?: Ga4Script): FakeGa4Client;
 /** Build a Vercel client fake returning a fixed total. */
 declare function createFakeVercelClient(result: VercelPageviews | Error): VercelClient;
-/** Build a Vercel pageviews fixture. */
-declare function makeVercelPageviews(byDate: Record<string, number>): VercelPageviews;
+/**
+ * Build a Vercel pageviews fixture.
+ *
+ * `visitors` defaults to roughly two thirds of pageviews rather than to the pageview total,
+ * because they are genuinely different numbers — a fixture where they match would let a bug that
+ * confuses the two pass unnoticed.
+ */
+declare function makeVercelPageviews(byDate: Record<string, number>, visitors?: number): VercelPageviews;
 /** A Sanity fake that also records the GROQ it was asked to run. */
 interface FakeSanityClient extends SanityQueryClient {
     /** Every query, with its params. Assert against this to prove no PII field was projected. */

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { G as Ga4Client, a as Ga4ReportRequest, S as SanityQueryClient, b as Ga4Report, c as VercelPageviews, V as VercelClient } from './vercel-D19ArNAY.js';
+import { G as Ga4Client, b as Ga4ReportRequest, S as SanityQueryClient, a as Ga4Report, d as VercelPageviews, V as VercelClient } from './vercel-BMEO-Jcw.js';
 
 /**
  * Test doubles and fixture builders for the report layer.
@@ -48,8 +48,14 @@ interface Ga4Script {
 declare function createFakeGa4Client(script?: Ga4Script): FakeGa4Client;
 /** Build a Vercel client fake returning a fixed total. */
 declare function createFakeVercelClient(result: VercelPageviews | Error): VercelClient;
-/** Build a Vercel pageviews fixture. */
-declare function makeVercelPageviews(byDate: Record<string, number>): VercelPageviews;
+/**
+ * Build a Vercel pageviews fixture.
+ *
+ * `visitors` defaults to roughly two thirds of pageviews rather than to the pageview total,
+ * because they are genuinely different numbers — a fixture where they match would let a bug that
+ * confuses the two pass unnoticed.
+ */
+declare function makeVercelPageviews(byDate: Record<string, number>, visitors?: number): VercelPageviews;
 /** A Sanity fake that also records the GROQ it was asked to run. */
 interface FakeSanityClient extends SanityQueryClient {
     /** Every query, with its params. Assert against this to prove no PII field was projected. */

package/dist/testing.js

@@ -74,10 +74,12 @@ function createFakeVercelClient(result) {
     }
   };
 }
-function makeVercelPageviews(byDate) {
+function makeVercelPageviews(byDate, visitors) {
+  const total = Object.values(byDate).reduce((sum, n) => sum + n, 0);
   return {
     byDate,
-    total: Object.values(byDate).reduce((sum, n) => sum + n, 0)
+    total,
+    visitors: visitors ?? Math.round(total * 0.66)
   };
 }
 function createFakeSanityClient(respond) {

package/dist/testing.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/testing.ts","../src/testing/fakes.ts"],"sourcesContent":["/**\n * Testing entry point — test doubles for the report layer.\n *\n * Behind its own subpath so these never reach a production server or Studio bundle, while still\n * being available to a consuming site that wants to exercise these reports before it has\n * credentials to point at.\n *\n *   import { createFakeGa4Client } from '@liiift-studio/sanity-visitor-insights/testing'\n */\n\nexport * from './testing/fakes'\n","/**\n * Test doubles and fixture builders for the report layer.\n *\n * The reports are thin wrappers over three upstreams, but the reasoning inside them — which\n * absence means \"unavailable\" rather than zero, which ratios may be computed at all, which source\n * failure is allowed to degrade which figure — is exactly the part that silently corrupts a\n * dashboard. That reasoning needs to be exercised without credentials, so these fakes stand in for\n * GA4, Vercel and Sanity and record what they were asked.\n *\n * Exported from the package (not just used internally) so a consuming site can drive the same\n * fakes in its own integration tests before wiring real credentials.\n */\n\nimport type { Ga4Client, Ga4Report, Ga4ReportRequest, Ga4Row } from '../server/ga4'\nimport type { VercelClient, VercelPageviews } from '../server/vercel'\nimport type { SanityQueryClient } from '../server/orders'\n\n/** Build a GA4 report fixture from plain rows. */\nexport function makeGa4Report(\n\trows: Array<{ dimensions?: string[]; metrics: number[] }>,\n\toptions: { thresholded?: boolean; sampled?: boolean } = {},\n): Ga4Report {\n\tconst parsed: Ga4Row[] = rows.map((row) => ({\n\t\tdimensions: row.dimensions ?? [],\n\t\tmetrics: row.metrics,\n\t}))\n\n\treturn {\n\t\trows: parsed,\n\t\tthresholded: options.thresholded ?? false,\n\t\tsampled: options.sampled ?? false,\n\t\trowCount: parsed.length,\n\t}\n}\n\n/** Shorthand for a single-metric, single-row report — the common case. */\nexport function makeGa4Total(total: number): Ga4Report {\n\treturn makeGa4Report([{ metrics: [total] }])\n}\n\n/** A GA4 fake that also records what it was asked. */\nexport interface FakeGa4Client extends Ga4Client {\n\t/** Every batchRunReports call, as arrays of requests. */\n\tbatchCalls: Ga4ReportRequest[][]\n\t/** Every runReport call. */\n\tsingleCalls: Ga4ReportRequest[]\n}\n\n/** Script controlling what the GA4 fake returns. */\nexport interface Ga4Script {\n\t/** Handles batchRunReports. Receives the requests, returns one report per request. */\n\tbatch?: (requests: Ga4ReportRequest[]) => Ga4Report[]\n\t/** Handles runReport. */\n\tsingle?: (request: Ga4ReportRequest) => Ga4Report\n\t/** When set, every call rejects with this error instead. */\n\tfailWith?: Error\n}\n\n/**\n * Build a GA4 client fake.\n *\n * Unhandled calls return an empty report rather than throwing, so a test only has to script the\n * behaviour it actually cares about.\n */\nexport function createFakeGa4Client(script: Ga4Script = {}): FakeGa4Client {\n\tconst batchCalls: Ga4ReportRequest[][] = []\n\tconst singleCalls: Ga4ReportRequest[] = []\n\n\treturn {\n\t\tbatchCalls,\n\t\tsingleCalls,\n\n\t\tasync batchRunReports(requests) {\n\t\t\tbatchCalls.push(requests)\n\t\t\tif (script.failWith) throw script.failWith\n\t\t\tif (script.batch) return script.batch(requests)\n\t\t\treturn requests.map(() => makeGa4Report([]))\n\t\t},\n\n\t\tasync runReport(request) {\n\t\t\tsingleCalls.push(request)\n\t\t\tif (script.failWith) throw script.failWith\n\t\t\tif (script.single) return script.single(request)\n\t\t\treturn makeGa4Report([])\n\t\t},\n\t}\n}\n\n/** Build a Vercel client fake returning a fixed total. */\nexport function createFakeVercelClient(\n\tresult: VercelPageviews | Error,\n): VercelClient {\n\treturn {\n\t\tasync pageviews() {\n\t\t\tif (result instanceof Error) throw result\n\t\t\treturn result\n\t\t},\n\t}\n}\n\n/** Build a Vercel pageviews fixture. */\nexport function makeVercelPageviews(byDate: Record<string, number>): VercelPageviews {\n\treturn {\n\t\tbyDate,\n\t\ttotal: Object.values(byDate).reduce((sum, n) => sum + n, 0),\n\t}\n}\n\n/** A Sanity fake that also records the GROQ it was asked to run. */\nexport interface FakeSanityClient extends SanityQueryClient {\n\t/** Every query, with its params. Assert against this to prove no PII field was projected. */\n\tqueries: Array<{ query: string; params?: Record<string, unknown> }>\n}\n\n/**\n * Build a Sanity client fake.\n *\n * @param respond - returns the documents for a given query, or throws to simulate failure\n */\nexport function createFakeSanityClient(respond: (query: string) => unknown): FakeSanityClient {\n\tconst queries: Array<{ query: string; params?: Record<string, unknown> }> = []\n\n\treturn {\n\t\tqueries,\n\t\tasync fetch<T>(query: string, params?: Record<string, unknown>): Promise<T> {\n\t\t\tqueries.push({ query, params })\n\t\t\treturn respond(query) as T\n\t\t},\n\t}\n}\n\n/** Build order documents at given dates, in the shape the safe projection returns. */\nexport function makeOrders(dates: string[]): Array<{ _createdAt: string; orderStatus: string }> {\n\treturn dates.map((date) => ({ _createdAt: `${date}T12:00:00Z`, orderStatus: 'complete' }))\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACkBO,SAAS,cACf,MACA,UAAwD,CAAC,GAC7C;AACZ,QAAM,SAAmB,KAAK,IAAI,CAAC,SAAS;AAAA,IAC3C,YAAY,IAAI,cAAc,CAAC;AAAA,IAC/B,SAAS,IAAI;AAAA,EACd,EAAE;AAEF,SAAO;AAAA,IACN,MAAM;AAAA,IACN,aAAa,QAAQ,eAAe;AAAA,IACpC,SAAS,QAAQ,WAAW;AAAA,IAC5B,UAAU,OAAO;AAAA,EAClB;AACD;AAGO,SAAS,aAAa,OAA0B;AACtD,SAAO,cAAc,CAAC,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC;AAC5C;AA0BO,SAAS,oBAAoB,SAAoB,CAAC,GAAkB;AAC1E,QAAM,aAAmC,CAAC;AAC1C,QAAM,cAAkC,CAAC;AAEzC,SAAO;AAAA,IACN;AAAA,IACA;AAAA,IAEA,MAAM,gBAAgB,UAAU;AAC/B,iBAAW,KAAK,QAAQ;AACxB,UAAI,OAAO,SAAU,OAAM,OAAO;AAClC,UAAI,OAAO,MAAO,QAAO,OAAO,MAAM,QAAQ;AAC9C,aAAO,SAAS,IAAI,MAAM,cAAc,CAAC,CAAC,CAAC;AAAA,IAC5C;AAAA,IAEA,MAAM,UAAU,SAAS;AACxB,kBAAY,KAAK,OAAO;AACxB,UAAI,OAAO,SAAU,OAAM,OAAO;AAClC,UAAI,OAAO,OAAQ,QAAO,OAAO,OAAO,OAAO;AAC/C,aAAO,cAAc,CAAC,CAAC;AAAA,IACxB;AAAA,EACD;AACD;AAGO,SAAS,uBACf,QACe;AACf,SAAO;AAAA,IACN,MAAM,YAAY;AACjB,UAAI,kBAAkB,MAAO,OAAM;AACnC,aAAO;AAAA,IACR;AAAA,EACD;AACD;AAGO,SAAS,oBAAoB,QAAiD;AACpF,SAAO;AAAA,IACN;AAAA,IACA,OAAO,OAAO,OAAO,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,MAAM,GAAG,CAAC;AAAA,EAC3D;AACD;AAaO,SAAS,uBAAuB,SAAuD;AAC7F,QAAM,UAAsE,CAAC;AAE7E,SAAO;AAAA,IACN;AAAA,IACA,MAAM,MAAS,OAAe,QAA8C;AAC3E,cAAQ,KAAK,EAAE,OAAO,OAAO,CAAC;AAC9B,aAAO,QAAQ,KAAK;AAAA,IACrB;AAAA,EACD;AACD;AAGO,SAAS,WAAW,OAAqE;AAC/F,SAAO,MAAM,IAAI,CAAC,UAAU,EAAE,YAAY,GAAG,IAAI,cAAc,aAAa,WAAW,EAAE;AAC1F;","names":[]}
+{"version":3,"sources":["../src/testing.ts","../src/testing/fakes.ts"],"sourcesContent":["/**\n * Testing entry point — test doubles for the report layer.\n *\n * Behind its own subpath so these never reach a production server or Studio bundle, while still\n * being available to a consuming site that wants to exercise these reports before it has\n * credentials to point at.\n *\n *   import { createFakeGa4Client } from '@liiift-studio/sanity-visitor-insights/testing'\n */\n\nexport * from './testing/fakes'\n","/**\n * Test doubles and fixture builders for the report layer.\n *\n * The reports are thin wrappers over three upstreams, but the reasoning inside them — which\n * absence means \"unavailable\" rather than zero, which ratios may be computed at all, which source\n * failure is allowed to degrade which figure — is exactly the part that silently corrupts a\n * dashboard. That reasoning needs to be exercised without credentials, so these fakes stand in for\n * GA4, Vercel and Sanity and record what they were asked.\n *\n * Exported from the package (not just used internally) so a consuming site can drive the same\n * fakes in its own integration tests before wiring real credentials.\n */\n\nimport type { Ga4Client, Ga4Report, Ga4ReportRequest, Ga4Row } from '../server/ga4'\nimport type { VercelClient, VercelPageviews } from '../server/vercel'\nimport type { SanityQueryClient } from '../server/orders'\n\n/** Build a GA4 report fixture from plain rows. */\nexport function makeGa4Report(\n\trows: Array<{ dimensions?: string[]; metrics: number[] }>,\n\toptions: { thresholded?: boolean; sampled?: boolean } = {},\n): Ga4Report {\n\tconst parsed: Ga4Row[] = rows.map((row) => ({\n\t\tdimensions: row.dimensions ?? [],\n\t\tmetrics: row.metrics,\n\t}))\n\n\treturn {\n\t\trows: parsed,\n\t\tthresholded: options.thresholded ?? false,\n\t\tsampled: options.sampled ?? false,\n\t\trowCount: parsed.length,\n\t}\n}\n\n/** Shorthand for a single-metric, single-row report — the common case. */\nexport function makeGa4Total(total: number): Ga4Report {\n\treturn makeGa4Report([{ metrics: [total] }])\n}\n\n/** A GA4 fake that also records what it was asked. */\nexport interface FakeGa4Client extends Ga4Client {\n\t/** Every batchRunReports call, as arrays of requests. */\n\tbatchCalls: Ga4ReportRequest[][]\n\t/** Every runReport call. */\n\tsingleCalls: Ga4ReportRequest[]\n}\n\n/** Script controlling what the GA4 fake returns. */\nexport interface Ga4Script {\n\t/** Handles batchRunReports. Receives the requests, returns one report per request. */\n\tbatch?: (requests: Ga4ReportRequest[]) => Ga4Report[]\n\t/** Handles runReport. */\n\tsingle?: (request: Ga4ReportRequest) => Ga4Report\n\t/** When set, every call rejects with this error instead. */\n\tfailWith?: Error\n}\n\n/**\n * Build a GA4 client fake.\n *\n * Unhandled calls return an empty report rather than throwing, so a test only has to script the\n * behaviour it actually cares about.\n */\nexport function createFakeGa4Client(script: Ga4Script = {}): FakeGa4Client {\n\tconst batchCalls: Ga4ReportRequest[][] = []\n\tconst singleCalls: Ga4ReportRequest[] = []\n\n\treturn {\n\t\tbatchCalls,\n\t\tsingleCalls,\n\n\t\tasync batchRunReports(requests) {\n\t\t\tbatchCalls.push(requests)\n\t\t\tif (script.failWith) throw script.failWith\n\t\t\tif (script.batch) return script.batch(requests)\n\t\t\treturn requests.map(() => makeGa4Report([]))\n\t\t},\n\n\t\tasync runReport(request) {\n\t\t\tsingleCalls.push(request)\n\t\t\tif (script.failWith) throw script.failWith\n\t\t\tif (script.single) return script.single(request)\n\t\t\treturn makeGa4Report([])\n\t\t},\n\t}\n}\n\n/** Build a Vercel client fake returning a fixed total. */\nexport function createFakeVercelClient(\n\tresult: VercelPageviews | Error,\n): VercelClient {\n\treturn {\n\t\tasync pageviews() {\n\t\t\tif (result instanceof Error) throw result\n\t\t\treturn result\n\t\t},\n\t}\n}\n\n/**\n * Build a Vercel pageviews fixture.\n *\n * `visitors` defaults to roughly two thirds of pageviews rather than to the pageview total,\n * because they are genuinely different numbers — a fixture where they match would let a bug that\n * confuses the two pass unnoticed.\n */\nexport function makeVercelPageviews(byDate: Record<string, number>, visitors?: number): VercelPageviews {\n\tconst total = Object.values(byDate).reduce((sum, n) => sum + n, 0)\n\treturn {\n\t\tbyDate,\n\t\ttotal,\n\t\tvisitors: visitors ?? Math.round(total * 0.66),\n\t}\n}\n\n/** A Sanity fake that also records the GROQ it was asked to run. */\nexport interface FakeSanityClient extends SanityQueryClient {\n\t/** Every query, with its params. Assert against this to prove no PII field was projected. */\n\tqueries: Array<{ query: string; params?: Record<string, unknown> }>\n}\n\n/**\n * Build a Sanity client fake.\n *\n * @param respond - returns the documents for a given query, or throws to simulate failure\n */\nexport function createFakeSanityClient(respond: (query: string) => unknown): FakeSanityClient {\n\tconst queries: Array<{ query: string; params?: Record<string, unknown> }> = []\n\n\treturn {\n\t\tqueries,\n\t\tasync fetch<T>(query: string, params?: Record<string, unknown>): Promise<T> {\n\t\t\tqueries.push({ query, params })\n\t\t\treturn respond(query) as T\n\t\t},\n\t}\n}\n\n/** Build order documents at given dates, in the shape the safe projection returns. */\nexport function makeOrders(dates: string[]): Array<{ _createdAt: string; orderStatus: string }> {\n\treturn dates.map((date) => ({ _createdAt: `${date}T12:00:00Z`, orderStatus: 'complete' }))\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACkBO,SAAS,cACf,MACA,UAAwD,CAAC,GAC7C;AACZ,QAAM,SAAmB,KAAK,IAAI,CAAC,SAAS;AAAA,IAC3C,YAAY,IAAI,cAAc,CAAC;AAAA,IAC/B,SAAS,IAAI;AAAA,EACd,EAAE;AAEF,SAAO;AAAA,IACN,MAAM;AAAA,IACN,aAAa,QAAQ,eAAe;AAAA,IACpC,SAAS,QAAQ,WAAW;AAAA,IAC5B,UAAU,OAAO;AAAA,EAClB;AACD;AAGO,SAAS,aAAa,OAA0B;AACtD,SAAO,cAAc,CAAC,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC;AAC5C;AA0BO,SAAS,oBAAoB,SAAoB,CAAC,GAAkB;AAC1E,QAAM,aAAmC,CAAC;AAC1C,QAAM,cAAkC,CAAC;AAEzC,SAAO;AAAA,IACN;AAAA,IACA;AAAA,IAEA,MAAM,gBAAgB,UAAU;AAC/B,iBAAW,KAAK,QAAQ;AACxB,UAAI,OAAO,SAAU,OAAM,OAAO;AAClC,UAAI,OAAO,MAAO,QAAO,OAAO,MAAM,QAAQ;AAC9C,aAAO,SAAS,IAAI,MAAM,cAAc,CAAC,CAAC,CAAC;AAAA,IAC5C;AAAA,IAEA,MAAM,UAAU,SAAS;AACxB,kBAAY,KAAK,OAAO;AACxB,UAAI,OAAO,SAAU,OAAM,OAAO;AAClC,UAAI,OAAO,OAAQ,QAAO,OAAO,OAAO,OAAO;AAC/C,aAAO,cAAc,CAAC,CAAC;AAAA,IACxB;AAAA,EACD;AACD;AAGO,SAAS,uBACf,QACe;AACf,SAAO;AAAA,IACN,MAAM,YAAY;AACjB,UAAI,kBAAkB,MAAO,OAAM;AACnC,aAAO;AAAA,IACR;AAAA,EACD;AACD;AASO,SAAS,oBAAoB,QAAgC,UAAoC;AACvG,QAAM,QAAQ,OAAO,OAAO,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,MAAM,GAAG,CAAC;AACjE,SAAO;AAAA,IACN;AAAA,IACA;AAAA,IACA,UAAU,YAAY,KAAK,MAAM,QAAQ,IAAI;AAAA,EAC9C;AACD;AAaO,SAAS,uBAAuB,SAAuD;AAC7F,QAAM,UAAsE,CAAC;AAE7E,SAAO;AAAA,IACN;AAAA,IACA,MAAM,MAAS,OAAe,QAA8C;AAC3E,cAAQ,KAAK,EAAE,OAAO,OAAO,CAAC;AAC9B,aAAO,QAAQ,KAAK;AAAA,IACrB;AAAA,EACD;AACD;AAGO,SAAS,WAAW,OAAqE;AAC/F,SAAO,MAAM,IAAI,CAAC,UAAU,EAAE,YAAY,GAAG,IAAI,cAAc,aAAa,WAAW,EAAE;AAC1F;","names":[]}

package/dist/testing.mjs

@@ -42,10 +42,12 @@ function createFakeVercelClient(result) {
     }
   };
 }
-function makeVercelPageviews(byDate) {
+function makeVercelPageviews(byDate, visitors) {
+  const total = Object.values(byDate).reduce((sum, n) => sum + n, 0);
   return {
     byDate,
-    total: Object.values(byDate).reduce((sum, n) => sum + n, 0)
+    total,
+    visitors: visitors ?? Math.round(total * 0.66)
   };
 }
 function createFakeSanityClient(respond) {

package/dist/testing.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/testing/fakes.ts"],"sourcesContent":["/**\n * Test doubles and fixture builders for the report layer.\n *\n * The reports are thin wrappers over three upstreams, but the reasoning inside them — which\n * absence means \"unavailable\" rather than zero, which ratios may be computed at all, which source\n * failure is allowed to degrade which figure — is exactly the part that silently corrupts a\n * dashboard. That reasoning needs to be exercised without credentials, so these fakes stand in for\n * GA4, Vercel and Sanity and record what they were asked.\n *\n * Exported from the package (not just used internally) so a consuming site can drive the same\n * fakes in its own integration tests before wiring real credentials.\n */\n\nimport type { Ga4Client, Ga4Report, Ga4ReportRequest, Ga4Row } from '../server/ga4'\nimport type { VercelClient, VercelPageviews } from '../server/vercel'\nimport type { SanityQueryClient } from '../server/orders'\n\n/** Build a GA4 report fixture from plain rows. */\nexport function makeGa4Report(\n\trows: Array<{ dimensions?: string[]; metrics: number[] }>,\n\toptions: { thresholded?: boolean; sampled?: boolean } = {},\n): Ga4Report {\n\tconst parsed: Ga4Row[] = rows.map((row) => ({\n\t\tdimensions: row.dimensions ?? [],\n\t\tmetrics: row.metrics,\n\t}))\n\n\treturn {\n\t\trows: parsed,\n\t\tthresholded: options.thresholded ?? false,\n\t\tsampled: options.sampled ?? false,\n\t\trowCount: parsed.length,\n\t}\n}\n\n/** Shorthand for a single-metric, single-row report — the common case. */\nexport function makeGa4Total(total: number): Ga4Report {\n\treturn makeGa4Report([{ metrics: [total] }])\n}\n\n/** A GA4 fake that also records what it was asked. */\nexport interface FakeGa4Client extends Ga4Client {\n\t/** Every batchRunReports call, as arrays of requests. */\n\tbatchCalls: Ga4ReportRequest[][]\n\t/** Every runReport call. */\n\tsingleCalls: Ga4ReportRequest[]\n}\n\n/** Script controlling what the GA4 fake returns. */\nexport interface Ga4Script {\n\t/** Handles batchRunReports. Receives the requests, returns one report per request. */\n\tbatch?: (requests: Ga4ReportRequest[]) => Ga4Report[]\n\t/** Handles runReport. */\n\tsingle?: (request: Ga4ReportRequest) => Ga4Report\n\t/** When set, every call rejects with this error instead. */\n\tfailWith?: Error\n}\n\n/**\n * Build a GA4 client fake.\n *\n * Unhandled calls return an empty report rather than throwing, so a test only has to script the\n * behaviour it actually cares about.\n */\nexport function createFakeGa4Client(script: Ga4Script = {}): FakeGa4Client {\n\tconst batchCalls: Ga4ReportRequest[][] = []\n\tconst singleCalls: Ga4ReportRequest[] = []\n\n\treturn {\n\t\tbatchCalls,\n\t\tsingleCalls,\n\n\t\tasync batchRunReports(requests) {\n\t\t\tbatchCalls.push(requests)\n\t\t\tif (script.failWith) throw script.failWith\n\t\t\tif (script.batch) return script.batch(requests)\n\t\t\treturn requests.map(() => makeGa4Report([]))\n\t\t},\n\n\t\tasync runReport(request) {\n\t\t\tsingleCalls.push(request)\n\t\t\tif (script.failWith) throw script.failWith\n\t\t\tif (script.single) return script.single(request)\n\t\t\treturn makeGa4Report([])\n\t\t},\n\t}\n}\n\n/** Build a Vercel client fake returning a fixed total. */\nexport function createFakeVercelClient(\n\tresult: VercelPageviews | Error,\n): VercelClient {\n\treturn {\n\t\tasync pageviews() {\n\t\t\tif (result instanceof Error) throw result\n\t\t\treturn result\n\t\t},\n\t}\n}\n\n/** Build a Vercel pageviews fixture. */\nexport function makeVercelPageviews(byDate: Record<string, number>): VercelPageviews {\n\treturn {\n\t\tbyDate,\n\t\ttotal: Object.values(byDate).reduce((sum, n) => sum + n, 0),\n\t}\n}\n\n/** A Sanity fake that also records the GROQ it was asked to run. */\nexport interface FakeSanityClient extends SanityQueryClient {\n\t/** Every query, with its params. Assert against this to prove no PII field was projected. */\n\tqueries: Array<{ query: string; params?: Record<string, unknown> }>\n}\n\n/**\n * Build a Sanity client fake.\n *\n * @param respond - returns the documents for a given query, or throws to simulate failure\n */\nexport function createFakeSanityClient(respond: (query: string) => unknown): FakeSanityClient {\n\tconst queries: Array<{ query: string; params?: Record<string, unknown> }> = []\n\n\treturn {\n\t\tqueries,\n\t\tasync fetch<T>(query: string, params?: Record<string, unknown>): Promise<T> {\n\t\t\tqueries.push({ query, params })\n\t\t\treturn respond(query) as T\n\t\t},\n\t}\n}\n\n/** Build order documents at given dates, in the shape the safe projection returns. */\nexport function makeOrders(dates: string[]): Array<{ _createdAt: string; orderStatus: string }> {\n\treturn dates.map((date) => ({ _createdAt: `${date}T12:00:00Z`, orderStatus: 'complete' }))\n}\n"],"mappings":";AAkBO,SAAS,cACf,MACA,UAAwD,CAAC,GAC7C;AACZ,QAAM,SAAmB,KAAK,IAAI,CAAC,SAAS;AAAA,IAC3C,YAAY,IAAI,cAAc,CAAC;AAAA,IAC/B,SAAS,IAAI;AAAA,EACd,EAAE;AAEF,SAAO;AAAA,IACN,MAAM;AAAA,IACN,aAAa,QAAQ,eAAe;AAAA,IACpC,SAAS,QAAQ,WAAW;AAAA,IAC5B,UAAU,OAAO;AAAA,EAClB;AACD;AAGO,SAAS,aAAa,OAA0B;AACtD,SAAO,cAAc,CAAC,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC;AAC5C;AA0BO,SAAS,oBAAoB,SAAoB,CAAC,GAAkB;AAC1E,QAAM,aAAmC,CAAC;AAC1C,QAAM,cAAkC,CAAC;AAEzC,SAAO;AAAA,IACN;AAAA,IACA;AAAA,IAEA,MAAM,gBAAgB,UAAU;AAC/B,iBAAW,KAAK,QAAQ;AACxB,UAAI,OAAO,SAAU,OAAM,OAAO;AAClC,UAAI,OAAO,MAAO,QAAO,OAAO,MAAM,QAAQ;AAC9C,aAAO,SAAS,IAAI,MAAM,cAAc,CAAC,CAAC,CAAC;AAAA,IAC5C;AAAA,IAEA,MAAM,UAAU,SAAS;AACxB,kBAAY,KAAK,OAAO;AACxB,UAAI,OAAO,SAAU,OAAM,OAAO;AAClC,UAAI,OAAO,OAAQ,QAAO,OAAO,OAAO,OAAO;AAC/C,aAAO,cAAc,CAAC,CAAC;AAAA,IACxB;AAAA,EACD;AACD;AAGO,SAAS,uBACf,QACe;AACf,SAAO;AAAA,IACN,MAAM,YAAY;AACjB,UAAI,kBAAkB,MAAO,OAAM;AACnC,aAAO;AAAA,IACR;AAAA,EACD;AACD;AAGO,SAAS,oBAAoB,QAAiD;AACpF,SAAO;AAAA,IACN;AAAA,IACA,OAAO,OAAO,OAAO,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,MAAM,GAAG,CAAC;AAAA,EAC3D;AACD;AAaO,SAAS,uBAAuB,SAAuD;AAC7F,QAAM,UAAsE,CAAC;AAE7E,SAAO;AAAA,IACN;AAAA,IACA,MAAM,MAAS,OAAe,QAA8C;AAC3E,cAAQ,KAAK,EAAE,OAAO,OAAO,CAAC;AAC9B,aAAO,QAAQ,KAAK;AAAA,IACrB;AAAA,EACD;AACD;AAGO,SAAS,WAAW,OAAqE;AAC/F,SAAO,MAAM,IAAI,CAAC,UAAU,EAAE,YAAY,GAAG,IAAI,cAAc,aAAa,WAAW,EAAE;AAC1F;","names":[]}
+{"version":3,"sources":["../src/testing/fakes.ts"],"sourcesContent":["/**\n * Test doubles and fixture builders for the report layer.\n *\n * The reports are thin wrappers over three upstreams, but the reasoning inside them — which\n * absence means \"unavailable\" rather than zero, which ratios may be computed at all, which source\n * failure is allowed to degrade which figure — is exactly the part that silently corrupts a\n * dashboard. That reasoning needs to be exercised without credentials, so these fakes stand in for\n * GA4, Vercel and Sanity and record what they were asked.\n *\n * Exported from the package (not just used internally) so a consuming site can drive the same\n * fakes in its own integration tests before wiring real credentials.\n */\n\nimport type { Ga4Client, Ga4Report, Ga4ReportRequest, Ga4Row } from '../server/ga4'\nimport type { VercelClient, VercelPageviews } from '../server/vercel'\nimport type { SanityQueryClient } from '../server/orders'\n\n/** Build a GA4 report fixture from plain rows. */\nexport function makeGa4Report(\n\trows: Array<{ dimensions?: string[]; metrics: number[] }>,\n\toptions: { thresholded?: boolean; sampled?: boolean } = {},\n): Ga4Report {\n\tconst parsed: Ga4Row[] = rows.map((row) => ({\n\t\tdimensions: row.dimensions ?? [],\n\t\tmetrics: row.metrics,\n\t}))\n\n\treturn {\n\t\trows: parsed,\n\t\tthresholded: options.thresholded ?? false,\n\t\tsampled: options.sampled ?? false,\n\t\trowCount: parsed.length,\n\t}\n}\n\n/** Shorthand for a single-metric, single-row report — the common case. */\nexport function makeGa4Total(total: number): Ga4Report {\n\treturn makeGa4Report([{ metrics: [total] }])\n}\n\n/** A GA4 fake that also records what it was asked. */\nexport interface FakeGa4Client extends Ga4Client {\n\t/** Every batchRunReports call, as arrays of requests. */\n\tbatchCalls: Ga4ReportRequest[][]\n\t/** Every runReport call. */\n\tsingleCalls: Ga4ReportRequest[]\n}\n\n/** Script controlling what the GA4 fake returns. */\nexport interface Ga4Script {\n\t/** Handles batchRunReports. Receives the requests, returns one report per request. */\n\tbatch?: (requests: Ga4ReportRequest[]) => Ga4Report[]\n\t/** Handles runReport. */\n\tsingle?: (request: Ga4ReportRequest) => Ga4Report\n\t/** When set, every call rejects with this error instead. */\n\tfailWith?: Error\n}\n\n/**\n * Build a GA4 client fake.\n *\n * Unhandled calls return an empty report rather than throwing, so a test only has to script the\n * behaviour it actually cares about.\n */\nexport function createFakeGa4Client(script: Ga4Script = {}): FakeGa4Client {\n\tconst batchCalls: Ga4ReportRequest[][] = []\n\tconst singleCalls: Ga4ReportRequest[] = []\n\n\treturn {\n\t\tbatchCalls,\n\t\tsingleCalls,\n\n\t\tasync batchRunReports(requests) {\n\t\t\tbatchCalls.push(requests)\n\t\t\tif (script.failWith) throw script.failWith\n\t\t\tif (script.batch) return script.batch(requests)\n\t\t\treturn requests.map(() => makeGa4Report([]))\n\t\t},\n\n\t\tasync runReport(request) {\n\t\t\tsingleCalls.push(request)\n\t\t\tif (script.failWith) throw script.failWith\n\t\t\tif (script.single) return script.single(request)\n\t\t\treturn makeGa4Report([])\n\t\t},\n\t}\n}\n\n/** Build a Vercel client fake returning a fixed total. */\nexport function createFakeVercelClient(\n\tresult: VercelPageviews | Error,\n): VercelClient {\n\treturn {\n\t\tasync pageviews() {\n\t\t\tif (result instanceof Error) throw result\n\t\t\treturn result\n\t\t},\n\t}\n}\n\n/**\n * Build a Vercel pageviews fixture.\n *\n * `visitors` defaults to roughly two thirds of pageviews rather than to the pageview total,\n * because they are genuinely different numbers — a fixture where they match would let a bug that\n * confuses the two pass unnoticed.\n */\nexport function makeVercelPageviews(byDate: Record<string, number>, visitors?: number): VercelPageviews {\n\tconst total = Object.values(byDate).reduce((sum, n) => sum + n, 0)\n\treturn {\n\t\tbyDate,\n\t\ttotal,\n\t\tvisitors: visitors ?? Math.round(total * 0.66),\n\t}\n}\n\n/** A Sanity fake that also records the GROQ it was asked to run. */\nexport interface FakeSanityClient extends SanityQueryClient {\n\t/** Every query, with its params. Assert against this to prove no PII field was projected. */\n\tqueries: Array<{ query: string; params?: Record<string, unknown> }>\n}\n\n/**\n * Build a Sanity client fake.\n *\n * @param respond - returns the documents for a given query, or throws to simulate failure\n */\nexport function createFakeSanityClient(respond: (query: string) => unknown): FakeSanityClient {\n\tconst queries: Array<{ query: string; params?: Record<string, unknown> }> = []\n\n\treturn {\n\t\tqueries,\n\t\tasync fetch<T>(query: string, params?: Record<string, unknown>): Promise<T> {\n\t\t\tqueries.push({ query, params })\n\t\t\treturn respond(query) as T\n\t\t},\n\t}\n}\n\n/** Build order documents at given dates, in the shape the safe projection returns. */\nexport function makeOrders(dates: string[]): Array<{ _createdAt: string; orderStatus: string }> {\n\treturn dates.map((date) => ({ _createdAt: `${date}T12:00:00Z`, orderStatus: 'complete' }))\n}\n"],"mappings":";AAkBO,SAAS,cACf,MACA,UAAwD,CAAC,GAC7C;AACZ,QAAM,SAAmB,KAAK,IAAI,CAAC,SAAS;AAAA,IAC3C,YAAY,IAAI,cAAc,CAAC;AAAA,IAC/B,SAAS,IAAI;AAAA,EACd,EAAE;AAEF,SAAO;AAAA,IACN,MAAM;AAAA,IACN,aAAa,QAAQ,eAAe;AAAA,IACpC,SAAS,QAAQ,WAAW;AAAA,IAC5B,UAAU,OAAO;AAAA,EAClB;AACD;AAGO,SAAS,aAAa,OAA0B;AACtD,SAAO,cAAc,CAAC,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC;AAC5C;AA0BO,SAAS,oBAAoB,SAAoB,CAAC,GAAkB;AAC1E,QAAM,aAAmC,CAAC;AAC1C,QAAM,cAAkC,CAAC;AAEzC,SAAO;AAAA,IACN;AAAA,IACA;AAAA,IAEA,MAAM,gBAAgB,UAAU;AAC/B,iBAAW,KAAK,QAAQ;AACxB,UAAI,OAAO,SAAU,OAAM,OAAO;AAClC,UAAI,OAAO,MAAO,QAAO,OAAO,MAAM,QAAQ;AAC9C,aAAO,SAAS,IAAI,MAAM,cAAc,CAAC,CAAC,CAAC;AAAA,IAC5C;AAAA,IAEA,MAAM,UAAU,SAAS;AACxB,kBAAY,KAAK,OAAO;AACxB,UAAI,OAAO,SAAU,OAAM,OAAO;AAClC,UAAI,OAAO,OAAQ,QAAO,OAAO,OAAO,OAAO;AAC/C,aAAO,cAAc,CAAC,CAAC;AAAA,IACxB;AAAA,EACD;AACD;AAGO,SAAS,uBACf,QACe;AACf,SAAO;AAAA,IACN,MAAM,YAAY;AACjB,UAAI,kBAAkB,MAAO,OAAM;AACnC,aAAO;AAAA,IACR;AAAA,EACD;AACD;AASO,SAAS,oBAAoB,QAAgC,UAAoC;AACvG,QAAM,QAAQ,OAAO,OAAO,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,MAAM,GAAG,CAAC;AACjE,SAAO;AAAA,IACN;AAAA,IACA;AAAA,IACA,UAAU,YAAY,KAAK,MAAM,QAAQ,IAAI;AAAA,EAC9C;AACD;AAaO,SAAS,uBAAuB,SAAuD;AAC7F,QAAM,UAAsE,CAAC;AAE7E,SAAO;AAAA,IACN;AAAA,IACA,MAAM,MAAS,OAAe,QAA8C;AAC3E,cAAQ,KAAK,EAAE,OAAO,OAAO,CAAC;AAC9B,aAAO,QAAQ,KAAK;AAAA,IACrB;AAAA,EACD;AACD;AAGO,SAAS,WAAW,OAAqE;AAC/F,SAAO,MAAM,IAAI,CAAC,UAAU,EAAE,YAAY,GAAG,IAAI,cAAc,aAAa,WAAW,EAAE;AAC1F;","names":[]}

package/dist/vercel-BMEO-Jcw.d.mts

@@ -0,0 +1,123 @@
+/** What this module needs from a Sanity client — kept minimal so it is trivial to stub in tests. */
+interface SanityQueryClient {
+    fetch<T>(query: string, params?: Record<string, unknown>): Promise<T>;
+}
+
+/**
+ * Service-account access tokens for the GA4 Data API.
+ *
+ * Implemented directly against Google's OAuth2 token endpoint rather than through `googleapis`,
+ * which is a very large dependency to pull into a package that only needs one grant type. Signing
+ * a JWT with node:crypto keeps the dependency surface at zero and removes any risk of a
+ * credential-bearing SDK being reachable from the Studio entry point.
+ */
+/** The parts of a service-account JSON key this module uses. */
+interface ServiceAccountKey {
+    client_email: string;
+    private_key: string;
+}
+/**
+ * Parse a service-account key from an environment variable.
+ *
+ * Accepts either raw JSON or base64-encoded JSON, because multi-line JSON with embedded newlines
+ * is awkward to set in some dashboards and gets mangled often enough to be worth tolerating both.
+ *
+ * @param raw - the environment variable's value
+ * @returns the parsed key, or null when unset or unparseable
+ */
+declare function parseServiceAccountKey(raw: string | undefined): ServiceAccountKey | null;
+
+/**
+ * GA4 Data API client.
+ *
+ * Only `runReport` and `batchRunReports` are used. `runFunnelReport` is deliberately not called:
+ * it is an alpha surface with its own stricter quota, and it returns step-conversion marginals
+ * rather than observed paths — drawing a flow diagram from it would imply co-occurrence that was
+ * never measured. The journey report approximates instead, and says so.
+ */
+
+/** A GA4 report request, narrowed to the fields this package sets. */
+interface Ga4ReportRequest {
+    dimensions?: Array<{
+        name: string;
+    }>;
+    metrics?: Array<{
+        name: string;
+    }>;
+    dateRanges: Array<{
+        startDate: string;
+        endDate: string;
+    }>;
+    dimensionFilter?: unknown;
+    orderBys?: unknown;
+    limit?: number;
+    keepEmptyRows?: boolean;
+}
+/** A parsed report row: dimension values and metric values, positionally aligned to the request. */
+interface Ga4Row {
+    dimensions: string[];
+    metrics: number[];
+}
+/** A parsed GA4 report. */
+interface Ga4Report {
+    rows: Ga4Row[];
+    /** True when GA4 withheld rows for privacy thresholding — totals are then incomplete. */
+    thresholded: boolean;
+    /** True when GA4 answered from a sample rather than the full data set. */
+    sampled: boolean;
+    /** Total row count GA4 reports, which may exceed rows returned when a limit applied. */
+    rowCount: number;
+    /**
+     * The property's configured timezone, as GA4 reports it. Worth capturing because every range
+     * is anchored to the timezone in site config, and a mismatch silently shifts day boundaries.
+     */
+    timeZone?: string;
+}
+/** A GA4 client bound to one property. */
+interface Ga4Client {
+    runReport(request: Ga4ReportRequest): Promise<Ga4Report>;
+    batchRunReports(requests: Ga4ReportRequest[]): Promise<Ga4Report[]>;
+}
+/**
+ * Build a GA4 client for one property.
+ *
+ * @param propertyId - numeric GA4 property id
+ * @param key - service-account key with Viewer on that property
+ */
+declare function createGa4Client(propertyId: string, key: ServiceAccountKey): Ga4Client;
+
+/**
+ * Vercel Web Analytics client.
+ *
+ * Uses the documented Web Analytics query API under `/v1/query/web-analytics/visits/*`. An earlier
+ * version of this file guessed at `/v1/web-analytics/timeseries`, which does not exist and returned
+ * 404 for every project — indistinguishable, from the outside, from the feature being switched off.
+ * That mistake is why `unavailable` carries a reason: a 404 here now surfaces as a source error to
+ * be investigated rather than as an absence of traffic.
+ *
+ * Vercel is counted purely as a second, cookieless pageview measurement. It is never treated as
+ * ground truth, and never subtracted from a GA4 session count — those are different units.
+ *
+ * Note the API defaults to the production environment only, which is what the reports want.
+ */
+/** Daily pageview counts, keyed by ISO date. */
+interface VercelPageviews {
+    byDate: Record<string, number>;
+    total: number;
+    /** Distinct visitors over the whole range. Not a sum of the daily figures — visitors dedupe. */
+    visitors: number;
+}
+/** A Vercel client bound to one project. */
+interface VercelClient {
+    pageviews(start: string, end: string): Promise<VercelPageviews>;
+}
+/**
+ * Build a Vercel Web Analytics client.
+ *
+ * @param projectId - the Vercel project id
+ * @param token - a Vercel API token with read access to that project
+ * @param teamId - team scope, required when the project belongs to a team
+ */
+declare function createVercelClient(projectId: string, token: string, teamId?: string): VercelClient;
+
+export { type Ga4Client as G, type SanityQueryClient as S, type VercelClient as V, type Ga4Report as a, type Ga4ReportRequest as b, type ServiceAccountKey as c, type VercelPageviews as d, createGa4Client as e, createVercelClient as f, parseServiceAccountKey as p };

package/dist/vercel-BMEO-Jcw.d.ts

@@ -0,0 +1,123 @@
+/** What this module needs from a Sanity client — kept minimal so it is trivial to stub in tests. */
+interface SanityQueryClient {
+    fetch<T>(query: string, params?: Record<string, unknown>): Promise<T>;
+}
+
+/**
+ * Service-account access tokens for the GA4 Data API.
+ *
+ * Implemented directly against Google's OAuth2 token endpoint rather than through `googleapis`,
+ * which is a very large dependency to pull into a package that only needs one grant type. Signing
+ * a JWT with node:crypto keeps the dependency surface at zero and removes any risk of a
+ * credential-bearing SDK being reachable from the Studio entry point.
+ */
+/** The parts of a service-account JSON key this module uses. */
+interface ServiceAccountKey {
+    client_email: string;
+    private_key: string;
+}
+/**
+ * Parse a service-account key from an environment variable.
+ *
+ * Accepts either raw JSON or base64-encoded JSON, because multi-line JSON with embedded newlines
+ * is awkward to set in some dashboards and gets mangled often enough to be worth tolerating both.
+ *
+ * @param raw - the environment variable's value
+ * @returns the parsed key, or null when unset or unparseable
+ */
+declare function parseServiceAccountKey(raw: string | undefined): ServiceAccountKey | null;
+
+/**
+ * GA4 Data API client.
+ *
+ * Only `runReport` and `batchRunReports` are used. `runFunnelReport` is deliberately not called:
+ * it is an alpha surface with its own stricter quota, and it returns step-conversion marginals
+ * rather than observed paths — drawing a flow diagram from it would imply co-occurrence that was
+ * never measured. The journey report approximates instead, and says so.
+ */
+
+/** A GA4 report request, narrowed to the fields this package sets. */
+interface Ga4ReportRequest {
+    dimensions?: Array<{
+        name: string;
+    }>;
+    metrics?: Array<{
+        name: string;
+    }>;
+    dateRanges: Array<{
+        startDate: string;
+        endDate: string;
+    }>;
+    dimensionFilter?: unknown;
+    orderBys?: unknown;
+    limit?: number;
+    keepEmptyRows?: boolean;
+}
+/** A parsed report row: dimension values and metric values, positionally aligned to the request. */
+interface Ga4Row {
+    dimensions: string[];
+    metrics: number[];
+}
+/** A parsed GA4 report. */
+interface Ga4Report {
+    rows: Ga4Row[];
+    /** True when GA4 withheld rows for privacy thresholding — totals are then incomplete. */
+    thresholded: boolean;
+    /** True when GA4 answered from a sample rather than the full data set. */
+    sampled: boolean;
+    /** Total row count GA4 reports, which may exceed rows returned when a limit applied. */
+    rowCount: number;
+    /**
+     * The property's configured timezone, as GA4 reports it. Worth capturing because every range
+     * is anchored to the timezone in site config, and a mismatch silently shifts day boundaries.
+     */
+    timeZone?: string;
+}
+/** A GA4 client bound to one property. */
+interface Ga4Client {
+    runReport(request: Ga4ReportRequest): Promise<Ga4Report>;
+    batchRunReports(requests: Ga4ReportRequest[]): Promise<Ga4Report[]>;
+}
+/**
+ * Build a GA4 client for one property.
+ *
+ * @param propertyId - numeric GA4 property id
+ * @param key - service-account key with Viewer on that property
+ */
+declare function createGa4Client(propertyId: string, key: ServiceAccountKey): Ga4Client;
+
+/**
+ * Vercel Web Analytics client.
+ *
+ * Uses the documented Web Analytics query API under `/v1/query/web-analytics/visits/*`. An earlier
+ * version of this file guessed at `/v1/web-analytics/timeseries`, which does not exist and returned
+ * 404 for every project — indistinguishable, from the outside, from the feature being switched off.
+ * That mistake is why `unavailable` carries a reason: a 404 here now surfaces as a source error to
+ * be investigated rather than as an absence of traffic.
+ *
+ * Vercel is counted purely as a second, cookieless pageview measurement. It is never treated as
+ * ground truth, and never subtracted from a GA4 session count — those are different units.
+ *
+ * Note the API defaults to the production environment only, which is what the reports want.
+ */
+/** Daily pageview counts, keyed by ISO date. */
+interface VercelPageviews {
+    byDate: Record<string, number>;
+    total: number;
+    /** Distinct visitors over the whole range. Not a sum of the daily figures — visitors dedupe. */
+    visitors: number;
+}
+/** A Vercel client bound to one project. */
+interface VercelClient {
+    pageviews(start: string, end: string): Promise<VercelPageviews>;
+}
+/**
+ * Build a Vercel Web Analytics client.
+ *
+ * @param projectId - the Vercel project id
+ * @param token - a Vercel API token with read access to that project
+ * @param teamId - team scope, required when the project belongs to a team
+ */
+declare function createVercelClient(projectId: string, token: string, teamId?: string): VercelClient;
+
+export { type Ga4Client as G, type SanityQueryClient as S, type VercelClient as V, type Ga4Report as a, type Ga4ReportRequest as b, type ServiceAccountKey as c, type VercelPageviews as d, createGa4Client as e, createVercelClient as f, parseServiceAccountKey as p };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@liiift-studio/sanity-visitor-insights",
-  "version": "0.2.0",
-  "description": "Visitor-behaviour analytics for type-foundry Sanity Studios \u2014 GA4, Vercel and order data reconciled honestly",
+  "version": "0.2.2",
+  "description": "Visitor-behaviour analytics for type-foundry Sanity Studios — GA4, Vercel and order data reconciled honestly",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",

package/src/server/vercel.ts

@@ -1,22 +1,26 @@
 /**
  * Vercel Web Analytics client.
  *
- * Vercel's Web Analytics read API is not a stable, versioned public surface the way the GA4 Data
- * API is, and access depends on plan tier. This client is therefore written to degrade rather than
- * throw: a missing token, an unavailable plan, or a changed endpoint all surface as an unconfigured
- * or errored source in the report envelope, so the Measurement Health panel can say "Vercel did not
- * answer" instead of implying the site had no traffic.
+ * Uses the documented Web Analytics query API under `/v1/query/web-analytics/visits/*`. An earlier
+ * version of this file guessed at `/v1/web-analytics/timeseries`, which does not exist and returned
+ * 404 for every project — indistinguishable, from the outside, from the feature being switched off.
+ * That mistake is why `unavailable` carries a reason: a 404 here now surfaces as a source error to
+ * be investigated rather than as an absence of traffic.
  *
- * Vercel is counted here purely as a second, cookieless pageview measurement. It is never treated
- * as ground truth, and never subtracted from a GA4 session count — those are different units.
+ * Vercel is counted purely as a second, cookieless pageview measurement. It is never treated as
+ * ground truth, and never subtracted from a GA4 session count — those are different units.
+ *
+ * Note the API defaults to the production environment only, which is what the reports want.
  */
 
-const API_BASE = 'https://api.vercel.com'
+const API_BASE = 'https://api.vercel.com/v1/query/web-analytics'
 
 /** Daily pageview counts, keyed by ISO date. */
 export interface VercelPageviews {
 	byDate: Record<string, number>
 	total: number
+	/** Distinct visitors over the whole range. Not a sum of the daily figures — visitors dedupe. */
+	visitors: number
 }
 
 /** A Vercel client bound to one project. */
@@ -24,6 +28,13 @@ export interface VercelClient {
 	pageviews(start: string, end: string): Promise<VercelPageviews>
 }
 
+/** Shape of the aggregate response rows. */
+interface AggregateRow {
+	timestamp?: string
+	pageviews?: number
+	visitors?: number
+}
+
 /**
  * Build a Vercel Web Analytics client.
  *
@@ -32,37 +43,52 @@ export interface VercelClient {
  * @param teamId - team scope, required when the project belongs to a team
  */
 export function createVercelClient(projectId: string, token: string, teamId?: string): VercelClient {
-	return {
-		async pageviews(start, end) {
-			const params = new URLSearchParams({
-				projectId,
-				since: `${start}T00:00:00.000Z`,
-				until: `${end}T23:59:59.999Z`,
-			})
-			if (teamId) params.set('teamId', teamId)
+	async function query<T>(path: string, extra: Record<string, string>): Promise<T> {
+		const params = new URLSearchParams({ projectId, ...extra })
+		if (teamId) params.set('teamId', teamId)
 
-			const response = await fetch(`${API_BASE}/v1/web-analytics/timeseries?${params.toString()}`, {
-				headers: { Authorization: `Bearer ${token}` },
-			})
+		const response = await fetch(`${API_BASE}/${path}?${params.toString()}`, {
+			headers: { Authorization: `Bearer ${token}` },
+		})
 
-			if (!response.ok) {
-				throw new Error(`Vercel Web Analytics failed with ${response.status}`)
-			}
+		if (!response.ok) {
+			// 404 here means the endpoint or project is wrong, or Web Analytics is not enabled —
+			// the status is the only useful detail, and the body can echo the request.
+			throw new Error(`Vercel Web Analytics ${path} failed with ${response.status}`)
+		}
 
-			const body = (await response.json()) as { data?: Array<{ key?: string; total?: number; devices?: number }> }
-			const byDate: Record<string, number> = {}
-			let total = 0
+		return (await response.json()) as T
+	}
+
+	return {
+		async pageviews(start, end) {
+			// Two calls on purpose. The count endpoint gives range totals with visitors deduped
+			// across the whole window; summing the daily rows would overcount visitors, because a
+			// person returning on three days is three daily visitors but one range visitor.
+			const [totals, series] = await Promise.all([
+				query<{ data?: { pageviews?: number; visitors?: number } }>('visits/count', {
+					since: start,
+					until: end,
+				}),
+				query<{ data?: AggregateRow[] }>('visits/aggregate', {
+					since: start,
+					until: end,
+					by: 'day',
+					limit: '100',
+				}),
+			])
 
-			for (const point of body.data ?? []) {
-				if (!point.key) continue
-				// `key` is a timestamp or date string depending on granularity; normalise to a date.
-				const date = point.key.slice(0, 10)
-				const count = typeof point.total === 'number' ? point.total : 0
-				byDate[date] = (byDate[date] ?? 0) + count
-				total += count
+			const byDate: Record<string, number> = {}
+			for (const row of series.data ?? []) {
+				if (!row.timestamp) continue
+				byDate[row.timestamp.slice(0, 10)] = row.pageviews ?? 0
 			}
 
-			return { byDate, total }
+			return {
+				byDate,
+				total: totals.data?.pageviews ?? 0,
+				visitors: totals.data?.visitors ?? 0,
+			}
 		},
 	}
 }

package/src/server.ts

@@ -20,6 +20,12 @@ export type { TypefaceInterestData, TypefaceInterestRow } from './server/reports
 export { JOURNEY_STEPS } from './server/reports/journey'
 export { DESIGN_INDUSTRY_SOURCES } from './server/reports/acquisition'
 export { runDiagnostics, type DiagnosticsInput } from './server/diagnostics'
+
+// Client constructors. Needed to call runDiagnostics headlessly, which the README documents —
+// without these exported that example could not actually be written.
+export { createGa4Client, type Ga4Client, type Ga4Report, type Ga4ReportRequest } from './server/ga4'
+export { createVercelClient, type VercelClient, type VercelPageviews } from './server/vercel'
+export { parseServiceAccountKey, type ServiceAccountKey } from './server/googleAuth'
 export type { CheckStatus, DiagnosticCheck, DiagnosticReport } from './reportData'
 
 // Shared contract, re-exported so the server entry is self-sufficient.

package/src/testing/fakes.ts

@@ -98,11 +98,19 @@ export function createFakeVercelClient(
 	}
 }
 
-/** Build a Vercel pageviews fixture. */
-export function makeVercelPageviews(byDate: Record<string, number>): VercelPageviews {
+/**
+ * Build a Vercel pageviews fixture.
+ *
+ * `visitors` defaults to roughly two thirds of pageviews rather than to the pageview total,
+ * because they are genuinely different numbers — a fixture where they match would let a bug that
+ * confuses the two pass unnoticed.
+ */
+export function makeVercelPageviews(byDate: Record<string, number>, visitors?: number): VercelPageviews {
+	const total = Object.values(byDate).reduce((sum, n) => sum + n, 0)
 	return {
 		byDate,
-		total: Object.values(byDate).reduce((sum, n) => sum + n, 0),
+		total,
+		visitors: visitors ?? Math.round(total * 0.66),
 	}
 }
 

package/dist/vercel-D19ArNAY.d.mts

@@ -1,80 +0,0 @@
-/** What this module needs from a Sanity client — kept minimal so it is trivial to stub in tests. */
-interface SanityQueryClient {
-    fetch<T>(query: string, params?: Record<string, unknown>): Promise<T>;
-}
-
-/**
- * GA4 Data API client.
- *
- * Only `runReport` and `batchRunReports` are used. `runFunnelReport` is deliberately not called:
- * it is an alpha surface with its own stricter quota, and it returns step-conversion marginals
- * rather than observed paths — drawing a flow diagram from it would imply co-occurrence that was
- * never measured. The journey report approximates instead, and says so.
- */
-
-/** A GA4 report request, narrowed to the fields this package sets. */
-interface Ga4ReportRequest {
-    dimensions?: Array<{
-        name: string;
-    }>;
-    metrics?: Array<{
-        name: string;
-    }>;
-    dateRanges: Array<{
-        startDate: string;
-        endDate: string;
-    }>;
-    dimensionFilter?: unknown;
-    orderBys?: unknown;
-    limit?: number;
-    keepEmptyRows?: boolean;
-}
-/** A parsed report row: dimension values and metric values, positionally aligned to the request. */
-interface Ga4Row {
-    dimensions: string[];
-    metrics: number[];
-}
-/** A parsed GA4 report. */
-interface Ga4Report {
-    rows: Ga4Row[];
-    /** True when GA4 withheld rows for privacy thresholding — totals are then incomplete. */
-    thresholded: boolean;
-    /** True when GA4 answered from a sample rather than the full data set. */
-    sampled: boolean;
-    /** Total row count GA4 reports, which may exceed rows returned when a limit applied. */
-    rowCount: number;
-    /**
-     * The property's configured timezone, as GA4 reports it. Worth capturing because every range
-     * is anchored to the timezone in site config, and a mismatch silently shifts day boundaries.
-     */
-    timeZone?: string;
-}
-/** A GA4 client bound to one property. */
-interface Ga4Client {
-    runReport(request: Ga4ReportRequest): Promise<Ga4Report>;
-    batchRunReports(requests: Ga4ReportRequest[]): Promise<Ga4Report[]>;
-}
-
-/**
- * Vercel Web Analytics client.
- *
- * Vercel's Web Analytics read API is not a stable, versioned public surface the way the GA4 Data
- * API is, and access depends on plan tier. This client is therefore written to degrade rather than
- * throw: a missing token, an unavailable plan, or a changed endpoint all surface as an unconfigured
- * or errored source in the report envelope, so the Measurement Health panel can say "Vercel did not
- * answer" instead of implying the site had no traffic.
- *
- * Vercel is counted here purely as a second, cookieless pageview measurement. It is never treated
- * as ground truth, and never subtracted from a GA4 session count — those are different units.
- */
-/** Daily pageview counts, keyed by ISO date. */
-interface VercelPageviews {
-    byDate: Record<string, number>;
-    total: number;
-}
-/** A Vercel client bound to one project. */
-interface VercelClient {
-    pageviews(start: string, end: string): Promise<VercelPageviews>;
-}
-
-export type { Ga4Client as G, SanityQueryClient as S, VercelClient as V, Ga4ReportRequest as a, Ga4Report as b, VercelPageviews as c };