luchy 0.0.1 → 0.1.0

package/README.md

@@ -0,0 +1,314 @@
+# Luchy Tracker
+
+A lightweight, privacy-focused analytics tracker for web applications. Built for CDN deployment with automatic compression and versioning.
+
+## Features
+
+- 🚀 **Lightweight**: ~3KB minified, ~1.5KB compressed
+- 📊 **Privacy-focused**: No cookies, no personal data collection
+- 🔄 **Auto-tracking**: Pageviews, outbound links, hash routing
+- 📦 **CDN-ready**: Optimized for global distribution
+- 🗜️ **Compressed**: Gzip and Brotli compression included
+- 🏷️ **Versioned**: Commit-based versioning for safe deployments
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install luchy
+```
+
+### Basic Usage
+
+```html
+<script
+  src="https://cdn.luchy.app/luchy.min.js"
+  data-api-key="your-api-key"
+  data-auto-pageviews
+></script>
+```
+
+### Advanced Usage
+
+```html
+<script
+  src="https://cdn.luchy.app/luchy.min.js"
+  data-api-key="your-api-key"
+  data-endpoint="https://api.luchy.app/ingest"
+  data-auto-pageviews
+  data-auto-outbound
+  data-hash-routing
+  data-track-localhost
+></script>
+```
+
+## Data Attributes
+
+| Attribute              | Description                             | Required |
+| ---------------------- | --------------------------------------- | -------- |
+| `data-api-key`         | Your Luchy API key                      | ✅ Yes   |
+| `data-endpoint`        | Custom API endpoint                     | ❌ No    |
+| `data-auto-pageviews`  | Enable automatic pageview tracking      | ❌ No    |
+| `data-auto-outbound`   | Enable automatic outbound link tracking | ❌ No    |
+| `data-auto-events`     | Enable automatic data attribute event tracking | ❌ No    |
+| `data-hash-routing`    | Enable hash routing support             | ❌ No    |
+| `data-track-localhost` | Track localhost traffic                 | ❌ No    |
+
+## Data Attribute Events
+
+Track custom events without JavaScript by adding `data-luchy-event` to any HTML element. Clicks are detected automatically via event delegation.
+
+```html
+<!-- Simple event -->
+<button data-luchy-event="cta-click">Sign Up</button>
+
+<!-- With a payload (data-luchy-payload-*) -->
+<a data-luchy-event="post-click" data-luchy-payload-slug="hello-world" href="/blog/hello-world">
+  Read Post
+</a>
+
+<!-- Multiple keys, dashes convert to underscores -->
+<!-- data-luchy-payload-plan-tier becomes { plan_tier: "enterprise" } -->
+<button
+  data-luchy-event="purchase"
+  data-luchy-payload-plan-tier="enterprise"
+  data-luchy-payload-source="pricing-page"
+>
+  Buy Now
+</button>
+```
+
+> `data-luchy-prop-*` is the original spelling and keeps working — it is written
+> into pages we do not control, so it is never going away. New markup should use
+> `data-luchy-payload-*`, which matches the field name on the wire and in the
+> dashboard.
+
+When an element has `data-luchy-event`, it takes priority over outbound link tracking to avoid duplicate events. Disable with `data-auto-events="false"` on the script tag.
+
+## Manual Tracking
+
+```javascript
+// Track a pageview
+window.luchy.trackPageview();
+
+// Track a custom event. The second argument is the event payload —
+// it is sent as `payload` and shows up as the event's properties.
+window.luchy.trackEvent('Button Click', {
+  button: 'signup',
+  page: 'home'
+});
+
+// Enable auto-tracking features
+window.luchy.enableAutoPageviews();
+window.luchy.enableAutoOutboundTracking();
+window.luchy.enableHashRouting();
+```
+
+## Server-Side Tracking
+
+The browser script can only see what happens in a page. A server sees what the
+application actually *did* — an order placed, a payment recorded, a webhook
+processed — and those are usually the events worth having.
+
+`luchy/server` carries no browser globals, so it runs in Node, Bun,
+Deno and Cloudflare Workers:
+
+```ts
+import { createServerTracker } from 'luchy/server';
+
+const luchy = createServerTracker({
+  apiKey: process.env.LUCHY_API_KEY!,
+  // optional: point at a self-hosted dashboard
+  endpoint: 'https://dash.luchy.app/api/ingest',
+  onError: (error) => logger.warn('[luchy] event dropped', error)
+});
+
+await luchy.trackEvent({
+  name: 'order:placed',
+  pathname: '/checkout',
+  type: 'server',
+  payload: { plan: 'pro', amount: 29 }
+});
+```
+
+Nothing here ever rejects — analytics must not break the request it is
+describing. Pass `onError` if you want failures in your logs.
+
+Fire it after the response so it costs no latency. On Cloudflare Workers:
+
+```ts
+ctx.waitUntil(luchy.trackEvent({ name: 'order:placed', pathname: '/checkout' }));
+```
+
+## API client (`luchy/api`)
+
+`createServerTracker` covers the two calls most apps make. `luchy/api`
+is the whole API: a typed client generated from the dashboard's own OpenAPI
+document, with tracking *and* reading on it. It has no DOM globals and no node
+built-ins, so the same import works on a server and in a browser.
+
+```ts
+import { createLuchyClient } from 'luchy/api';
+
+const luchy = createLuchyClient({
+  apiKey: LUCHY_API_KEY,
+  // optional: point at a self-hosted dashboard's API root
+  endpoint: 'https://dash.luchy.app/api',
+  onError: (error) => console.warn('[luchy] event dropped', error)
+});
+
+// Tracking never rejects, on either side of the wire.
+await luchy.trackEvent({
+  name: 'order:placed',
+  pathname: '/checkout',
+  payload: { plan: 'pro', amount: 29 }
+});
+
+// Reads do — a chart with silently missing numbers is worse than an error.
+const { results } = await luchy.query({
+  date_range: '30d',
+  metrics: ['pageviews', 'visitors'],
+  dimensions: ['event:page']
+});
+```
+
+Failed reads throw `LuchyApiError`, which carries the HTTP status and the
+error body the API sent. For anything without a convenience method, `luchy.api`
+is the underlying [`openapi-fetch`](https://openapi-ts.dev/openapi-fetch/)
+client, typed against every documented endpoint:
+
+```ts
+const { data, error } = await luchy.api.GET('/health');
+```
+
+The request and response types come from the document too, so they are worth
+importing rather than restating: `EventInput`, `PageviewInput`,
+`IngestSuccess`, `QueryRequest`, `QueryResponse`, plus the raw `paths` and
+`components`.
+
+### Where the types come from
+
+```
+apps/dash zod route schemas
+  → bun run openapi:emit   (in apps/dash)
+  → packages/tracker/openapi.json
+  → bun run generate       (in packages/tracker)
+  → src/api/schema.d.ts
+```
+
+`openapi.json` is checked in: it is the wire contract, so a change to the API's
+shape shows up as a reviewable diff in the commit that caused it, and the
+client can be regenerated without a dashboard running anywhere. `schema.d.ts`
+is generated too — never edit either by hand. Change the zod schemas in
+`apps/dash`, re-run both steps, commit the result.
+
+## Development
+
+### Build Scripts
+
+```bash
+# Build the CDN bundle *and* the importable package entry points
+npm run build
+
+# Only the package entry points (dist/index.js, dist/server.js + types)
+npm run build:lib
+
+# Upload to R2 (requires Wrangler setup)
+npm run upload
+
+# Build and deploy everything
+npm run deploy
+```
+
+### File Sizes
+
+- **Minified**: 3.0 KB
+- **Gzipped**: 1.7 KB (43% smaller)
+- **Brotli**: 1.5 KB (50% smaller)
+
+### Generated Files
+
+```
+dist/script/
+├── luchy.js          (unminified)
+├── luchy.min.js      (minified)
+├── luchy.js.gz       (gzipped)
+├── luchy.min.js.gz   (gzipped)
+├── luchy.js.br       (brotli)
+└── luchy.min.js.br   (brotli)
+```
+
+## CDN Deployment
+
+### R2 Upload Structure
+
+The deploy script uploads files to two locations:
+
+**Root Level:**
+
+```
+bucket/
+├── luchy.js
+├── luchy.min.js
+├── luchy.js.gz
+├── luchy.min.js.gz
+├── luchy.js.br
+└── luchy.min.js.br
+```
+
+**Versioned Level:**
+
+```
+bucket/v/{commit-hash}/
+├── luchy.js
+├── luchy.min.js
+├── luchy.js.gz
+├── luchy.min.js.gz
+├── luchy.js.br
+└── luchy.min.js.br
+```
+
+### CDN Usage Examples
+
+```html
+<!-- Latest version -->
+<script src="https://cdn.luchy.app/luchy.min.js"></script>
+
+<!-- Specific version -->
+<script src="https://cdn.luchy.app/v/abc123/luchy.min.js"></script>
+
+<!-- With compression (automatic) -->
+<script src="https://cdn.luchy.app/luchy.min.js"></script>
+```
+
+## Deploying
+
+`bun run deploy` builds, uploads to R2, **purges the CDN cache** and then checks
+what the edge actually serves.
+
+The purge is not optional. R2 has the new bytes the instant the upload finishes,
+but `cdn.luchy.app` is cached, so skipping it leaves every customer on the
+previous build while the deploy prints nothing but green. For that reason the
+script refuses to start when `CLOUDFLARE_API_TOKEN` is missing, rather than
+uploading and half-shipping.
+
+The verification step fetches `https://cdn.luchy.app/luchy.min.js` with no
+cache-busting query string on purpose — a unique query string bypasses the edge
+cache and would pass even when real visitors are still getting the old script.
+
+Root paths are purged; `v/{commit-hash}/` is immutable and never needs it.
+
+## Environment Variables
+
+- `R2_BUCKET`: R2 bucket name (default: `cdn-luchy-app`)
+- `CLOUDFLARE_API_TOKEN`: **required.** Needs the Zone > Cache Purge permission
+  on the `luchy.app` zone.
+- `CLOUDFLARE_ACCOUNT_ID`: defaults to the account that owns `cdn-luchy-app`.
+  Pinned because `wrangler r2 object put` refuses to pick between accounts in a
+  non-interactive shell.
+- `CLOUDFLARE_ZONE_ID`: defaults to the `luchy.app` zone.
+
+## License
+
+MIT

package/dist/api/index.d.ts

@@ -0,0 +1,112 @@
+import { Client } from 'openapi-fetch';
+import { components, paths } from './schema';
+/**
+ * The typed Luchy API client.
+ *
+ * `schema.d.ts` next to this file is generated from `openapi.json`, which is
+ * itself emitted from the zod route definitions in `apps/dash`. Nothing in this
+ * package restates the wire format by hand — that is what let the
+ * `props`/`payload` split ship unnoticed — so a field renamed in the API turns
+ * into a type error here rather than into silently-dropped data in production.
+ *
+ * This module is isomorphic on purpose: no DOM globals, no node built-ins, no
+ * `import.meta.env`. It runs in browsers, Node, Bun, Deno and Cloudflare
+ * Workers, which is why the transport is injectable rather than assumed.
+ */
+export type { components, paths };
+/** The body accepted by `POST /ingest/event`. */
+export type EventInput = components['schemas']['EventInput'];
+/** The body accepted by `POST /ingest/pageview`. */
+export type PageviewInput = components['schemas']['PageviewInput'];
+/** What both ingest endpoints answer with on success. */
+export type IngestSuccess = components['schemas']['SuccessResponse'];
+/** The body accepted by `POST /query`. */
+export type QueryRequest = components['schemas']['QueryRequest'];
+/** The result of a successful `POST /query`. */
+export type QueryResponse = components['schemas']['QueryResponse'];
+/** The `GET /health` body. */
+export type HealthResponse = components['schemas']['HealthResponse'];
+/** A 400 from any endpoint. */
+export type ValidationError = components['schemas']['ValidationErrorResponse'];
+/** A 500 from any endpoint. */
+export type ServerError = components['schemas']['ServerErrorResponse'];
+/** The raw typed client, with every documented endpoint on it. */
+export type LuchyApi = Client<paths>;
+export type LuchyClientOptions = {
+    /** A Luchy API key. Sent as `Authorization: Bearer <key>`. */
+    apiKey: string;
+    /** The API root, without a trailing slash. Defaults to the hosted API. */
+    endpoint?: string;
+    /**
+     * Transport override. Useful for tests, for runtimes that hand you a scoped
+     * `fetch` (Cloudflare service bindings), and for retry/proxy wrappers.
+     */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Called when a tracking call fails. `trackEvent` and `trackPageview` never
+     * reject — analytics must not break the thing it is describing — so this is
+     * the only way to see those failures.
+     */
+    onError?: (error: unknown) => void;
+};
+export type LuchyClient = {
+    /**
+     * The underlying `openapi-fetch` client, pre-authenticated. Use it for
+     * anything the convenience methods below do not cover; it is typed against
+     * the full document, so `api.POST('/query', { body })` is checked end to end.
+     */
+    api: LuchyApi;
+    trackEvent(event: EventInput): Promise<IngestSuccess | null>;
+    trackPageview(pageview: PageviewInput): Promise<IngestSuccess | null>;
+    query(request: QueryRequest): Promise<QueryResponse>;
+    health(): Promise<HealthResponse>;
+};
+/**
+ * Thrown by the endpoints where failing loudly is the right answer — reads
+ * (`query`, `health`), as opposed to the fire-and-forget tracking calls.
+ *
+ * ```ts
+ * try {
+ *   await luchy.query({ date_range: '7d', metrics: ['pageviews'] });
+ * } catch (error) {
+ *   if (error instanceof LuchyApiError) {
+ *     console.error(error.status, error.body);
+ *   }
+ * }
+ * ```
+ */
+export declare class LuchyApiError extends Error {
+    /** The HTTP status. Transport failures propagate as the runtime's own error, not this one. */
+    readonly status: number;
+    /** The parsed error body, when the API sent one. */
+    readonly body: ValidationError | ServerError | undefined;
+    constructor(message: string, status: number, body?: ValidationError | ServerError);
+}
+/**
+ * Creates a Luchy API client.
+ *
+ * The same import works on a server and in a browser, so an app that tracks
+ * from both ends has one client and one set of types instead of two.
+ *
+ * ```ts
+ * import { createLuchyClient } from 'luchy/api';
+ *
+ * const luchy = createLuchyClient({
+ *   apiKey: process.env.LUCHY_API_KEY!,
+ *   onError: (error) => console.warn('[luchy]', error)
+ * });
+ *
+ * await luchy.trackEvent({
+ *   name: 'order:placed',
+ *   pathname: '/checkout',
+ *   payload: { plan: 'pro', amount: 29 }
+ * });
+ *
+ * const stats = await luchy.query({
+ *   date_range: '7d',
+ *   metrics: ['pageviews', 'visitors']
+ * });
+ * ```
+ */
+export declare function createLuchyClient(options: LuchyClientOptions): LuchyClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,OAAqB,EAAE,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAElD;;;;;;;;;;;;GAYG;AAEH,YAAY,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AAElC,iDAAiD;AACjD,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,YAAY,CAAC,CAAC;AAC7D,oDAAoD;AACpD,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,eAAe,CAAC,CAAC;AACnE,yDAAyD;AACzD,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,iBAAiB,CAAC,CAAC;AACrE,0CAA0C;AAC1C,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,cAAc,CAAC,CAAC;AACjE,gDAAgD;AAChD,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,eAAe,CAAC,CAAC;AACnE,8BAA8B;AAC9B,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,gBAAgB,CAAC,CAAC;AACrE,+BAA+B;AAC/B,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,yBAAyB,CAAC,CAAC;AAC/E,+BAA+B;AAC/B,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,qBAAqB,CAAC,CAAC;AAEvE,kEAAkE;AAClE,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;AAErC,MAAM,MAAM,kBAAkB,GAAG;IAC/B,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB;;;;OAIG;IACH,GAAG,EAAE,QAAQ,CAAC;IACd,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAC7D,aAAa,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IACtE,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACrD,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC;CACnC,CAAC;AAYF;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW,GAAG,SAAS,CAAC;gBAGvD,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,eAAe,GAAG,WAAW;CAOvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAoI1E"}

package/dist/api/index.js

@@ -0,0 +1,125 @@
+import createClient from "openapi-fetch";
+const DEFAULT_ENDPOINT = "https://dash.luchy.app/api";
+class LuchyApiError extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.name = "LuchyApiError";
+    this.status = status;
+    this.body = body;
+  }
+}
+function createLuchyClient(options) {
+  const { apiKey, onError } = options;
+  const api = createClient({
+    baseUrl: options.endpoint || DEFAULT_ENDPOINT,
+    fetch: options.fetch,
+    headers: { Authorization: `Bearer ${apiKey}` }
+  });
+  async function ingest(call) {
+    try {
+      const { data, error, response } = await call();
+      if (error || !data) {
+        onError?.(
+          new LuchyApiError(
+            `Luchy ingest failed with ${response.status}`,
+            response.status,
+            error
+          )
+        );
+        return null;
+      }
+      return data;
+    } catch (error) {
+      onError?.(error);
+      return null;
+    }
+  }
+  return {
+    api,
+    /**
+     * Records a custom event. Resolves to the ingest receipt, or to `null` if
+     * the call failed — it never rejects.
+     *
+     * ```ts
+     * await luchy.trackEvent({
+     *   name: 'signup:completed',
+     *   pathname: '/signup',
+     *   type: 'server',
+     *   payload: { plan: 'free' }
+     * });
+     * ```
+     */
+    trackEvent(event) {
+      return ingest(
+        () => api.POST("/ingest/event", {
+          // Lets the request outlive the page on `beforeunload`. Runtimes that
+          // do not support the flag ignore it rather than reject.
+          keepalive: true,
+          body: event
+        })
+      );
+    },
+    /**
+     * Records a pageview. Same contract as `trackEvent`: never rejects.
+     *
+     * ```ts
+     * await luchy.trackPageview({
+     *   pathname: '/pricing',
+     *   referrer: 'https://google.com'
+     * });
+     * ```
+     */
+    trackPageview(pageview) {
+      return ingest(
+        () => api.POST("/ingest/pageview", { keepalive: true, body: pageview })
+      );
+    },
+    /**
+     * Runs an analytics query. Unlike the tracking calls this throws
+     * `LuchyApiError` on a non-2xx, because a caller rendering a chart needs to
+     * know the numbers are missing.
+     *
+     * ```ts
+     * const { results } = await luchy.query({
+     *   date_range: '30d',
+     *   metrics: ['pageviews', 'visitors'],
+     *   dimensions: ['event:page']
+     * });
+     * ```
+     */
+    async query(request) {
+      const { data, error, response } = await api.POST("/query", {
+        body: request
+      });
+      if (error || !data) {
+        throw new LuchyApiError(
+          `Luchy query failed with ${response.status}`,
+          response.status,
+          error
+        );
+      }
+      return data;
+    },
+    /**
+     * Pings the API. Throws `LuchyApiError` if it is not healthy.
+     *
+     * ```ts
+     * const { status, timestamp } = await luchy.health();
+     * ```
+     */
+    async health() {
+      const { data, response } = await api.GET("/health");
+      if (!data) {
+        throw new LuchyApiError(
+          `Luchy health check failed with ${response.status}`,
+          response.status
+        );
+      }
+      return data;
+    }
+  };
+}
+export {
+  LuchyApiError,
+  createLuchyClient
+};