@liiift-studio/sanity-visitor-insights 0.1.0

package/dist/server.d.ts

@@ -0,0 +1,280 @@
+import { S as SiteAnalyticsConfig, M as MetricValue } from './ranges-D6AZwpmm.js';
+export { k as ConfigProblem, C as Coverage, D as DateRange, E as EventCutover, G as GA4_PROCESSING_LAG_DAYS, l as Ga4Config, O as OrdersConfig, P as PREEXISTING, c as REPORT_NAMES, b as RangeKey, R as ReportEnvelope, d as ReportError, a as ReportName, e as SourceName, f as SourceStatus, U as UnavailableReason, V as VercelConfig, m as applyCoverage, n as assertValidSiteConfig, g as coverageForRange, q as coverageNotices, s as daysBetween, t as formatInTimeZone, i as isReportName, w as isValidTimeZone, o as ok, p as partial, h as previousRange, x as provisionalDates, y as provisionalNotice, r as resolveRange, z as shiftDays, u as unavailable, v as validateSiteConfig, j as valueOrNull } from './ranges-D6AZwpmm.js';
+
+/**
+ * Request authentication and CORS for the report handler.
+ *
+ * The Studio forwards its own Sanity session token and this verifies it against Sanity. A shared
+ * secret was the obvious alternative and is the wrong one: the Studio bundle is served publicly, so
+ * any secret compiled into it is extractable, which moves the bar from "know the URL" to "open
+ * devtools". Verifying a session token instead proves the caller is a logged-in project user, and
+ * gives a real identity to log rather than an anonymous caller who read a constant.
+ *
+ * This mirrors the pattern already in production on Darden's order-action endpoints.
+ */
+/** Minimal shape this module needs from a Next.js API request. */
+interface HandlerRequest {
+    method?: string;
+    url?: string;
+    headers: Record<string, string | string[] | undefined>;
+    query?: Record<string, string | string[] | undefined>;
+}
+/** Minimal shape this module needs from a Next.js API response. */
+interface HandlerResponse {
+    setHeader(name: string, value: string): void;
+    status(code: number): HandlerResponse;
+    json(body: unknown): void;
+    end(): void;
+}
+/** A verified Sanity Studio user. */
+interface StudioUser {
+    id: string;
+    name?: string;
+    email?: string;
+    roles?: Array<{
+        name: string;
+    }>;
+}
+/** Outcome of verifying a request's Studio token. */
+type VerifyResult = {
+    ok: true;
+    user: StudioUser;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Verify that a request carries a valid Sanity user token for this project.
+ *
+ * @param req - the incoming request
+ * @param sanityProjectId - project the token must belong to
+ * @returns ok with the resolved user, or a reason suitable for logging but never for the response
+ */
+declare function verifyStudioRequest(req: HandlerRequest, sanityProjectId: string): Promise<VerifyResult>;
+/**
+ * Apply CORS headers for a Studio-originated request and answer the preflight.
+ *
+ * Echoes one allow-listed origin rather than sending `*`. A wildcard is acceptable for public HTML
+ * but not for an endpoint that takes an Authorization header and returns business data.
+ *
+ * @param req - the incoming request
+ * @param res - the response to decorate
+ * @param allowedOrigins - exact origins permitted to call cross-origin
+ * @returns true when the request was a preflight and is now fully answered
+ */
+declare function applyCors(req: HandlerRequest, res: HandlerResponse, allowedOrigins: readonly string[]): boolean;
+/**
+ * Guard a report endpoint. Responds 401 and returns null when the caller cannot be verified.
+ *
+ * @returns the verified user, or null when the request has already been answered with a 401
+ */
+declare function requireStudioUser(req: HandlerRequest, res: HandlerResponse, sanityProjectId: string): Promise<StudioUser | null>;
+
+/** 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>;
+}
+
+/**
+ * The mountable Next.js API-route handler.
+ *
+ * Ships from this package rather than being copy-pasted into each site so the three foundries
+ * cannot drift apart: a fix applied here reaches all of them on a version bump, instead of being
+ * applied to one repo and forgotten in the other two. A consuming site's route is then:
+ *
+ *   // pages/api/visitor-insights/[report].js
+ *   import { createVisitorInsightsHandler } from '@liiift-studio/sanity-visitor-insights/server'
+ *   export default createVisitorInsightsHandler({ config: mySiteConfig })
+ *
+ * Credentials are read from the environment inside this module and never leave the server.
+ */
+
+/** Environment variables this handler reads. Names are fixed so all three sites match. */
+declare const ENV_VARS: {
+    /** Service-account JSON (raw or base64) with Viewer on the GA4 property. */
+    readonly googleServiceAccount: "VISITOR_INSIGHTS_GA4_SERVICE_ACCOUNT";
+    /** Vercel API token with read access to the project. */
+    readonly vercelToken: "VISITOR_INSIGHTS_VERCEL_TOKEN";
+};
+/** Options for building a handler. */
+interface HandlerOptions {
+    /** This site's description of itself. */
+    config: SiteAnalyticsConfig;
+    /**
+     * Sanity client used for order counts. Supply the site's existing server-side client so this
+     * package does not need its own Sanity credentials.
+     */
+    sanityClient?: SanityQueryClient;
+    /** Sanity project id used to verify Studio tokens. Defaults to `SANITY_STUDIO_PROJECT_ID`. */
+    sanityProjectId?: string;
+    /** Cache lifetime for report responses. */
+    cacheTtlMs?: number;
+}
+/**
+ * Build the API-route handler for a site.
+ *
+ * @param options - the site config and its Sanity client
+ * @returns a Next.js Pages Router API handler
+ */
+declare function createVisitorInsightsHandler(options: HandlerOptions): (req: HandlerRequest, res: HandlerResponse) => Promise<void>;
+
+/** Empty the cache. Test seam, and useful after a config change. */
+declare function clearCache(): void;
+
+/**
+ * Report result shapes, shared by the server that produces them and the panels that render them.
+ *
+ * These live outside both entry points on purpose. If the panels imported them from
+ * `src/server/reports/*` — even as `import type`, which does erase at build time — the module
+ * graph would still contain a client-to-server edge, and the guarantee that credential-reading
+ * code cannot reach a Studio bundle would rest on a compiler detail rather than on structure.
+ */
+
+/** How much of reality each source sees. Pageviews compare like with like; the rest is context. */
+interface MeasurementHealthData {
+    /** GA4 pageviews — directly comparable to `vercelPageviews`. */
+    ga4Pageviews: MetricValue;
+    /** Vercel pageviews — cookieless, not consent-gated. */
+    vercelPageviews: MetricValue;
+    /**
+     * Vercel minus GA4 pageviews, as a share of Vercel. Positive means GA4 saw less.
+     * Null when either side is unavailable — never computed against a missing operand.
+     */
+    shortfallRatio: number | null;
+    /** GA4 sessions. Context only: a session is not a pageview and is never subtracted from one. */
+    ga4Sessions: MetricValue;
+    /** Orders in range. Ground truth for conversions, shown as context. */
+    orders: MetricValue;
+    /** Share of sessions that granted consent, where the event exists. */
+    consentRate: MetricValue;
+    /** Plain-language reading of the numbers above, for a non-analyst audience. */
+    interpretation: string;
+}
+/** One acquisition source. */
+interface SourceRow {
+    /** GA4 `sessionSource` value. */
+    source: string;
+    /** GA4 `sessionDefaultChannelGroup`, e.g. Organic Search. */
+    channel: string;
+    sessions: number;
+    /** True when this source is one of the design-industry referrers. */
+    designIndustry: boolean;
+    /** True for GA4's `(not set)` / `(direct)` style buckets, which are not real sources. */
+    unattributed: boolean;
+}
+/** Where visitors came from. */
+interface AcquisitionData {
+    rows: SourceRow[];
+    totalSessions: number;
+    /** Sessions from design-industry referrers, as a share of the total. */
+    designIndustryShare: number | null;
+    /** Sessions GA4 could not attribute, as a share of the total. */
+    unattributedShare: number | null;
+    /** True when GA4 withheld low-count rows, so the tail is shorter than reality. */
+    rowsWithheld: boolean;
+}
+/** One rung of the funnel. */
+interface JourneyStep {
+    key: string;
+    label: string;
+    event: string;
+    count: MetricValue;
+    /**
+     * Share of the previous measurable step that reached this one.
+     * Null when either end is unavailable — a drop-off across an unmeasured step is meaningless.
+     */
+    conversionFromPrevious: number | null;
+}
+/** A page where sessions commonly ended. */
+interface ExitPage {
+    path: string;
+    exits: number;
+}
+/** How far visitors get. Per-step totals, never an observed path. */
+interface JourneyData {
+    steps: JourneyStep[];
+    topExitPages: ExitPage[];
+    /** Always true. The UI must not present these steps as a tracked journey. */
+    approximate: true;
+    /** Why it is approximate, in words the panel can show directly. */
+    approximationNote: string;
+}
+/** One family's interest figures. */
+interface TypefaceInterestRow {
+    typeface: string;
+    viewed: MetricValue;
+    tested: MetricValue;
+    bought: MetricValue;
+    /** Tested divided by viewed. Null unless both are real numbers. */
+    testRate: number | null;
+}
+/** Viewed, tested and bought, by family. */
+interface TypefaceInterestData {
+    rows: TypefaceInterestRow[];
+    /** Stated in the response so the UI cannot omit it. */
+    interpretationNote: string;
+    /** True when GA4 withheld low-count rows, so quiet families may be missing entirely. */
+    rowsWithheld: boolean;
+}
+
+/**
+ * Acquisition — where visitors come from.
+ *
+ * Design-industry referrers are pulled out as a named segment rather than left in a generic
+ * referrer table. A visit from Fonts In Use or Typewolf is a pre-qualified, industry-literate
+ * visitor and behaves nothing like average organic traffic; burying those rows among search and
+ * social discards the distinction a foundry actually acts on.
+ *
+ * `(not set)` rows are surfaced rather than swept into "other". On a type-foundry site they can be
+ * a large share — bookmarked visits, stripped referrers, AI crawlers — and hiding them makes the
+ * table look more complete than it is.
+ */
+
+/** Referrer hosts that identify a design-industry source worth tracking separately. */
+declare const DESIGN_INDUSTRY_SOURCES: readonly ["fontsinuse.com", "typewolf.com", "typographica.org", "fonts.google.com", "behance.net", "dribbble.com", "itsnicethat.com"];
+
+/**
+ * Journey — how far visitors get, and where they stop.
+ *
+ * This is an ordered step funnel, not a path graph, and that is a deliberate limit rather than a
+ * simplification. GA4's Data API has no path-exploration endpoint; Path Exploration is a UI-only
+ * feature. What is available is per-event totals and `runFunnelReport`, an alpha surface that
+ * returns step-conversion marginals — not observed sequences. Rendering ribbons from marginals
+ * would assert that a given visitor went A to B to C when no such co-occurrence was ever measured.
+ *
+ * So each step is reported as its own honest total, adjacent drop-off is derived between steps, and
+ * the response is explicitly flagged as an approximation for the UI to display.
+ *
+ * A step whose event is not instrumented on this site reports as unavailable, never as zero. On a
+ * site missing `begin_checkout`, the cart-to-checkout drop-off is not "100% drop-off" — it is
+ * unmeasured, and the two must not look alike.
+ */
+
+/** The funnel, in order. Each entry names the GA4 event that evidences the step. */
+declare const JOURNEY_STEPS: readonly [{
+    readonly key: "landed";
+    readonly label: "Landed";
+    readonly event: "page_view";
+}, {
+    readonly key: "viewed_typeface";
+    readonly label: "Viewed a typeface";
+    readonly event: "view_item";
+}, {
+    readonly key: "tested";
+    readonly label: "Used the type tester";
+    readonly event: "tester_engaged";
+}, {
+    readonly key: "added_to_cart";
+    readonly label: "Added to cart";
+    readonly event: "add_to_cart";
+}, {
+    readonly key: "began_checkout";
+    readonly label: "Began checkout";
+    readonly event: "begin_checkout";
+}, {
+    readonly key: "purchased";
+    readonly label: "Purchased";
+    readonly event: "purchase";
+}];
+
+export { type AcquisitionData, DESIGN_INDUSTRY_SOURCES, ENV_VARS, type ExitPage, type HandlerOptions, type HandlerRequest, type HandlerResponse, JOURNEY_STEPS, type JourneyData, type JourneyStep, type MeasurementHealthData, MetricValue, type SanityQueryClient, SiteAnalyticsConfig, type SourceRow, type StudioUser, type TypefaceInterestData, type TypefaceInterestRow, applyCors, clearCache, createVisitorInsightsHandler, requireStudioUser, verifyStudioRequest };