luchy 0.2.0 → 1.0.1

package/dist/api/schema.d.ts

@@ -118,7 +118,7 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/query": {
+    "/ingest/identify": {
         parameters: {
             query?: never;
             header?: never;
@@ -127,6 +127,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
+        /** @description Stores person profile traits. Requires the project's secret key (`lsk_…`) as the bearer token; the public ingest key is rejected. */
         post: {
             parameters: {
                 query?: never;
@@ -136,17 +137,17 @@ export interface paths {
             };
             requestBody?: {
                 content: {
-                    "application/json": components["schemas"]["QueryRequest"];
+                    "application/json": components["schemas"]["IdentifyInput"];
                 };
             };
             responses: {
-                /** @description Query executed successfully */
+                /** @description Profile stored */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["QueryResponse"];
+                        "application/json": components["schemas"]["IdentifyResponse"];
                     };
                 };
                 /** @description Invalid request body or validation error */
@@ -158,6 +159,131 @@ export interface paths {
                         "application/json": components["schemas"]["ValidationErrorResponse"];
                     };
                 };
+                /** @description Missing or invalid secret key */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Internal server error */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ServerErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/analytics/query": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** @description Metrics for the key's project. */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["AnalyticsQueryRequest"];
+                };
+            };
+            responses: {
+                /** @description Query result */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["AnalyticsQueryResponse"];
+                    };
+                };
+                /** @description Invalid request */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ValidationErrorResponse"];
+                    };
+                };
+                /** @description Internal server error */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ServerErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/analytics/sql": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** @description Read-only SQL over the whole database — not scoped to the key’s project. Luchy is single-owner, so any valid query key may use it; filter on project_id yourself. */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["SqlRequest"];
+                };
+            };
+            responses: {
+                /** @description Rows */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["SqlResponse"];
+                    };
+                };
+                /** @description Invalid request */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ValidationErrorResponse"];
+                    };
+                };
                 /** @description Internal server error */
                 500: {
                     headers: {
@@ -175,6 +301,42 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/analytics/schema": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** @description Tables, columns and conventions for writing /analytics/sql queries. */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Schema documentation */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["AnalyticsSchemaResponse"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/health": {
         parameters: {
             query?: never;
@@ -275,6 +437,15 @@ export interface components {
              * @example https://google.com
              */
             referrer?: string;
+            /**
+             * @description Pageview properties
+             * @example {
+             *       "plan": "pro"
+             *     }
+             */
+            payload?: {
+                [key: string]: string | number | boolean;
+            };
             /**
              * @description The user agent string
              * @example Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36
@@ -286,10 +457,20 @@ export interface components {
              */
             language?: string;
             /**
-             * @description The user country code
+             * @description The user country code. Wins over the country Cloudflare infers from the request.
              * @example US
              */
             country?: string;
+            /**
+             * @description Signed identity token (`base64url(json).base64url(hmac)`). An invalid token is ignored and the event is stored anonymously.
+             * @example eyJ1IjoidV8xIn0.3q2-7w
+             */
+            identity?: string;
+            /**
+             * @description Client IP, for server-side senders. Only used to derive the daily visitor hash; never stored. Defaults to the connecting IP.
+             * @example 203.0.113.7
+             */
+            ip?: string;
         };
         /** @description Event tracking data */
         EventInput: {
@@ -339,99 +520,206 @@ export interface components {
              */
             language?: string;
             /**
-             * @description The user country code
+             * @description The user country code. Wins over the country Cloudflare infers from the request.
              * @example US
              */
             country?: string;
+            /**
+             * @description Signed identity token (`base64url(json).base64url(hmac)`). An invalid token is ignored and the event is stored anonymously.
+             * @example eyJ1IjoidV8xIn0.3q2-7w
+             */
+            identity?: string;
+            /**
+             * @description Client IP, for server-side senders. Only used to derive the daily visitor hash; never stored. Defaults to the connecting IP.
+             * @example 203.0.113.7
+             */
+            ip?: string;
         };
-        /**
-         * Analytics Query Request
-         * @description Query parameters for analytics data
-         */
-        QueryRequest: {
-            /** @description Time range for the query */
-            date_range: string | {
-                /**
-                 * @description Start date (ISO 8601)
-                 * @example 2025-01-01
-                 */
-                from: string;
-                /**
-                 * @description End date (ISO 8601)
-                 * @example 2025-01-31
-                 */
-                to: string;
+        /** @description Profile stored */
+        IdentifyResponse: {
+            /** @example true */
+            success: boolean;
+        };
+        /** @description Error response */
+        ErrorResponse: {
+            /**
+             * @description Error message
+             * @example Invalid request body
+             */
+            error: string;
+            /**
+             * @description Detailed error information
+             * @example Invalid JSON format
+             */
+            details: string;
+        };
+        /** @description Person profile traits */
+        IdentifyInput: {
+            /**
+             * @description The stable user id, the same one identity tokens carry as `user`.
+             * @example usr_7Hq2mXk9
+             */
+            user: string;
+            /**
+             * @description Merged into the stored profile. `null` deletes a trait. The dashboard labels a person by `name`, else `email`, else the id.
+             * @example {
+             *       "name": "María Pérez",
+             *       "email": "maria@example.com"
+             *     }
+             */
+            traits: {
+                [key: string]: string | number | boolean | unknown | unknown;
+            };
+        };
+        AnalyticsPeriod: {
+            from: string;
+            to: string;
+            totals: {
+                events?: number;
+                pageviews?: number;
+                sessions?: number;
+                visitors?: number;
+                users?: number;
+                avg_duration?: number;
+                bounce_rate?: number;
+            };
+            rows?: {
+                events?: number;
+                pageviews?: number;
+                sessions?: number;
+                visitors?: number;
+                users?: number;
+                avg_duration?: number;
+                bounce_rate?: number;
+                key: string | number | unknown;
+            }[];
+            series?: {
+                events?: number;
+                pageviews?: number;
+                sessions?: number;
+                visitors?: number;
+                users?: number;
+                avg_duration?: number;
+                bounce_rate?: number;
+                bucket: string;
+            }[];
+        };
+        AnalyticsQueryResponse: {
+            current: components["schemas"]["AnalyticsPeriod"];
+            previous?: components["schemas"]["AnalyticsPeriod"];
+            delta?: {
+                events?: {
+                    abs: number;
+                    /** @description null when previous is 0 */
+                    pct: number | null;
+                };
+                pageviews?: {
+                    abs: number;
+                    /** @description null when previous is 0 */
+                    pct: number | null;
+                };
+                sessions?: {
+                    abs: number;
+                    /** @description null when previous is 0 */
+                    pct: number | null;
+                };
+                visitors?: {
+                    abs: number;
+                    /** @description null when previous is 0 */
+                    pct: number | null;
+                };
+                users?: {
+                    abs: number;
+                    /** @description null when previous is 0 */
+                    pct: number | null;
+                };
+                avg_duration?: {
+                    abs: number;
+                    /** @description null when previous is 0 */
+                    pct: number | null;
+                };
+                bounce_rate?: {
+                    abs: number;
+                    /** @description null when previous is 0 */
+                    pct: number | null;
+                };
             };
-            /** @description Timezone (e.g., America/Santo_Domingo) */
+        };
+        AnalyticsQueryRequest: {
+            /**
+             * @description Inclusive start (ISO 8601)
+             * @example 2025-01-01T00:00:00Z
+             */
+            from: string;
+            /**
+             * @description Exclusive end (ISO 8601)
+             * @example 2025-02-01T00:00:00Z
+             */
+            to: string;
+            /**
+             * @description IANA timezone for buckets, hour and weekday. Default UTC.
+             * @example America/Santo_Domingo
+             */
             tz?: string;
             /**
-             * @description Metrics to calculate
+             * @description Every metric is computed. visitors = distinct coalesce(user, visitor_hash); avg_duration in seconds; bounce_rate in %.
              * @example [
              *       "pageviews",
              *       "visitors"
              *     ]
              */
-            metrics: ("pageviews" | "visitors" | "sessions" | "visit:bounce_rate" | "visit:avg_duration" | "events")[];
+            metrics: ("events" | "pageviews" | "sessions" | "visitors" | "users" | "avg_duration" | "bounce_rate")[];
+            /**
+             * @description A fixed field or `props.<key>` (a key of the event payload). `hour` and `weekday` (0 = Sunday) are in `tz`.
+             * @example tenant
+             */
+            breakdown?: ("page" | "event" | "type" | "source" | "referrer" | "country" | "device" | "browser" | "os" | "tenant" | "user" | "actor" | "hour" | "weekday") | string;
             /**
-             * @description Dimensions to group by
+             * @description [field, op, value]; `in` takes a list.
              * @example [
-             *       "event:page"
+             *       [
+             *         "props.role",
+             *         "eq",
+             *         "admin"
+             *       ]
              *     ]
              */
-            dimensions?: ("event:page" | "visit:country_name" | "visit:source" | "visit:referrer" | "visit:device" | "visit:browser" | "event:name")[];
-            /**
-             * @description Filters to apply
-             * @example []
-             */
-            filters?: (("equals" | "not_equals" | "contains" | "starts_with" | "in" | "not_in" | "between" | "is_not") | string | (string | number | string[] | number[] | string[]))[][] | (("equals" | "not_equals" | "contains" | "starts_with" | "in" | "not_in" | "between" | "is_not") | string | (string | number | string[] | number[] | string[]))[][];
-            /**
-             * @description Ordering criteria
-             * @example []
-             */
-            order_by?: (string | ("asc" | "desc"))[][] | (string | ("asc" | "desc"))[][];
-            /** @description Pagination options */
-            pagination?: {
-                /**
-                 * @default 100
-                 * @example 50
-                 */
-                limit: number;
-                /**
-                 * @default 0
-                 * @example 0
-                 */
-                offset: number;
-            };
-            /** @description Additional data to include in response */
-            include?: {
-                /** @default false */
-                time_labels: boolean;
-                /** @default false */
-                total_rows: boolean;
-                /**
-                 * @default daily
-                 * @enum {string}
-                 */
-                granularity: "hourly" | "daily" | "weekly" | "monthly" | "yearly";
+            filters?: ((("page" | "event" | "type" | "source" | "referrer" | "country" | "device" | "browser" | "os" | "tenant" | "user" | "actor" | "hour" | "weekday") | string) | ("eq" | "neq" | "in") | (string | number | boolean | unknown | (string | number | boolean | unknown | unknown)[] | unknown))[][];
+            /**
+             * @description Adds a zero-filled time series
+             * @enum {string}
+             */
+            granularity?: "hour" | "day" | "week" | "month";
+            /** @description Also runs the query on another range and returns deltas */
+            compare?: "previous_period" | {
+                /** @example 2025-01-01T00:00:00Z */
+                from: string;
+                /** @example 2025-02-01T00:00:00Z */
+                to: string;
             };
+            /** @description Max breakdown rows (default 100) */
+            limit?: number;
         };
-        /**
-         * Analytics Query Response
-         * @description Analytics query results
-         */
-        QueryResponse: {
-            /** @description Query results */
-            results: {
-                dimensions: string[];
-                metrics: number[];
-                time_series?: number[];
+        SqlResponse: {
+            columns: string[];
+            rows: {
+                [key: string]: unknown;
             }[];
-            /** @description Metadata about the query */
-            meta: {
-                time_labels?: string[];
-                total_rows?: number;
-                query: components["schemas"]["QueryRequest"];
-            };
+            truncated: boolean;
+        };
+        SqlRequest: {
+            /**
+             * @description One SELECT or WITH statement. See GET /analytics/schema.
+             * @example SELECT tenant, COUNT(*) AS actions FROM events WHERE project_id = ? GROUP BY tenant
+             */
+            query: string;
+            /** @description Bound to `?` placeholders in order */
+            params?: (string | number | boolean | unknown | unknown)[];
+            /** @description Max rows (default 1000) */
+            limit?: number;
+        };
+        AnalyticsSchemaResponse: {
+            doc: string;
         };
         /** @description Health check response */
         HealthResponse: {

package/dist/identity.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Signed identity tokens.
+ *
+ * Ingest only trusts who a hit belongs to when the app vouches for it: the
+ * server signs `{ user, actor?, tenant? }` with the project's secret key,
+ * the token travels with the hit (browser or server), and ingest verifies it.
+ * An unsigned or tampered token is dropped and the hit is stored anonymous, so
+ * a visitor cannot attribute traffic to someone else by editing the page.
+ *
+ * WebCrypto only — runs in Workers, Node >= 18, Bun and Deno.
+ *
+ * @module
+ */
+/**
+ * Who a hit belongs to. `user` is the account being viewed as, `actor` the
+ * person actually acting when they differ (impersonation), `tenant` the app's
+ * own workspace/client id.
+ */
+export type LuchyIdentity = {
+    user: string;
+    actor?: string;
+    tenant?: string;
+};
+/**
+ * Signs an identity for ingest.
+ *
+ * Format: `base64url(JSON({ u, a?, t? })) + "." + base64url(HMAC-SHA256(secret, firstPart))`.
+ * The short keys keep the token small: it is rendered into every page.
+ *
+ * ```ts
+ * const token = await signIdentity({ user: 'u_1', tenant: '5' }, env.LUCHY_SECRET);
+ * ```
+ */
+export declare function signIdentity(identity: LuchyIdentity, secret: string): Promise<string>;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAgB9E;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAgBjB"}

package/dist/index.d.ts

@@ -1,7 +1,20 @@
+export type { LuchyIdentity } from './identity.js';
+/** A property bag. Nested objects are not supported by the ingest API. */
+export type LuchyProps = Record<string, string | number | boolean>;
 export type LuchyInitOptions = {
     endpoint?: string;
     apiKey: string;
     trackLocalhost?: boolean;
+    /** A signed identity token (see `signIdentity` in `luchy/server`). */
+    identity?: string;
+    /** Merged into the payload of every event and pageview. */
+    props?: LuchyProps;
+    /**
+     * The script tag the tracker was loaded from. When set, `data-identity` and
+     * `data-props` are read from it on every send (so a server re-render after
+     * login is picked up), and `identify`/`reset` write to it.
+     */
+    script?: Element;
 };
 export type LuchyTrackerOptions = {
     autoPageviews?: boolean;
@@ -13,10 +26,19 @@ export type LuchyTracker = {
     trackPageview(data?: {
         pathname?: string;
         referrer?: string;
+        payload?: LuchyProps;
     }): Promise<void>;
-    trackEvent(name: string, payload?: Record<string, string | number>, options?: {
+    trackEvent(name: string, payload?: LuchyProps, options?: {
         type?: string;
     }): Promise<void>;
+    /**
+     * Attributes everything sent from now on to a signed identity token, for
+     * SPAs that learn who the user is after load. `props` replace the current
+     * ones.
+     */
+    identify(token: string, props?: LuchyProps): void;
+    /** Back to anonymous, e.g. on logout. Drops props too. */
+    reset(): void;
     setOptions(options: LuchyTrackerOptions): void;
 };
 /**

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,aAAa,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,UAAU,CACR,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EACzC,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,UAAU,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAChD,CAAC;AAEF;;GAEG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,CAyW7D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAEnE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,aAAa,CAAC,IAAI,CAAC,EAAE;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,UAAU,CAAC;KACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB,UAAU,CACR,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,UAAU,EACpB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAClD,0DAA0D;IAC1D,KAAK,IAAI,IAAI,CAAC;IACd,UAAU,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAChD,CAAC;AAgBF;;GAEG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,CA2Z7D"}