luchy 1.0.1 → 1.2.0

package/README.md

@@ -123,6 +123,15 @@ window.luchy.reset();
 `identify`/`reset` write through to the script tag's `data-identity` /
 `data-props`, so the tag stays the single source of truth.
 
+### UTM attribution
+
+Every pageview reads `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`
+and `utm_content` from `location.search` and adds the present ones to its
+payload (trimmed, at most 200 characters). Nothing else from the query string
+is sent, and a key in the pageview's own `payload` wins over the URL. Ingest
+keeps the first `utm_source` / `utm_medium` / `utm_campaign` of a session as
+its attribution.
+
 ## Identity
 
 Luchy ties hits to your users only when your server vouches for them. An
@@ -218,6 +227,9 @@ await luchy.pageview({ pathname: '/pricing', payload: { plan: 'pro' } });
   is the server.
 - Nothing ever rejects — analytics must not break the request it is
   describing. Pass `onError` if you want failures in your logs.
+- UTM attribution is not read from any URL here: pass the same keys
+  (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`) in
+  `payload` and the session is attributed exactly as for the browser script.
 
 ## API client (`luchy/api`)
 
@@ -254,7 +266,8 @@ const { current, delta } = await luchy.query({
 });
 
 // Anything the engine can't express: one read-only SELECT/WITH over the whole
-// database (not scoped to a project). `luchy.schema()` documents the tables.
+// database (not scoped to a project). The tables are documented in the
+// method's description: https://dash.luchy.app/llms.txt
 const { rows } = await luchy.sql({
   query:
     'SELECT tenant, COUNT(*) AS n FROM events WHERE project_id = ? GROUP BY tenant',
@@ -274,13 +287,17 @@ 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`, `SqlRequest`, `SqlResponse`,
-plus the raw `paths` and
-`components`.
+`MethodError`, plus the raw `paths` and `components`.
+
+Reads use a query key (`wak_…`) minted in the dashboard under Keys. They call
+the dashboard's analytics methods (`POST /api/analytics.query`,
+`/api/analytics.sql`, …), the same ones its MCP server at
+`https://dash.luchy.app/mcp` exposes to agents.
 
 ### Where the types come from
 
 ```
-apps/dash zod route schemas
+apps/dash ingest routes (zod) + kit methods (app/kit)
   → bun run openapi:emit   (in apps/dash)
   → packages/tracker/openapi.json
   → bun run generate       (in packages/tracker)
@@ -290,7 +307,7 @@ apps/dash zod route schemas
 `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
+is generated too — never edit either by hand. Change the schemas in
 `apps/dash`, re-run both steps, commit the result.
 
 ## React Router (`luchy/react-router`)

package/dist/api/index.d.ts

@@ -22,14 +22,36 @@ export type PageviewInput = components['schemas']['PageviewInput'];
 export type IdentifyInput = components['schemas']['IdentifyInput'];
 /** What both ingest endpoints answer with on success. */
 export type IngestSuccess = components['schemas']['SuccessResponse'];
-/** The body accepted by `POST /analytics/query`. */
-export type QueryRequest = components['schemas']['AnalyticsQueryRequest'];
-/** The result of a successful `POST /analytics/query`. */
-export type QueryResponse = components['schemas']['AnalyticsQueryResponse'];
-/** The body accepted by `POST /analytics/sql`. */
-export type SqlRequest = components['schemas']['SqlRequest'];
-/** The result of a successful `POST /analytics/sql`. */
-export type SqlResponse = components['schemas']['SqlResponse'];
+type Body<P extends keyof paths> = paths[P] extends {
+    post: {
+        requestBody?: {
+            content: {
+                'application/json': infer B;
+            };
+        };
+    };
+} ? B : never;
+type Result<P extends keyof paths> = paths[P] extends {
+    post: {
+        responses: {
+            200: {
+                content: {
+                    'application/json': infer R;
+                };
+            };
+        };
+    };
+} ? R : never;
+/** The body accepted by `POST /analytics.query`. */
+export type QueryRequest = Body<'/analytics.query'>;
+/** The result of a successful `POST /analytics.query`. */
+export type QueryResponse = Result<'/analytics.query'>;
+/** The body accepted by `POST /analytics.sql`. */
+export type SqlRequest = Body<'/analytics.sql'>;
+/** The result of a successful `POST /analytics.sql`. */
+export type SqlResponse = Result<'/analytics.sql'>;
+/** A kit method's error body (`{ error }`, plus `fields` for invalid input). */
+export type MethodError = components['schemas']['InvalidInput'];
 /** The `GET /health` body. */
 export type HealthResponse = components['schemas']['HealthResponse'];
 /** A 400 from any endpoint. */
@@ -59,7 +81,7 @@ 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('/analytics/query', { body })` is checked
+     * the full document, so `api.POST('/analytics.query', { body })` is checked
      * end to end.
      */
     api: LuchyApi;
@@ -67,12 +89,11 @@ export type LuchyClient = {
     trackPageview(pageview: PageviewInput): Promise<IngestSuccess | null>;
     query(request: QueryRequest): Promise<QueryResponse>;
     sql(request: SqlRequest): Promise<SqlResponse>;
-    schema(): Promise<string>;
     health(): Promise<HealthResponse>;
 };
 /**
  * Thrown by the endpoints where failing loudly is the right answer — reads
- * (`query`, `sql`, `schema`, `health`), as opposed to the fire-and-forget
+ * (`query`, `sql`, `health`), as opposed to the fire-and-forget
  * tracking calls.
  *
  * ```ts
@@ -89,8 +110,8 @@ 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);
+    readonly body: ValidationError | ServerError | MethodError | undefined;
+    constructor(message: string, status: number, body?: ValidationError | ServerError | MethodError);
 }
 /**
  * Creates a Luchy API client.

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"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"}

package/dist/api/index.js

@@ -90,7 +90,7 @@ function createLuchyClient(options) {
      * ```
      */
     async query(request) {
-      const { data, error, response } = await api.POST("/analytics/query", {
+      const { data, error, response } = await api.POST("/analytics.query", {
         body: request
       });
       if (error || !data) {
@@ -104,8 +104,9 @@ function createLuchyClient(options) {
     },
     /**
      * Runs one read-only `SELECT`/`WITH` statement over the whole database
-     * (not scoped to a project — filter on `project_id`). Throws
-     * `LuchyApiError` on a non-2xx, including rejected statements (400).
+     * (not scoped to a project — filter on `project_id`). The schema is in
+     * the method's description: `GET /llms.txt` or `/openapi.json` on the dash.
+     * Throws `LuchyApiError` on a non-2xx, including rejected statements (400).
      *
      * ```ts
      * const { rows } = await luchy.sql({
@@ -115,7 +116,7 @@ function createLuchyClient(options) {
      * ```
      */
     async sql(request) {
-      const { data, error, response } = await api.POST("/analytics/sql", {
+      const { data, error, response } = await api.POST("/analytics.sql", {
         body: request
       });
       if (error || !data) {
@@ -127,17 +128,6 @@ function createLuchyClient(options) {
       }
       return data;
     },
-    /** The tables, columns and conventions to write `sql` queries against. */
-    async schema() {
-      const { data, response } = await api.GET("/analytics/schema");
-      if (!data) {
-        throw new LuchyApiError(
-          `Luchy schema failed with ${response.status}`,
-          response.status
-        );
-      }
-      return data.doc;
-    },
     /**
      * Pings the API. Throws `LuchyApiError` if it is not healthy.
      *