Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,8 @@ The source of truth for [scientfactory.com](https://scientfactory.com), includin
- [`ScientFactory/scient-desktop`](https://github.com/ScientFactory/scient-desktop)
owns the desktop application and its releases.
- [`ScientFactory/scient-agent`](https://github.com/ScientFactory/scient-agent)
is the planned home for future native Scient-agent work. Its current
OpenCode-derived starting repository is not yet an implemented native-agent
foundation.
owns Scient Agent, the native research agent built from Oh My Pi that the
desktop application installs and runs.
- [`ScientFactory/ScientFactory-website`](https://github.com/ScientFactory/ScientFactory-website)
owns this website and download experience.

Expand Down Expand Up @@ -118,13 +117,17 @@ Cloudflare D1 stores four website event types:

Before a visitor chooses analytics, and after choosing **Essential only**, every event receives a new event-specific identifier. Those counts represent events rather than unique people. After explicit **Allow analytics** consent, the site sets a random first-party visitor identifier and creates a session identifier so visits, downloads, sessions, and return behavior can be measured. The identity is not derived from an IP address, browser fingerprint, email address, advertising identifier, referrer, or third-party account. `download_failed` is limited to a failure in ScientFactory's redirect service; the website cannot observe a transfer failure after GitHub begins serving an installer.

Each visit also records where it came from: the referring site's host (never its full address) and the link's `utm_source`, `utm_medium` and `utm_campaign` tags. The browser keeps them for the tab and sends them once on the visit's first page view, and the site's download links carry them with the page the download was clicked on. A download link on another site is credited to that site's host. Values that look like an address or an email are dropped.

Downloads made directly from GitHub never reach this site. Once a day the events Worker saves GitHub's running total for each release file in `github_release_downloads`. GitHub counts every fetch: Mac `.dmg` files are installs only and Mac updates fetch the `.zip`, but Windows `.exe` and Linux `.AppImage` totals also include updates that fell back to GitHub from the update mirror. A token in the optional `GITHUB_TOKEN` Worker secret only raises GitHub's rate limit.

The production binding is `DOWNLOAD_DB`, backed by the `scientfactory-downloads` D1 database. New events use the shared `analytics_events` table; the earlier `site_events` table remains as read-only historical data. Apply new migrations before deploying code that depends on them:

```sh
bun run db:migrate
```

To view the lifetime event summary plus 30-day identity, consent, session, download, outbound-link, and failure breakdowns:
To view the lifetime event summary plus 30-day identity, consent, session, download (by source, campaign, place and network, and GitHub's totals), outbound-link, and failure breakdowns:

```sh
bun run analytics:report
Expand Down
11 changes: 5 additions & 6 deletions functions/_lib/analyticsPeople.ts
Original file line number Diff line number Diff line change
Expand Up @@ -180,15 +180,14 @@ export function webObservationStatement(
occurredAt: string,
visitorId: string,
request: Request,
/** The site the visit came from; the request's own Referer is usually this website. */
sourceHost: string | null = null,
): D1PreparedStatement | null {
const network = networkObservation(request);
if (!network) return null;
let referrer: string | null = null;
try {
referrer = new URL(request.headers.get("Referer") ?? "").hostname;
} catch {
/* optional */
}
// The request's own Referer is this website (the page that sent the event), so only the
// visit's source, or the other site whose download link was followed, is recorded.
const referrer = sourceHost;
return db
.prepare(`INSERT OR IGNORE INTO analytics_web_sightings
(event_id, event_name, occurred_at, visitor_id, ip_address, referrer_host, country, region, city, timezone, asn, network_name)
Expand Down
14 changes: 12 additions & 2 deletions functions/_lib/events.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import { webObservationStatement } from "./analyticsPeople";
// Layer: Cloudflare Pages Function utility

import { cleanSessionId, websiteIdentity, websiteSessionId } from "./identity";
import type { VisitSource } from "./visitSource";

export const SITE_EVENT_NAMES = [
"page_viewed",
Expand All @@ -14,7 +15,8 @@ export const SITE_EVENT_NAMES = [

export type SiteEventName = (typeof SITE_EVENT_NAMES)[number];

export interface SiteEvent {
/** Page views on landing and downloads also carry where the visit came from. */
export interface SiteEvent extends VisitSource {
readonly eventName: SiteEventName;
readonly pagePath?: string | null;
readonly assetKey?: string | null;
Expand Down Expand Up @@ -64,9 +66,11 @@ function limited(value: string | null | undefined, maximum: number): string | nu
return value.slice(0, maximum);
}

/** A path on this site: never another host (`//host/...`) or anything with an email in it. */
export function cleanPath(value: string | null | undefined): string | null {
if (!value?.startsWith("/")) return null;
if (!value?.startsWith("/") || value.startsWith("//") || value.startsWith("/\\")) return null;
const path = value.split(/[?#]/, 1)[0] ?? "/";
if (path.includes("@")) return null;
return limited(path, 512);
}

Expand Down Expand Up @@ -123,6 +127,11 @@ export async function insertSiteEvent(
upstream_elapsed_ms: event.upstreamElapsedMs ?? null,
upstream_attempts: event.upstreamAttempts ?? null,
fallback: event.fallback ?? null,
referrer_host: limited(event.referrerHost, 253),
utm_source: limited(event.utmSource, 100),
utm_medium: limited(event.utmMedium, 100),
utm_campaign: limited(event.utmCampaign, 100),
landing_path: cleanPath(event.landingPath),
}).filter((entry): entry is [string, string | number] => entry[1] !== null),
);

Expand Down Expand Up @@ -165,6 +174,7 @@ export async function insertSiteEvent(
occurredAt,
distinctId,
request,
event.referrerHost ?? null,
);
if (observation) statements.push(observation);
}
Expand Down
53 changes: 53 additions & 0 deletions functions/_lib/visitSource.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
import { describe, expect, it } from "vitest";

import { cleanCampaignTag, cleanReferrerHost, visitSourceFrom } from "./visitSource";

describe("visit source", () => {
it("keeps a referring site's host and drops this website", () => {
expect(cleanReferrerHost("WWW.Google.com", "scientfactory.com")).toBe("google.com");
expect(cleanReferrerHost("com.google.android.gm", "scientfactory.com")).toBe(
"com.google.android.gm",
);
expect(cleanReferrerHost("www.scientfactory.com", "scientfactory.com")).toBeNull();
expect(cleanReferrerHost("https://google.com/search?q=x", "scientfactory.com")).toBeNull();
expect(cleanReferrerHost(42, "scientfactory.com")).toBeNull();
});

it("keeps short campaign labels and drops addresses and emails", () => {
expect(cleanCampaignTag(" spring-launch_2026 ")).toBe("spring-launch_2026");
expect(cleanCampaignTag("LinkedIn | paid")).toBe("LinkedIn | paid");
expect(cleanCampaignTag("someone@example.com")).toBeNull();
expect(cleanCampaignTag("https://example.com")).toBeNull();
expect(cleanCampaignTag("/private/path")).toBeNull();
expect(cleanCampaignTag("x".repeat(101))).toBeNull();
expect(cleanCampaignTag("example.com/private/path")).toBeNull();
expect(cleanCampaignTag("google.com")).toBe("google.com");
});

it("keeps only paths on this site", () => {
const read = (landing: string) =>
visitSourceFrom((name) => (name === "landing_path" ? landing : null), "scientfactory.com")
.landingPath;
expect(read("/docs/install?x=1")).toBe("/docs/install");
expect(read("//example.com/private")).toBeNull();
expect(read("/\\example.com")).toBeNull();
expect(read("/people/person@example.com")).toBeNull();
});

it("reads every field through the same checks", () => {
const values: Record<string, string> = {
referrer_host: "x.com",
utm_source: "twitter",
utm_medium: "social",
utm_campaign: "bad<script>",
landing_path: "/docs?token=secret",
};
expect(visitSourceFrom((name) => values[name], "scientfactory.com")).toEqual({
referrerHost: "x.com",
utmSource: "twitter",
utmMedium: "social",
utmCampaign: null,
landingPath: "/docs",
});
});
});
55 changes: 55 additions & 0 deletions functions/_lib/visitSource.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
// FILE: visitSource.ts
// Purpose: Where a visit came from: the referring site's host and the link's campaign tags.
// Layer: Cloudflare Pages Function utility

import { cleanPath } from "./events";

export interface VisitSource {
/** The referring site's host, without "www.", never its full address. */
readonly referrerHost?: string | null;
readonly utmSource?: string | null;
readonly utmMedium?: string | null;
readonly utmCampaign?: string | null;
/** The first page of the visit on this site. */
readonly landingPath?: string | null;
}

const HOST_PATTERN =
/^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$/;
// Campaign tags are short labels: no "/" or "@", so an address, a path or an email is dropped.
const TAG_PATTERN = /^[\p{L}\p{N} ._+\-|:]{1,100}$/u;

export function cleanReferrerHost(value: unknown, siteHost: string): string | null {
if (typeof value !== "string") return null;
const host = value
.trim()
.toLowerCase()
.replace(/^www\./, "");
if (!HOST_PATTERN.test(host)) return null;
if (host === siteHost.toLowerCase().replace(/^www\./, "")) return null;
return host;
}

export function cleanCampaignTag(value: unknown): string | null {
if (typeof value !== "string") return null;
const tag = value.trim();
if (!TAG_PATTERN.test(tag)) return null;
return tag;
}

/** Reads a visit source from named values, keeping only what passes the checks above. */
export function visitSourceFrom(
read: (
name: "referrer_host" | "utm_source" | "utm_medium" | "utm_campaign" | "landing_path",
) => unknown,
siteHost: string,
): VisitSource {
const landing = read("landing_path");
return {
referrerHost: cleanReferrerHost(read("referrer_host"), siteHost),
utmSource: cleanCampaignTag(read("utm_source")),
utmMedium: cleanCampaignTag(read("utm_medium")),
utmCampaign: cleanCampaignTag(read("utm_campaign")),
landingPath: typeof landing === "string" ? cleanPath(landing) : null,
};
}
26 changes: 26 additions & 0 deletions functions/_lib/webSighting.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
import { expect, it, vi } from "vitest";

import { webObservationStatement } from "./analyticsPeople";

function sightingReferrer(sourceHost: string | null) {
const bind = vi.fn((..._values: unknown[]) => ({}));
const db = { prepare: vi.fn(() => ({ bind })) } as unknown as D1Database;
const request = new Request("https://scientfactory.com/api/events", {
headers: { "CF-Connecting-IP": "192.0.2.10", Referer: "https://scientfactory.com/about/" },
});
webObservationStatement(
db,
"e1",
"page_viewed",
"2026-11-17T00:00:00Z",
"v1",
request,
sourceHost,
);
return bind.mock.calls[0]?.[5];
}

it("records the visit's source, never this website's own page, as the referrer", () => {
expect(sightingReferrer(null)).toBeNull();
expect(sightingReferrer("google.com")).toBe("google.com");
});
40 changes: 40 additions & 0 deletions functions/api/download/[asset].test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,46 @@ describe("tracked download redirect", () => {
);
});

it("records the page and the visit's source that the site's download link carries", async () => {
const db = createDatabase();
const context = createContext("macArm64", db.database);
(context as { request: Request }).request = new Request(
"https://scientfactory.com/api/download/macArm64?page=/docs/install&referrer_host=news.ycombinator.com&utm_source=hn&utm_campaign=launch&landing_path=/",
);
vi.stubGlobal("fetch", vi.fn<typeof fetch>().mockResolvedValue(handoffResponse()));

const response = await onRequestGet(context);

expect(response.headers.get("Location")).toBe(releaseFixture.assets[0]?.browser_download_url);
await flushWaitUntil(context);
const click = db.bind.mock.calls.find((call) => call[1] === "download_clicked");
expect(JSON.parse(String(click?.[5]))).toMatchObject({
page_path: "/docs/install",
referrer_host: "news.ycombinator.com",
utm_source: "hn",
utm_campaign: "launch",
landing_path: "/",
});
});

it("names the other site when its own link starts the download", async () => {
const db = createDatabase();
const context = createContext("macArm64", db.database);
(context as { request: Request }).request = new Request(
"https://scientfactory.com/api/download/macArm64",
{ headers: { Referer: "https://www.reddit.com/r/science/comments/abc" } },
);
vi.stubGlobal("fetch", vi.fn<typeof fetch>().mockResolvedValue(handoffResponse()));

await onRequestGet(context);
await flushWaitUntil(context);
const click = db.bind.mock.calls.find((call) => call[1] === "download_clicked");
expect(JSON.parse(String(click?.[5]))).toMatchObject({
page_path: "/download",
referrer_host: "reddit.com",
});
});

it("does not let a database failure block a valid redirect", async () => {
vi.spyOn(console, "error").mockImplementation(() => undefined);
const db = createDatabase(vi.fn().mockRejectedValue(new Error("database unavailable")));
Expand Down
33 changes: 30 additions & 3 deletions functions/api/download/[asset].ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ import {
DESKTOP_LATEST_RELEASE_PAGE_URL,
isOfficialDesktopReleaseDownload,
} from "../../../src/lib/release-source";
import { queueSiteEvent } from "../../_lib/events";
import { cleanPath, queueSiteEvent } from "../../_lib/events";
import { cleanReferrerHost, visitSourceFrom, type VisitSource } from "../../_lib/visitSource";
import {
LatestReleaseResolutionError,
resolveLatestDesktopRelease,
Expand Down Expand Up @@ -78,20 +79,45 @@ function redirectResponse(location: string): Response {
});
}

/**
* The site's download links carry the page they were clicked on and where the visit came from
* (`page`, `referrer_host`, `landing_path` and the `utm_*` tags). Links from elsewhere have none.
*/
function downloadOrigin(request: Request): { pagePath: string; source: VisitSource } {
const url = new URL(request.url);
const source = visitSourceFrom((name) => url.searchParams.get(name), url.hostname);
let linkingHost: string | null = null;
try {
// A download link on another site sends that site as the Referer.
linkingHost = cleanReferrerHost(
new URL(request.headers.get("Referer") ?? "").hostname,
url.hostname,
);
} catch {
/* optional */
}
return {
pagePath: cleanPath(url.searchParams.get("page")) ?? "/download",
source: { ...source, referrerHost: source.referrerHost ?? linkingHost },
};
}

async function handleDownload(
context: EventContext<Cloudflare.Env, "asset", unknown>,
track: boolean,
): Promise<Response> {
const key = assetKeyFromContext(context);
if (!key) return new Response("Not found", { status: 404 });
const { pagePath, source } = downloadOrigin(context.request);

try {
const { release, asset } = await resolveDownload(key, context);
if (track) {
const destination = new URL(asset.browser_download_url);
queueSiteEvent(context, {
eventName: "download_clicked",
pagePath: "/download",
pagePath,
...source,
assetKey: key,
releaseTag: release.tag_name,
assetName: asset.name,
Expand All @@ -109,7 +135,8 @@ async function handleDownload(
if (track) {
queueSiteEvent(context, {
eventName: "download_failed",
pagePath: "/download",
pagePath,
...source,
assetKey: key,
failureStage: failure.stage,
failureReason: failure.reason,
Expand Down
Loading