luchy 0.2.0 → 1.0.1

package/README.md

@@ -45,15 +45,21 @@ npm install luchy
 
 ## 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    |
+| Attribute              | Description                                                     | Required |
+| ---------------------- | --------------------------------------------------------------- | -------- |
+| `data-api-key`         | Your Luchy API key                                              | ✅ Yes   |
+| `data-endpoint`        | Custom ingest endpoint                                          | ❌ No    |
+| `data-identity`        | Signed identity token (see [Identity](#identity))               | ❌ No    |
+| `data-props`           | JSON object merged into the payload of every event and pageview | ❌ 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-identity` and `data-props` are read from the script tag on **every**
+send, not once at load, so a server-rendered tag that is re-rendered after
+login or logout is picked up without a reload.
 
 ## Data Attribute Events
 
@@ -64,7 +70,11 @@ Track custom events without JavaScript by adding `data-luchy-event` to any HTML
 <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">
+<a
+  data-luchy-event="post-click"
+  data-luchy-payload-slug="hello-world"
+  href="/blog/hello-world"
+>
   Read Post
 </a>
 
@@ -99,53 +109,121 @@ window.luchy.trackEvent('Button Click', {
   page: 'home'
 });
 
-// Enable auto-tracking features
-window.luchy.enableAutoPageviews();
-window.luchy.enableAutoOutboundTracking();
-window.luchy.enableHashRouting();
+// Toggle auto-tracking features
+window.luchy.setOptions({ autoPageviews: true, hashRouting: false });
+
+// SPAs that learn who the user is after load: attribute everything from now
+// on to a signed token (rendered by your server), with optional props.
+window.luchy.identify(token, { role: 'admin' });
+
+// Back to anonymous, e.g. on logout.
+window.luchy.reset();
 ```
 
-## Server-Side Tracking
+`identify`/`reset` write through to the script tag's `data-identity` /
+`data-props`, so the tag stays the single source of truth.
 
-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.
+## Identity
+
+Luchy ties hits to your users only when your server vouches for them. An
+identity is `{ user, actor?, tenant? }` — `user` is the account being viewed
+as, `actor` the person actually acting when they differ (impersonation),
+`tenant` your own workspace/client id. Everything else (role, plan, …) goes in
+props.
 
-`luchy/server` carries no browser globals, so it runs in Node, Bun,
-Deno and Cloudflare Workers:
+The server signs it with the project's secret key (`lsk_…`, from the
+dashboard settings):
 
 ```ts
-import { createServerTracker } from 'luchy/server';
+import { signIdentity } 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)
-});
+const token = await signIdentity(
+  { user: user.id, tenant: String(workspace.id) },
+  env.LUCHY_SECRET
+);
+```
 
-await luchy.trackEvent({
-  name: 'order:placed',
-  pathname: '/checkout',
-  type: 'server',
-  payload: { plan: 'pro', amount: 29 }
-});
+The token is `base64url(JSON({ u, a?, t? })).base64url(HMAC-SHA256)`, signed
+with WebCrypto (Workers, Node ≥ 18, Bun, Deno). Ingest verifies it; a missing,
+unsigned or tampered token stores the hit anonymous — it is never rejected. The
+secret never leaves your server: only the token is rendered into the page.
+
+## Person profiles
+
+`user` is a stable id (`usr_7Hq2mXk9`, `42`), not something to read. Profile
+traits — a name, an email, a plan — are stored once per person with
+`identify`, server-side, authenticated with the secret key:
+
+```ts
+await luchy.identify(user.id, { name: user.name, email: user.email });
 ```
 
-Nothing here ever rejects — analytics must not break the request it is
-describing. Pass `onError` if you want failures in your logs.
+Traits merge into what is stored; `null` deletes one. The dashboard labels a
+person (and a support agent helping them) by `traits.name`, else
+`traits.email`, else the id. The wire call is
+`POST /api/ingest/identify` with `Authorization: Bearer <lsk_…>` and body
+`{ user, traits }`; the public ingest key is rejected there.
 
-Fire it after the response so it costs no latency. On Cloudflare Workers:
+## Server-Side Tracking (`luchy/server`)
+
+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
-ctx.waitUntil(luchy.trackEvent({ name: 'order:placed', pathname: '/checkout' }));
+import { createLuchy } from 'luchy/server';
+
+const luchy = createLuchy({
+  apiKey: env.LUCHY_API_KEY,
+  // optional: signs identities; without it identities are not sent
+  secret: env.LUCHY_SECRET,
+  // optional: the ingest base of a self-hosted dashboard
+  endpoint: 'https://dash.luchy.app/api/ingest',
+  // optional: false turns every call into a no-op
+  enabled: env.APP_ENV === 'production',
+  onError: (error) => logger.warn('[luchy] event dropped', error)
+});
+
+ctx.waitUntil(
+  luchy.track(
+    {
+      name: 'order:placed',
+      pathname: '/checkout',
+      type: 'server',
+      payload: { plan: 'pro', amount: 29 },
+      // forward the end user's request so the hit joins their session
+      userAgent: request.headers.get('user-agent') ?? undefined,
+      ip: request.headers.get('cf-connecting-ip') ?? undefined,
+      country: request.cf?.country,
+      language: 'es-DO'
+    },
+    { user: user.id, tenant: String(workspace.id) }
+  )
+);
+
+await luchy.pageview({ pathname: '/pricing', payload: { plan: 'pro' } });
 ```
 
+- `identify(user, traits)` stores profile traits (see
+  [Person profiles](#person-profiles)). It needs `secret`; without it the call
+  is a no-op and `onError` hears about it once.
+- `track(event, identity?)` and `pageview(pageview, identity?)` take an
+  identity object (signed with `secret`) or an already-signed token string.
+- **Without `secret`, an identity object is not sent at all** — ingest would
+  drop it unsigned anyway, so the hit is plainly anonymous.
+- `ip` is only used to compute the visitor hash and is never stored. Without
+  it, ingest uses the sender's own `cf-connecting-ip` — which, for a server,
+  is the server.
+- Nothing ever rejects — analytics must not break the request it is
+  describing. Pass `onError` if you want failures in your logs.
+
 ## API client (`luchy/api`)
 
-`createServerTracker` covers the two calls most apps make. `luchy/api`
+`createLuchy` 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
+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
@@ -166,10 +244,21 @@ await luchy.trackEvent({
 });
 
 // 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']
+const { current, delta } = await luchy.query({
+  from: '2025-01-01T00:00:00Z',
+  to: '2025-02-01T00:00:00Z',
+  metrics: ['events', 'users'],
+  breakdown: 'tenant', // or page, user, props.<key>, hour, weekday, …
+  filters: [['props.role', 'eq', 'admin']],
+  compare: 'previous_period'
+});
+
+// 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.
+const { rows } = await luchy.sql({
+  query:
+    'SELECT tenant, COUNT(*) AS n FROM events WHERE project_id = ? GROUP BY tenant',
+  params: ['project_id']
 });
 ```
 
@@ -184,7 +273,8 @@ 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
+`IngestSuccess`, `QueryRequest`, `QueryResponse`, `SqlRequest`, `SqlResponse`,
+plus the raw `paths` and
 `components`.
 
 ### Where the types come from
@@ -203,64 +293,124 @@ 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.
 
-## React Router on Cloudflare (`luchy/react-router`)
+## React Router (`luchy/react-router`)
+
+For React Router v7.9+ apps with middleware. Three pieces:
+
+- `luchyMiddleware` — a root route middleware. Every mutation React Router
+  serves becomes a server event, attributed to the request's identity.
+- `getLuchy(context)` — for the root loader: the browser script's config, with
+  the identity already signed.
+- `<LuchyScript {...luchy} />` — renders the browser script with
+  `data-identity` / `data-props`, so server events and browser pageviews land
+  in the same session.
 
 A React Router app already tells you what it did — in the request. Every
 console mutation is a form POST whose `intent` field names it (`rotate`,
 `invite-member`, `create-api-key`, …), every JSON API mutation is
 discriminated by its method, and every auth verb has a path that names the
-operation. So the event does not need to be emitted by hand from a route
-module, where it is only tracked once somebody remembers to instrument it: the
-Worker *derives* it from the request it is already holding. One hook, zero
-per-route code, and a new intent is tracked the day it is written.
-
-Two lines in the Worker's `fetch`:
-
-```ts
-import { createRequestTracker } from 'luchy/react-router';
-
-const tracker = createRequestTracker({
-  apiKey: LUCHY_API_KEY,
-  enabled: env.APP_ENV === 'production'
-});
-
-export default {
-  async fetch(request, env, ctx) {
-    const finish = tracker.begin(request);
-    const response = await requestHandler(request, loadContext);
-    finish(response, ctx);
-    return response;
-  }
-} satisfies ExportedHandler<Env>;
+operation. So the event is _derived_ from the request instead of emitted by
+hand from route modules: zero per-route code, and a new intent is tracked the
+day it is written.
+
+```tsx
+// app/root.tsx
+import { getLuchy, luchyMiddleware, LuchyScript } from 'luchy/react-router';
+
+export const middleware: Route.MiddlewareFunction[] = [
+  luchyMiddleware({
+    apiKey: env.LUCHY_API_KEY,
+    secret: env.LUCHY_SECRET,
+    enabled: env.APP_ENV === 'production',
+    // How to keep the event alive after the response. Nothing here imports
+    // `cloudflare:workers`; hand it whatever your runtime has.
+    waitUntil:
+      ({ context }) =>
+      (promise) =>
+        context.get(cfContext).ctx.waitUntil(promise),
+    identity: async ({ context }) => {
+      const s = await context.get(appContext).getMaybeSessionContext();
+      if (!s) {
+        return undefined;
+      }
+
+      return {
+        user: s.user.id,
+        tenant: String(s.workspaceId),
+        props: { role: s.role },
+        traits: { name: s.user.name, email: s.user.email }
+      };
+    }
+  })
+];
+
+export async function loader({ context }: Route.LoaderArgs) {
+  return { luchy: await getLuchy(context) };
+}
+
+export function Layout({ children }: { children: React.ReactNode }) {
+  const data = useRouteLoaderData<typeof loader>('root');
+
+  return (
+    <html lang="en">
+      <head>
+        {/* … */}
+        {data ? <LuchyScript {...data.luchy} /> : null}
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
 ```
 
-`begin` has to run *before* React Router gets the request: it is what clones
-the body, and once the handler has read it, it is gone. `finish` schedules
-everything else on `ctx.waitUntil`, so nothing about analytics is on the
-response's critical path, and nothing it does can throw into your handler.
-
-Events come out named `route:intent` — `team/:id:invite-member`,
-`applications:create` — with ids collapsed to `:id`, React Router's
-single-fetch `.data` suffix stripped (so a hydrated and a non-hydrated
-submission report the same name), and `/` mapped to `home`. The payload always
-carries `status`.
-
-| Option | Default | What it does |
-| --- | --- | --- |
-| `apiKey` | — | Luchy API key. The public ingest key is fine. |
-| `endpoint` | hosted API | API root, without a trailing slash. |
-| `enabled` | `true` | When false, everything is a no-op — no clone, no network. |
-| `ignorePrefixes` | `['/__manifest']` | Raw-pathname prefixes to drop. Yours are added to the default, not swapped for it. |
-| `ignoreRouteSuffixes` | `[]` | Normalized-route suffixes to drop, e.g. `/user-keys/validate`. |
-| `ignoreEvents` | `[]` | Fully-formed event names to drop, e.g. `notifications:markRead`. |
-| `trackFailures` | `false` | When true, 4xx/5xx are tracked too (tell them apart by `status`). |
-| `methodSuffix` | `false` | When true, an intent-less mutation is `route:post` / `route:delete` instead of bare `route`. |
-| `payload` | — | `(request, response) => payload`, merged over `status`. Runs inside `waitUntil`; a rejection costs the payload, not the event. |
-| `onError` | — | The only way to see failures. |
-
-The pieces are exported on their own too — `isMutatingMethod`,
-`carriesIntent`, `normalizeRoute`, `serverEventName` — if you want the naming
-without the hook.
+How it behaves:
+
+- Only mutations (`POST`/`PUT`/`PATCH`/`DELETE`) produce events. Reads are the
+  browser script's job.
+- Events are named `route:intent` — `team/:id:invite-member`,
+  `applications:create` — with ids collapsed to `:id`, React Router's
+  single-fetch `.data` suffix stripped (so a hydrated and a non-hydrated
+  submission report the same name), and `/` mapped to `home`.
+- The body is cloned before `next()` only when it can carry an `intent`
+  (urlencoded); the action still reads the original.
+- Redirects and responses thrown by actions are tracked with their real status
+  and re-thrown untouched.
+- The payload is the identity's `props` plus `status` (always the response
+  status — props cannot override it). The end user's `cf-connecting-ip`,
+  country (`request.cf.country` or `cf-ipcountry`), first `accept-language` tag
+  and user agent are forwarded.
+- `identity` is resolved lazily and at most once per request: only when an
+  event ships or `getLuchy` asks. A rejection is reported to `onError` and the
+  request is treated as anonymous.
+- `traits`, when the resolver returns them, are sent via `identify` through
+  the same `waitUntil` — at most once per isolate per hour for the same user
+  and traits (a small in-memory map, bounded at 1000 entries). Changed traits
+  go out on the next request. Needs `secret`; traits never reach the page.
+- `<LuchyScript>` must be server-rendered — React does not execute `<script>`
+  elements it creates on the client. Re-renders after login/logout update its
+  attributes, and the script picks them up on the next send.
+- Only requests React Router routes are seen. Anything your Worker answers
+  before handing over to React Router is invisible to the middleware.
+
+| Option                | Default           | What it does                                                                                 |
+| --------------------- | ----------------- | -------------------------------------------------------------------------------------------- |
+| `apiKey`              | —                 | Luchy API key. The public ingest key is fine.                                                |
+| `secret`              | —                 | Secret key. Without it no identity or traits are sent (props still are).                     |
+| `endpoint`            | hosted ingest     | Ingest base, without a trailing slash. Also what `getLuchy` hands the script.                |
+| `enabled`             | `true`            | When false no events are produced — no clone, no network. `getLuchy` keeps working.          |
+| `waitUntil`           | —                 | `(args) => (promise) => void`. Called only for requests that produce an event.               |
+| `identity`            | —                 | `(args) => ({ user, actor?, tenant?, props?, traits? }) \| undefined`, sync or async.        |
+| `ignorePrefixes`      | `['/__manifest']` | Raw-pathname prefixes to drop. Yours are added to the default.                               |
+| `ignoreRouteSuffixes` | `[]`              | Normalized-route suffixes to drop, e.g. `/user-keys/validate`.                               |
+| `ignoreEvents`        | `[]`              | Fully-formed event names to drop, e.g. `notifications:markRead`.                             |
+| `trackFailures`       | `false`           | When true, 4xx/5xx are tracked too (tell them apart by `status`).                            |
+| `methodSuffix`        | `false`           | When true, an intent-less mutation is `route:post` / `route:delete` instead of bare `route`. |
+| `onError`             | —                 | The only way to see failures.                                                                |
+
+`<LuchyScript>` also takes `src` (defaults to the CDN build) and `nonce`.
+
+The naming pieces are exported on their own too — `isMutatingMethod`,
+`carriesIntent`, `normalizeRoute`, `serverEventName`.
 
 ## Development
 

package/dist/api/index.d.ts

@@ -18,12 +18,18 @@ export type { components, paths };
 export type EventInput = components['schemas']['EventInput'];
 /** The body accepted by `POST /ingest/pageview`. */
 export type PageviewInput = components['schemas']['PageviewInput'];
+/** The body accepted by `POST /ingest/identify` (secret key only). */
+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 /query`. */
-export type QueryRequest = components['schemas']['QueryRequest'];
-/** The result of a successful `POST /query`. */
-export type QueryResponse = components['schemas']['QueryResponse'];
+/** 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'];
 /** The `GET /health` body. */
 export type HealthResponse = components['schemas']['HealthResponse'];
 /** A 400 from any endpoint. */
@@ -53,21 +59,25 @@ 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.
+     * the full document, so `api.POST('/analytics/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>;
+    sql(request: SqlRequest): Promise<SqlResponse>;
+    schema(): Promise<string>;
     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.
+ * (`query`, `sql`, `schema`, `health`), as opposed to the fire-and-forget
+ * tracking calls.
  *
  * ```ts
  * try {
- *   await luchy.query({ date_range: '7d', metrics: ['pageviews'] });
+ *   await luchy.sql({ query: 'SELECT COUNT(*) AS n FROM events' });
  * } catch (error) {
  *   if (error instanceof LuchyApiError) {
  *     console.error(error.status, error.body);
@@ -103,8 +113,10 @@ export declare class LuchyApiError extends Error {
  * });
  *
  * const stats = await luchy.query({
- *   date_range: '7d',
- *   metrics: ['pageviews', 'visitors']
+ *   from: '2025-01-01T00:00:00Z',
+ *   to: '2025-02-01T00:00:00Z',
+ *   metrics: ['pageviews', 'visitors'],
+ *   compare: 'previous_period'
  * });
  * ```
  */

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

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

package/dist/api/index.js

@@ -75,20 +75,22 @@ function createLuchyClient(options) {
       );
     },
     /**
-     * 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.
+     * Runs an analytics query against the key's project. 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']
+     * const { current } = await luchy.query({
+     *   from: '2025-01-01T00:00:00Z',
+     *   to: '2025-02-01T00:00:00Z',
+     *   metrics: ['events', 'users'],
+     *   breakdown: 'tenant',
+     *   filters: [['props.role', 'eq', 'admin']]
      * });
      * ```
      */
     async query(request) {
-      const { data, error, response } = await api.POST("/query", {
+      const { data, error, response } = await api.POST("/analytics/query", {
         body: request
       });
       if (error || !data) {
@@ -100,6 +102,42 @@ function createLuchyClient(options) {
       }
       return data;
     },
+    /**
+     * 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).
+     *
+     * ```ts
+     * const { rows } = await luchy.sql({
+     *   query: 'SELECT tenant, COUNT(*) AS n FROM events WHERE project_id = ? GROUP BY tenant',
+     *   params: ['project_1']
+     * });
+     * ```
+     */
+    async sql(request) {
+      const { data, error, response } = await api.POST("/analytics/sql", {
+        body: request
+      });
+      if (error || !data) {
+        throw new LuchyApiError(
+          `Luchy sql failed with ${response.status}`,
+          response.status,
+          error
+        );
+      }
+      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.
      *