Initial release v0.1.0

Anonymous analytics service for ATProto app views.

- Event collection API
- Stats API endpoints
- Per-app-view API key authentication
- TypeScript client library
- Admin endpoint for API key management

.gitignore

···
+.DS_Store
+.vt/

.vscode/extensions.json

···
+{
+    "recommendations": [
+        "denoland.vscode-deno"
+    ]
+}

.vtignore

···
+.git
+.vscode
+.cursorrules
+.DS_Store
+node_modules
+vendor

AGENTS.md

···
+You are an advanced assistant specialized in generating Val Town code.
+
+## Core Guidelines
+
+- Ask clarifying questions when requirements are ambiguous
+- Provide complete, functional solutions rather than skeleton implementations
+- Test your logic against edge cases before presenting the final solution
+- Ensure all code follows Val Town's specific platform requirements
+- If a section of code that you're working on is getting too complex, consider refactoring it into subcomponents
+
+## Code Standards
+
+- Generate code in TypeScript or TSX
+- Add appropriate TypeScript types and interfaces for all data structures
+- Prefer official SDKs or libraries than writing API calls directly
+- Ask the user to supply API or library documentation if you are at all unsure about it
+- **Never bake in secrets into the code** - always use environment variables
+- Include comments explaining complex logic (avoid commenting obvious operations)
+- Follow modern ES6+ conventions and functional programming practices if possible
+
+## Types of triggers
+
+### 1. HTTP Trigger
+
+- Create web APIs and endpoints
+- Handle HTTP requests and responses
+- Example structure:
+
+```ts
+export default async function (req: Request) {
+  return new Response("Hello World");
+}
+```
+
+Files that are HTTP triggers have http in their name like `foobar.http.tsx`
+
+### 2. Cron Triggers
+
+- Run on a schedule
+- Use cron expressions for timing
+- Example structure:
+
+```ts
+export default async function () {
+  // Scheduled task code
+}
+```
+
+Files that are Cron triggers have cron in their name like `foobar.cron.tsx`
+
+### 3. Email Triggers
+
+- Process incoming emails
+- Handle email-based workflows
+- Example structure:
+
+```ts
+export default async function (email: Email) {
+  // Process email
+}
+```
+
+Files that are Email triggers have email in their name like `foobar.email.tsx`
+
+
+## Val Town Standard Libraries
+
+Val Town provides several hosted services and utility functions.
+
+### Blob Storage
+
+```ts
+import { blob } from "https://esm.town/v/std/blob";
+await blob.setJSON("myKey", { hello: "world" });
+let blobDemo = await blob.getJSON("myKey");
+let appKeys = await blob.list("app_");
+await blob.delete("myKey");
+```
+
+### SQLite
+
+```ts
+import { sqlite } from "https://esm.town/v/stevekrouse/sqlite";
+const TABLE_NAME = 'todo_app_users_2';
+// Create table - do this before usage and change table name when modifying schema
+await sqlite.execute(`CREATE TABLE IF NOT EXISTS ${TABLE_NAME} (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL
+)`);
+// Query data
+const result = await sqlite.execute(`SELECT * FROM ${TABLE_NAME} WHERE id = ?`, [1]);
+```
+
+Note: When changing a SQLite table's schema, change the table's name (e.g., add _2 or _3) to create a fresh table.
+
+### OpenAI
+
+```ts
+import { OpenAI } from "https://esm.town/v/std/openai";
+const openai = new OpenAI();
+const completion = await openai.chat.completions.create({
+  messages: [
+    { role: "user", content: "Say hello in a creative way" },
+  ],
+  model: "gpt-4o-mini",
+  max_tokens: 30,
+});
+```
+
+### Email
+
+```ts
+import { email } from "https://esm.town/v/std/email";
+// By default emails the owner of the val
+await email({ 
+  subject: "Hi",  
+  text: "Hi", 
+  html: "<h1>Hi</h1>"
+});
+```
+
+## Val Town Utility Functions
+
+Val Town provides several utility functions to help with common project tasks.
+
+### Importing Utilities
+
+Always import utilities with version pins to avoid breaking changes:
+
+```ts
+import { parseProject, readFile, serveFile } from "https://esm.town/v/std/utils@85-main/index.ts";
+```
+
+### Available Utilities
+
+
+#### **serveFile** - Serve project files with proper content types
+
+For example, in Hono:
+
+```ts
+// serve all files in frontend/ and shared/
+app.get("/frontend/*", c => serveFile(c.req.path, import.meta.url));
+app.get("/shared/*", c => serveFile(c.req.path, import.meta.url));
+```
+
+#### **readFile** - Read files from within the project:
+
+```ts
+// Read a file from the project
+const fileContent = await readFile("/frontend/index.html", import.meta.url);
+```
+
+#### **listFiles** - List all files in the project
+
+```ts
+const files = await listFiles(import.meta.url);
+```
+
+#### **parseProject** - Extract information about the current project from import.meta.url
+
+This is useful for including info for linking back to a val, ie in "view source" urls:
+
+```ts
+const projectVal = parseProject(import.meta.url);
+console.log(projectVal.username); // Owner of the project
+console.log(projectVal.name);     // Project name
+console.log(projectVal.version);  // Version number
+console.log(projectVal.branch);   // Branch name
+console.log(projectVal.links.self.project); // URL to the project page
+```
+
+However, it's *extremely importing* to note that `parseProject` and other Standard Library utilities ONLY RUN ON THE SERVER.
+If you need access to this data on the client, run it in the server and pass it to the client by splicing it into the HTML page
+or by making an API request for it.
+
+## Val Town Platform Specifics
+
+- **Redirects:** Use `return new Response(null, { status: 302, headers: { Location: "/place/to/redirect" }})` instead of `Response.redirect` which is broken
+- **Images:** Avoid external images or base64 images. Use emojis, unicode symbols, or icon fonts/libraries instead
+- **AI Image:** To inline generate an AI image use: `<img src="https://maxm-imggenurl.web.val.run/the-description-of-your-image" />`
+- **Storage:** DO NOT use the Deno KV module for storage
+- **Browser APIs:** DO NOT use the `alert()`, `prompt()`, or `confirm()` methods
+- **Weather Data:** Use open-meteo for weather data (doesn't require API keys) unless otherwise specified
+- **View Source:** Add a view source link by importing & using `import.meta.url.replace("ems.sh", "val.town)"` (or passing this data to the client) and include `target="_top"` attribute
+- **Error Debugging:** Add `<script src="https://esm.town/v/std/catch"></script>` to HTML to capture client-side errors
+- **Error Handling:** Only use try...catch when there's a clear local resolution; Avoid catches that merely log or return 500s. Let errors bubble up with full context
+- **Environment Variables:** Use `Deno.env.get('keyname')` when you need to, but generally prefer APIs that don't require keys
+- **Imports:** Use `https://esm.sh` for npm and Deno dependencies to ensure compatibility on server and browser
+- **Storage Strategy:** Only use backend storage if explicitly required; prefer simple static client-side sites
+- **React Configuration:** When using React libraries, pin versions with `?deps=react@18.2.0,react-dom@18.2.0` and start the file with `/** @jsxImportSource https://esm.sh/react@18.2.0 */`
+- Ensure all React dependencies and sub-dependencies are pinned to the same version
+- **Styling:** Default to using TailwindCSS via `<script src="https://cdn.twind.style" crossorigin></script>` unless otherwise specified
+
+## Project Structure and Design Patterns
+
+### Recommended Directory Structure
+```
+├── backend/
+│   ├── database/
+│   │   ├── migrations.ts    # Schema definitions
+│   │   ├── queries.ts       # DB query functions
+│   │   └── README.md
+│   └── routes/              # Route modules
+│       ├── [route].ts
+│       └── static.ts        # Static file serving
+│   ├── index.ts             # Main entry point
+│   └── README.md
+├── frontend/
+│   ├── components/
+│   │   ├── App.tsx
+│   │   └── [Component].tsx
+│   ├── favicon.svg
+│   ├── index.html           # Main HTML template
+│   ├── index.tsx            # Frontend JS entry point
+│   ├── README.md
+│   └── style.css
+├── README.md
+└── shared/
+    ├── README.md
+    └── utils.ts             # Shared types and functions
+```
+
+### Backend (Hono) Best Practices
+
+- Hono is the recommended API framework
+- Main entry point should be `backend/index.ts`
+- **Static asset serving:** Use the utility functions to read and serve project files:
+  ```ts
+  import { readFile, serveFile } from "https://esm.town/v/std/utils@85-main/index.ts";
+  
+  // serve all files in frontend/ and shared/
+  app.get("/frontend/*", c => serveFile(c.req.path, import.meta.url));
+  app.get("/shared/*", c => serveFile(c.req.path, import.meta.url));
+  
+  // For index.html, often you'll want to bootstrap with initial data
+  app.get("/", async c => {
+    let html = await readFile("/frontend/index.html", import.meta.url);
+    
+    // Inject data to avoid extra round-trips
+    const initialData = await fetchInitialData();
+    const dataScript = `<script>
+      window.__INITIAL_DATA__ = ${JSON.stringify(initialData)};
+    </script>`;
+    
+    html = html.replace("</head>", `${dataScript}</head>`);
+    return c.html(html);
+  });
+  ```
+- Create RESTful API routes for CRUD operations
+- Always include this snippet at the top-level Hono app to re-throwing errors to see full stack traces:
+  ```ts
+  // Unwrap Hono errors to see original error details
+  app.onError((err, c) => {
+    throw err;
+  });
+  ```
+
+### Database Patterns
+- Run migrations on startup or comment out for performance
+- Change table names when modifying schemas rather than altering
+- Export clear query functions with proper TypeScript typing
+
+## Common Gotchas and Solutions
+
+1. **Environment Limitations:** 
+   - Val Town runs on Deno in a serverless context, not Node.js
+   - Code in `shared/` must work in both frontend and backend environments
+   - Cannot use `Deno` keyword in shared code
+   - Use `https://esm.sh` for imports that work in both environments
+
+2. **SQLite Peculiarities:**
+   - Limited support for ALTER TABLE operations
+   - Create new tables with updated schemas and copy data when needed
+   - Always run table creation before querying
+
+3. **React Configuration:**
+   - All React dependencies must be pinned to 18.2.0
+   - Always include `@jsxImportSource https://esm.sh/react@18.2.0` at the top of React files
+   - Rendering issues often come from mismatched React versions
+
+4. **File Handling:**
+   - Val Town only supports text files, not binary
+   - Use the provided utilities to read files across branches and forks
+   - For files in the project, use `readFile` helpers
+
+5. **API Design:**
+   - `fetch` handler is the entry point for HTTP vals
+   - Run the Hono app with `export default app.fetch // This is the entry point for HTTP vals`
+

CHANGELOG.md

···
+# Changelog
+
+## [0.1.0] - 2025-11-28
+
+Initial release of Driftline Analytics.
+
+### Added
+
+- Event collection API (`POST /collect`)
+- Stats API endpoints (`GET /stats/:appView`)
+- Per-app-view API key authentication
+- TypeScript client library with `AnalyticsClient` class
+- `deriveUidFromDid` helper for anonymous user ID generation
+- Admin endpoint for API key management
+- SQLite storage with indexed queries

README.md

···
+# Driftline Analytics
+
+Anonymous analytics service for ATProto app views, hosted on Valtown.
+
+## Features
+
+- Anonymous by design: users are identified by pseudonymous IDs derived from DIDs
+- Per-app-view isolation: same user gets different IDs across different app views
+- Simple event model: accounts, views, and actions
+- JSON stats API
+
+## API Endpoints
+
+Base URL: `https://driftline.val.run`
+
+### Health Check
+
+```
+GET /
+```
+
+### Collect Events
+
+```
+POST /collect
+Headers: X-API-Key: <your-api-key>
+Content-Type: application/json
+
+Body (single event):
+{
+  "v": 1,
+  "appView": "kipclip.com",
+  "env": "prod",
+  "ts": "2025-01-15T10:30:00.000Z",
+  "uid": "a1b2c3d4e5f6",
+  "type": "action",
+  "name": "checkin_created",
+  "screen": "CheckinScreen",
+  "props": { "placeType": "cafe" }
+}
+
+Body (batch):
+{
+  "events": [...]
+}
+```
+
+Event types:
+- `account` - Track account creation (once per user)
+- `view` - Track screen impressions
+- `action` - Track user actions
+
+### Get Stats
+
+All stats endpoints require the `X-API-Key` header.
+
+```
+GET /stats/:appView?env=prod
+GET /stats/:appView/accounts?env=prod
+GET /stats/:appView/users?env=prod
+GET /stats/:appView/events?env=prod
+```
+
+## Client Usage
+
+```typescript
+import {
+  AnalyticsClient,
+  deriveUidFromDid
+} from "https://esm.town/v/tijs/driftline-analytics/client/analytics-client.ts";
+
+// Derive anonymous user ID from DID (use your app-specific salt)
+const uid = await deriveUidFromDid(user.did, KIPCLIP_SALT);
+
+const analytics = new AnalyticsClient({
+  appView: "kipclip.com",
+  env: "prod",
+  collectorUrl: "https://driftline.val.run",
+  apiKey: KIPCLIP_API_KEY,
+  uid,
+});
+
+// Track events
+await analytics.trackAccountCreated();
+await analytics.trackView("HomeScreen");
+await analytics.trackAction("checkin_created", "CheckinScreen", { placeType: "cafe" });
+```
+
+## Anonymity
+
+User IDs are derived using SHA-256:
+
+```typescript
+uid = sha256(salt + did).slice(0, 12)
+```
+
+- Each app view uses its own salt
+- Same DID produces different UIDs across app views
+- Server never sees the original DID
+
+## Admin
+
+Create API keys (requires `ADMIN_SECRET` env var):
+
+```
+POST /admin/api-keys
+Headers: X-Admin-Secret: <admin-secret>
+Body: { "appView": "your-app.com" }
+```
+
+## Development
+
+```bash
+deno task fmt      # Format code
+deno task lint     # Lint code
+deno task check    # Type check
+deno task deploy   # Format, lint, check, and push to Valtown
+```

backend/database/migrations.ts

···
+/**
+ * Database migrations for Driftline Analytics
+ */
+
+import { sqlite } from "https://esm.town/v/stevekrouse/sqlite?v=13";
+
+const EVENTS_TABLE = "driftline_events";
+const API_KEYS_TABLE = "driftline_api_keys";
+
+export async function runMigrations(): Promise<void> {
+  // Events table
+  await sqlite.execute(`
+    CREATE TABLE IF NOT EXISTS ${EVENTS_TABLE} (
+      id        INTEGER PRIMARY KEY AUTOINCREMENT,
+      ts        TEXT NOT NULL,
+      app_view  TEXT NOT NULL,
+      env       TEXT NOT NULL,
+      type      TEXT NOT NULL,
+      name      TEXT NOT NULL,
+      uid       TEXT NOT NULL,
+      screen    TEXT,
+      props     TEXT
+    )
+  `);
+
+  // Indexes for events
+  await sqlite.execute(`
+    CREATE INDEX IF NOT EXISTS ${EVENTS_TABLE}_app_view_idx
+    ON ${EVENTS_TABLE} (app_view, env, ts)
+  `);
+
+  await sqlite.execute(`
+    CREATE INDEX IF NOT EXISTS ${EVENTS_TABLE}_type_idx
+    ON ${EVENTS_TABLE} (app_view, type, name)
+  `);
+
+  await sqlite.execute(`
+    CREATE INDEX IF NOT EXISTS ${EVENTS_TABLE}_uid_idx
+    ON ${EVENTS_TABLE} (app_view, uid)
+  `);
+
+  // API keys table
+  await sqlite.execute(`
+    CREATE TABLE IF NOT EXISTS ${API_KEYS_TABLE} (
+      id        INTEGER PRIMARY KEY AUTOINCREMENT,
+      app_view  TEXT NOT NULL UNIQUE,
+      api_key   TEXT NOT NULL,
+      created   TEXT NOT NULL
+    )
+  `);
+
+  await sqlite.execute(`
+    CREATE INDEX IF NOT EXISTS ${API_KEYS_TABLE}_key_idx
+    ON ${API_KEYS_TABLE} (api_key)
+  `);
+}
+
+export { API_KEYS_TABLE, EVENTS_TABLE };

backend/database/queries.ts

···
+/**
+ * Database query functions for Driftline Analytics
+ */
+
+import { sqlite } from "https://esm.town/v/stevekrouse/sqlite?v=13";
+import { API_KEYS_TABLE, EVENTS_TABLE } from "./migrations.ts";
+import type {
+  AnalyticsEvent,
+  Environment,
+  EventType,
+  StatsResponse,
+} from "../../shared/types.ts";
+
+// API Key functions
+
+export async function validateApiKey(apiKey: string): Promise<string | null> {
+  const result = await sqlite.execute({
+    sql: `SELECT app_view FROM ${API_KEYS_TABLE} WHERE api_key = ?`,
+    args: [apiKey],
+  });
+
+  if (result.rows.length === 0) {
+    return null;
+  }
+
+  return result.rows[0].app_view as string;
+}
+
+export async function createApiKey(
+  appView: string,
+  apiKey: string,
+): Promise<void> {
+  await sqlite.execute({
+    sql:
+      `INSERT INTO ${API_KEYS_TABLE} (app_view, api_key, created) VALUES (?, ?, ?)`,
+    args: [appView, apiKey, new Date().toISOString()],
+  });
+}
+
+// Event storage
+
+export async function storeEvents(events: AnalyticsEvent[]): Promise<void> {
+  for (const event of events) {
+    await sqlite.execute({
+      sql: `
+        INSERT INTO ${EVENTS_TABLE} (ts, app_view, env, type, name, uid, screen, props)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      `,
+      args: [
+        event.ts,
+        event.appView,
+        event.env,
+        event.type,
+        event.name,
+        event.uid,
+        event.screen ?? null,
+        event.props ? JSON.stringify(event.props) : null,
+      ],
+    });
+  }
+}
+
+// Stats queries
+
+export async function getAccountCount(
+  appView: string,
+  env: Environment,
+): Promise<number> {
+  const result = await sqlite.execute({
+    sql: `
+      SELECT COUNT(DISTINCT uid) as count
+      FROM ${EVENTS_TABLE}
+      WHERE app_view = ? AND env = ? AND type = 'account' AND name = 'account_created'
+    `,
+    args: [appView, env],
+  });
+
+  return (result.rows[0]?.count as number) ?? 0;
+}
+
+export async function getUniqueUsers(
+  appView: string,
+  env: Environment,
+): Promise<number> {
+  const result = await sqlite.execute({
+    sql: `
+      SELECT COUNT(DISTINCT uid) as count
+      FROM ${EVENTS_TABLE}
+      WHERE app_view = ? AND env = ?
+    `,
+    args: [appView, env],
+  });
+
+  return (result.rows[0]?.count as number) ?? 0;
+}
+
+export async function getTotalEvents(
+  appView: string,
+  env: Environment,
+): Promise<number> {
+  const result = await sqlite.execute({
+    sql: `
+      SELECT COUNT(*) as count
+      FROM ${EVENTS_TABLE}
+      WHERE app_view = ? AND env = ?
+    `,
+    args: [appView, env],
+  });
+
+  return (result.rows[0]?.count as number) ?? 0;
+}
+
+export async function getEventsByType(
+  appView: string,
+  env: Environment,
+): Promise<Record<EventType, number>> {
+  const result = await sqlite.execute({
+    sql: `
+      SELECT type, COUNT(*) as count
+      FROM ${EVENTS_TABLE}
+      WHERE app_view = ? AND env = ?
+      GROUP BY type
+    `,
+    args: [appView, env],
+  });
+
+  const counts: Record<EventType, number> = {
+    account: 0,
+    view: 0,
+    action: 0,
+  };
+
+  for (const row of result.rows) {
+    const type = row.type as EventType;
+    counts[type] = row.count as number;
+  }
+
+  return counts;
+}
+
+export async function getEventsByName(
+  appView: string,
+  env: Environment,
+): Promise<Record<string, number>> {
+  const result = await sqlite.execute({
+    sql: `
+      SELECT name, COUNT(*) as count
+      FROM ${EVENTS_TABLE}
+      WHERE app_view = ? AND env = ?
+      GROUP BY name
+      ORDER BY count DESC
+    `,
+    args: [appView, env],
+  });
+
+  const counts: Record<string, number> = {};
+  for (const row of result.rows) {
+    counts[row.name as string] = row.count as number;
+  }
+
+  return counts;
+}
+
+export async function getTopScreens(
+  appView: string,
+  env: Environment,
+  limit: number = 10,
+): Promise<Array<{ screen: string; count: number }>> {
+  const result = await sqlite.execute({
+    sql: `
+      SELECT screen, COUNT(*) as count
+      FROM ${EVENTS_TABLE}
+      WHERE app_view = ? AND env = ? AND screen IS NOT NULL
+      GROUP BY screen
+      ORDER BY count DESC
+      LIMIT ?
+    `,
+    args: [appView, env, limit],
+  });
+
+  return result.rows.map((row) => ({
+    screen: row.screen as string,
+    count: row.count as number,
+  }));
+}
+
+export async function getTopActions(
+  appView: string,
+  env: Environment,
+  limit: number = 10,
+): Promise<Array<{ name: string; count: number }>> {
+  const result = await sqlite.execute({
+    sql: `
+      SELECT name, COUNT(*) as count
+      FROM ${EVENTS_TABLE}
+      WHERE app_view = ? AND env = ? AND type = 'action'
+      GROUP BY name
+      ORDER BY count DESC
+      LIMIT ?
+    `,
+    args: [appView, env, limit],
+  });
+
+  return result.rows.map((row) => ({
+    name: row.name as string,
+    count: row.count as number,
+  }));
+}
+
+export async function getStats(
+  appView: string,
+  env: Environment,
+): Promise<StatsResponse> {
+  const [
+    totalAccounts,
+    totalUsers,
+    totalEvents,
+    eventsByType,
+    topScreens,
+    topActions,
+  ] = await Promise.all([
+    getAccountCount(appView, env),
+    getUniqueUsers(appView, env),
+    getTotalEvents(appView, env),
+    getEventsByType(appView, env),
+    getTopScreens(appView, env),
+    getTopActions(appView, env),
+  ]);
+
+  return {
+    appView,
+    env,
+    totalAccounts,
+    totalUsers,
+    totalEvents,
+    eventsByType,
+    topScreens,
+    topActions,
+  };
+}

backend/index.http.ts

···
+/**
+ * Driftline Analytics - Main HTTP entry point
+ *
+ * Anonymous analytics service for ATProto app views.
+ */
+
+import { Hono } from "https://esm.sh/hono@4.4.0";
+import { cors } from "https://esm.sh/hono@4.4.0/cors";
+import { runMigrations } from "./database/migrations.ts";
+import { admin } from "./routes/admin.ts";
+import { collector } from "./routes/collector.ts";
+import { stats } from "./routes/stats.ts";
+
+const app = new Hono();
+
+// Re-throw errors to see full stack traces
+app.onError((err, _c) => {
+  throw err;
+});
+
+// Enable CORS for client-side tracking
+app.use(
+  "*",
+  cors({
+    origin: "*",
+    allowMethods: ["GET", "POST", "OPTIONS"],
+    allowHeaders: ["Content-Type", "X-API-Key"],
+  }),
+);
+
+// Run migrations on startup
+let migrationsRan = false;
+app.use("*", async (_c, next) => {
+  if (!migrationsRan) {
+    await runMigrations();
+    migrationsRan = true;
+  }
+  await next();
+});
+
+// Health check
+app.get("/", (c) => {
+  return c.json({
+    service: "driftline-analytics",
+    status: "ok",
+    version: 1,
+  });
+});
+
+// Mount routes
+app.route("/admin", admin);
+app.route("/collect", collector);
+app.route("/stats", stats);
+
+// Export for Valtown HTTP trigger
+export default app.fetch;

backend/routes/admin.ts

···
+/**
+ * Admin routes for Driftline Analytics
+ * Protected by ADMIN_SECRET environment variable
+ */
+
+import { Hono } from "https://esm.sh/hono@4.4.0";
+import { createApiKey } from "../database/queries.ts";
+
+const admin = new Hono();
+
+admin.post("/api-keys", async (c) => {
+  const adminSecret = Deno.env.get("ADMIN_SECRET");
+  if (!adminSecret) {
+    return c.json({ error: "Admin not configured" }, 500);
+  }
+
+  const providedSecret = c.req.header("X-Admin-Secret");
+  if (providedSecret !== adminSecret) {
+    return c.json({ error: "Unauthorized" }, 401);
+  }
+
+  let body: { appView?: string };
+  try {
+    body = await c.req.json();
+  } catch {
+    return c.json({ error: "Invalid JSON body" }, 400);
+  }
+
+  if (!body.appView || typeof body.appView !== "string") {
+    return c.json({ error: "appView is required" }, 400);
+  }
+
+  const apiKey = crypto.randomUUID();
+
+  try {
+    await createApiKey(body.appView, apiKey);
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("UNIQUE constraint")) {
+      return c.json({ error: "API key already exists for this app view" }, 409);
+    }
+    throw err;
+  }
+
+  return c.json({
+    success: true,
+    appView: body.appView,
+    apiKey,
+  });
+});
+
+export { admin };

backend/routes/collector.ts

···
+/**
+ * Event collector routes for Driftline Analytics
+ */
+
+import { Hono } from "https://esm.sh/hono@4.4.0";
+import { storeEvents, validateApiKey } from "../database/queries.ts";
+import {
+  validateAppViewMatch,
+  validateCollectRequest,
+} from "../../shared/validation.ts";
+import type { CollectResponse } from "../../shared/types.ts";
+
+const collector = new Hono();
+
+collector.post("/", async (c) => {
+  // Validate API key
+  const apiKey = c.req.header("X-API-Key");
+  if (!apiKey) {
+    return c.json({ error: "Missing X-API-Key header" }, 401);
+  }
+
+  const appViewForKey = await validateApiKey(apiKey);
+  if (!appViewForKey) {
+    return c.json({ error: "Invalid API key" }, 401);
+  }
+
+  // Parse and validate request body
+  let body: unknown;
+  try {
+    body = await c.req.json();
+  } catch {
+    return c.json({ error: "Invalid JSON body" }, 400);
+  }
+
+  const validation = validateCollectRequest(body);
+  if (!validation.valid) {
+    return c.json({ error: validation.error }, 400);
+  }
+
+  // Ensure all events match the API key's app_view
+  const mismatch = validateAppViewMatch(validation.events, appViewForKey);
+  if (mismatch) {
+    return c.json({ error: mismatch }, 403);
+  }
+
+  // Store events
+  await storeEvents(validation.events);
+
+  const response: CollectResponse = {
+    success: true,
+    count: validation.events.length,
+  };
+
+  return c.json(response);
+});
+
+export { collector };

backend/routes/stats.ts

···
+/**
+ * Stats API routes for Driftline Analytics
+ */
+
+import { Hono } from "https://esm.sh/hono@4.4.0";
+import {
+  getAccountCount,
+  getEventsByName,
+  getEventsByType,
+  getStats,
+  getUniqueUsers,
+  validateApiKey,
+} from "../database/queries.ts";
+import type {
+  AccountsResponse,
+  Environment,
+  EventsResponse,
+  UsersResponse,
+} from "../../shared/types.ts";
+
+const stats = new Hono();
+
+// Middleware to validate API key and app_view match
+async function validateAccess(
+  c: {
+    req: {
+      header: (name: string) => string | undefined;
+      param: (name: string) => string;
+    };
+  },
+  appView: string,
+): Promise<{ error: string; status: number } | null> {
+  const apiKey = c.req.header("X-API-Key");
+  if (!apiKey) {
+    return { error: "Missing X-API-Key header", status: 401 };
+  }
+
+  const appViewForKey = await validateApiKey(apiKey);
+  if (!appViewForKey) {
+    return { error: "Invalid API key", status: 401 };
+  }
+
+  if (appViewForKey !== appView) {
+    return { error: "API key does not match requested app_view", status: 403 };
+  }
+
+  return null;
+}
+
+function getEnv(
+  c: { req: { query: (name: string) => string | undefined } },
+): Environment {
+  const env = c.req.query("env");
+  if (env === "dev") return "dev";
+  return "prod";
+}
+
+// Full stats
+stats.get("/:appView", async (c) => {
+  const appView = c.req.param("appView");
+  const accessError = await validateAccess(c, appView);
+  if (accessError) {
+    return c.json(
+      { error: accessError.error },
+      accessError.status as 401 | 403,
+    );
+  }
+
+  const env = getEnv(c);
+  const result = await getStats(appView, env);
+  return c.json(result);
+});
+
+// Account count only
+stats.get("/:appView/accounts", async (c) => {
+  const appView = c.req.param("appView");
+  const accessError = await validateAccess(c, appView);
+  if (accessError) {
+    return c.json(
+      { error: accessError.error },
+      accessError.status as 401 | 403,
+    );
+  }
+
+  const env = getEnv(c);
+  const count = await getAccountCount(appView, env);
+  const response: AccountsResponse = { appView, env, count };
+  return c.json(response);
+});
+
+// Unique users only
+stats.get("/:appView/users", async (c) => {
+  const appView = c.req.param("appView");
+  const accessError = await validateAccess(c, appView);
+  if (accessError) {
+    return c.json(
+      { error: accessError.error },
+      accessError.status as 401 | 403,
+    );
+  }
+
+  const env = getEnv(c);
+  const count = await getUniqueUsers(appView, env);
+  const response: UsersResponse = { appView, env, count };
+  return c.json(response);
+});
+
+// Event breakdown
+stats.get("/:appView/events", async (c) => {
+  const appView = c.req.param("appView");
+  const accessError = await validateAccess(c, appView);
+  if (accessError) {
+    return c.json(
+      { error: accessError.error },
+      accessError.status as 401 | 403,
+    );
+  }
+
+  const env = getEnv(c);
+  const [byType, byName] = await Promise.all([
+    getEventsByType(appView, env),
+    getEventsByName(appView, env),
+  ]);
+
+  const response: EventsResponse = { appView, env, byType, byName };
+  return c.json(response);
+});
+
+export { stats };

client/analytics-client.ts

···
+/**
+ * Driftline Analytics Client
+ *
+ * TypeScript client for tracking analytics events from ATProto app views.
+ *
+ * Usage:
+ *   const uid = await deriveUidFromDid(user.did, YOUR_APP_SALT);
+ *   const analytics = new AnalyticsClient({
+ *     appView: "xyz.kipclip.feed",
+ *     env: "prod",
+ *     collectorUrl: "https://your-analytics.val.run",
+ *     apiKey: YOUR_API_KEY,
+ *     uid,
+ *   });
+ *
+ *   await analytics.trackAccountCreated();
+ *   await analytics.trackView("HomeScreen");
+ *   await analytics.trackAction("checkin_created", "CheckinScreen", { placeType: "cafe" });
+ */
+
+export type Environment = "dev" | "prod";
+export type EventType = "account" | "view" | "action";
+
+export type AnalyticsEvent = {
+  v: 1;
+  appView: string;
+  env: Environment;
+  ts: string;
+  uid: string;
+  type: EventType;
+  name: string;
+  screen?: string;
+  props?: Record<string, unknown>;
+};
+
+export type AnalyticsClientConfig = {
+  appView: string;
+  env: Environment;
+  collectorUrl: string;
+  apiKey: string;
+  uid: string;
+};
+
+export class AnalyticsClient {
+  constructor(private cfg: AnalyticsClientConfig) {}
+
+  private createEvent(
+    type: EventType,
+    name: string,
+    screen?: string,
+    props?: Record<string, unknown>,
+  ): AnalyticsEvent {
+    const event: AnalyticsEvent = {
+      v: 1,
+      appView: this.cfg.appView,
+      env: this.cfg.env,
+      ts: new Date().toISOString(),
+      uid: this.cfg.uid,
+      type,
+      name,
+    };
+
+    if (screen) {
+      event.screen = screen;
+    }
+
+    if (props && Object.keys(props).length > 0) {
+      event.props = props;
+    }
+
+    return event;
+  }
+
+  private async send(event: AnalyticsEvent): Promise<void> {
+    const url = this.cfg.collectorUrl.replace(/\/$/, "") + "/collect";
+
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-Key": this.cfg.apiKey,
+        },
+        body: JSON.stringify(event),
+      });
+
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({
+          error: "Unknown error",
+        }));
+        console.error("[analytics] Failed to send event:", error);
+      }
+    } catch (err) {
+      console.error("[analytics] Network error:", err);
+    }
+  }
+
+  /**
+   * Track when an account is first created/registered for this app view.
+   * Should only be called once per user.
+   */
+  async trackAccountCreated(props?: Record<string, unknown>): Promise<void> {
+    const event = this.createEvent(
+      "account",
+      "account_created",
+      undefined,
+      props,
+    );
+    await this.send(event);
+  }
+
+  /**
+   * Track a screen/view impression.
+   */
+  async trackView(
+    screen: string,
+    props?: Record<string, unknown>,
+  ): Promise<void> {
+    const event = this.createEvent("view", "screen_impression", screen, props);
+    await this.send(event);
+  }
+
+  /**
+   * Track a user action.
+   */
+  async trackAction(
+    name: string,
+    screen?: string,
+    props?: Record<string, unknown>,
+  ): Promise<void> {
+    const event = this.createEvent("action", name, screen, props);
+    await this.send(event);
+  }
+}
+
+/**
+ * Derive a pseudonymous user ID from a DID.
+ * The same DID + salt will always produce the same uid.
+ * Different salts (per app view) produce different uids for the same DID.
+ *
+ * @param did - The user's DID (e.g., "did:plc:...")
+ * @param salt - App-specific salt (keep secret, store in env vars)
+ * @returns 12-character hex string
+ */
+export async function deriveUidFromDid(
+  did: string,
+  salt: string,
+): Promise<string> {
+  const data = new TextEncoder().encode(salt + did);
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  const hex = Array.from(new Uint8Array(hash))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+  return hex.slice(0, 12);
+}

deno.json

···
+{
+  "$schema": "https://raw.githubusercontent.com/denoland/deno/98f62cee78e85bfc47c62ed703777c6bc8794f1c/cli/schemas/config-file.v1.json",
+  "name": "driftline-analytics",
+  "version": "0.1.0",
+  "exports": "./client/analytics-client.ts",
+  "lock": false,
+  "compilerOptions": {
+    "noImplicitAny": false,
+    "strict": true,
+    "types": ["https://www.val.town/types/valtown.d.ts"],
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "dom.asynciterable",
+      "deno.ns",
+      "deno.unstable"
+    ]
+  },
+  "lint": {
+    "include": ["**/*.ts"],
+    "rules": {
+      "exclude": ["no-explicit-any", "no-import-prefix"]
+    }
+  },
+  "fmt": {
+    "include": ["**/*.ts", "**/*.json"]
+  },
+  "tasks": {
+    "check": "deno check --allow-import backend/index.http.ts client/analytics-client.ts",
+    "lint": "deno lint",
+    "fmt": "deno fmt",
+    "fmt:check": "deno fmt --check",
+    "test": "deno test --allow-import",
+    "deploy": "deno task fmt && deno task lint && deno task check && vt push"
+  },
+  "node_modules_dir": false,
+  "experimental": {
+    "unstable-node-globals": true,
+    "unstable-temporal": true,
+    "unstable-worker-options": true,
+    "unstable-sloppy-imports": true
+  }
+}

scripts/create-api-key.ts

···
+/**
+ * Script to create an API key for an app view.
+ * Run via: deno run --allow-import scripts/create-api-key.ts <app_view>
+ *
+ * This script must be run in the Valtown environment (or use their API).
+ * For local testing, copy this logic into a val and run it there.
+ */
+
+import { sqlite } from "https://esm.town/v/stevekrouse/sqlite?v=13";
+
+const API_KEYS_TABLE = "driftline_api_keys";
+
+async function createApiKey(appView: string): Promise<string> {
+  const apiKey = crypto.randomUUID();
+
+  await sqlite.execute({
+    sql:
+      `INSERT INTO ${API_KEYS_TABLE} (app_view, api_key, created) VALUES (?, ?, ?)`,
+    args: [appView, apiKey, new Date().toISOString()],
+  });
+
+  return apiKey;
+}
+
+async function main() {
+  const appView = Deno.args[0];
+
+  if (!appView) {
+    console.error("Usage: deno run scripts/create-api-key.ts <app_view>");
+    console.error("Example: deno run scripts/create-api-key.ts kipclip.com");
+    Deno.exit(1);
+  }
+
+  console.log(`Creating API key for app view: ${appView}`);
+  const apiKey = await createApiKey(appView);
+  console.log(`API key created: ${apiKey}`);
+  console.log(`\nStore this in your Valtown secrets!`);
+}
+
+main();

shared/types.ts

···
+/**
+ * Analytics event types and shared interfaces for Driftline Analytics
+ */
+
+export type EventType = "account" | "view" | "action";
+export type Environment = "dev" | "prod";
+
+export type AnalyticsEvent = {
+  v: 1;
+  appView: string;
+  env: Environment;
+  ts: string;
+  uid: string;
+  type: EventType;
+  name: string;
+  screen?: string;
+  props?: Record<string, unknown>;
+};
+
+export type CollectRequest = AnalyticsEvent | { events: AnalyticsEvent[] };
+
+export type CollectResponse = {
+  success: boolean;
+  count: number;
+};
+
+export type StatsResponse = {
+  appView: string;
+  env: Environment;
+  totalAccounts: number;
+  totalUsers: number;
+  totalEvents: number;
+  eventsByType: Record<EventType, number>;
+  topScreens: Array<{ screen: string; count: number }>;
+  topActions: Array<{ name: string; count: number }>;
+};
+
+export type AccountsResponse = {
+  appView: string;
+  env: Environment;
+  count: number;
+};
+
+export type UsersResponse = {
+  appView: string;
+  env: Environment;
+  count: number;
+};
+
+export type EventsResponse = {
+  appView: string;
+  env: Environment;
+  byType: Record<EventType, number>;
+  byName: Record<string, number>;
+};
+
+export type ApiKeyRecord = {
+  id: number;
+  app_view: string;
+  api_key: string;
+  created: string;
+};
+
+export type EventRecord = {
+  id: number;
+  ts: string;
+  app_view: string;
+  env: string;
+  type: string;
+  name: string;
+  uid: string;
+  screen: string | null;
+  props: string | null;
+};

shared/validation.ts

···
+/**
+ * Event validation for Driftline Analytics
+ */
+
+import type { AnalyticsEvent, Environment, EventType } from "./types.ts";
+
+const VALID_ENVS: Environment[] = ["dev", "prod"];
+const VALID_TYPES: EventType[] = ["account", "view", "action"];
+const UID_PATTERN = /^[a-f0-9]{12}$/;
+
+export type ValidationResult =
+  | { valid: true; events: AnalyticsEvent[] }
+  | { valid: false; error: string };
+
+function isValidIsoDate(str: string): boolean {
+  const date = new Date(str);
+  return !isNaN(date.getTime()) && date.toISOString() === str;
+}
+
+function validateSingleEvent(event: unknown, index?: number): string | null {
+  const prefix = index !== undefined ? `Event[${index}]: ` : "";
+
+  if (!event || typeof event !== "object") {
+    return `${prefix}Event must be an object`;
+  }
+
+  const e = event as Record<string, unknown>;
+
+  if (e.v !== 1) {
+    return `${prefix}Version (v) must be 1`;
+  }
+
+  if (typeof e.appView !== "string" || e.appView.length === 0) {
+    return `${prefix}appView must be a non-empty string`;
+  }
+
+  if (!VALID_ENVS.includes(e.env as Environment)) {
+    return `${prefix}env must be 'dev' or 'prod'`;
+  }
+
+  if (typeof e.ts !== "string" || !isValidIsoDate(e.ts)) {
+    return `${prefix}ts must be a valid ISO timestamp`;
+  }
+
+  if (typeof e.uid !== "string" || !UID_PATTERN.test(e.uid)) {
+    return `${prefix}uid must be a 12-character hex string`;
+  }
+
+  if (!VALID_TYPES.includes(e.type as EventType)) {
+    return `${prefix}type must be 'account', 'view', or 'action'`;
+  }
+
+  if (typeof e.name !== "string" || e.name.length === 0) {
+    return `${prefix}name must be a non-empty string`;
+  }
+
+  if (e.screen !== undefined && typeof e.screen !== "string") {
+    return `${prefix}screen must be a string if provided`;
+  }
+
+  if (
+    e.props !== undefined && (typeof e.props !== "object" || e.props === null)
+  ) {
+    return `${prefix}props must be an object if provided`;
+  }
+
+  return null;
+}
+
+export function validateCollectRequest(body: unknown): ValidationResult {
+  if (!body || typeof body !== "object") {
+    return { valid: false, error: "Request body must be an object" };
+  }
+
+  const b = body as Record<string, unknown>;
+
+  // Check if it's a batch request
+  if ("events" in b && Array.isArray(b.events)) {
+    if (b.events.length === 0) {
+      return { valid: false, error: "Events array cannot be empty" };
+    }
+
+    if (b.events.length > 100) {
+      return { valid: false, error: "Maximum 100 events per request" };
+    }
+
+    const events: AnalyticsEvent[] = [];
+    for (let i = 0; i < b.events.length; i++) {
+      const error = validateSingleEvent(b.events[i], i);
+      if (error) {
+        return { valid: false, error };
+      }
+      events.push(b.events[i] as AnalyticsEvent);
+    }
+
+    return { valid: true, events };
+  }
+
+  // Single event
+  const error = validateSingleEvent(body);
+  if (error) {
+    return { valid: false, error };
+  }
+
+  return { valid: true, events: [body as AnalyticsEvent] };
+}
+
+export function validateAppViewMatch(
+  events: AnalyticsEvent[],
+  expectedAppView: string,
+): string | null {
+  for (let i = 0; i < events.length; i++) {
+    if (events[i].appView !== expectedAppView) {
+      return `Event[${i}]: appView '${
+        events[i].appView
+      }' does not match API key's app_view '${expectedAppView}'`;
+    }
+  }
+  return null;
+}