luchy 0.1.0 → 0.2.0

package/README.md

@@ -203,6 +203,65 @@ 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`)
+
+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>;
+```
+
+`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.
+
 ## Development
 
 ### Build Scripts

package/dist/react-router.d.ts

@@ -0,0 +1,164 @@
+/**
+ * React Router (v7+) on Cloudflare Workers — server events derived from
+ * requests.
+ *
+ * A React Router app already says 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 instead of sprinkling `trackEvent` calls across route modules
+ * — where a new intent is only tracked once somebody remembers to instrument
+ * it — the Worker derives the event from the request it is already holding:
+ * normalized route + intent (or method). One hook, zero per-route code, and a
+ * new intent is tracked the day it is written.
+ *
+ * This module is server-only but not Cloudflare-only: the flush context is
+ * structural (`{ waitUntil }`), so anything with that shape works.
+ *
+ * @module
+ */
+/** A property bag. Nested objects are not supported by the ingest API. */
+export type LuchyRequestPayload = Record<string, string | number | boolean>;
+/**
+ * True for the methods worth an event.
+ *
+ * Reads are the browser tracker's job; only mutations describe what the app
+ * did.
+ *
+ * ```ts
+ * isMutatingMethod('post'); // true
+ * isMutatingMethod('GET'); // false
+ * ```
+ */
+export declare function isMutatingMethod(method: string): boolean;
+/**
+ * True when the request body is worth parsing for an `intent` field.
+ *
+ * Only urlencoded bodies are read: a multipart upload could be megabytes, and
+ * no route reads an intent out of one.
+ *
+ * ```ts
+ * carriesIntent(request.headers.get('content-type'));
+ * ```
+ */
+export declare function carriesIntent(contentType: string | null | undefined): boolean;
+/**
+ * Turns a pathname into a route name: `/users/aBc123.../identities` →
+ * `users/:id/identities`.
+ *
+ * Client-side submissions land on React Router's single-fetch URL
+ * (`/users/abc.data`), so the `.data` suffix is stripped — otherwise the same
+ * action would report under two names depending on whether the page was
+ * hydrated. `/` and the single-fetch root (`/_root.data`) both become `home`.
+ */
+export declare function normalizeRoute(pathname: string): string;
+/** What `serverEventName` needs to know about a finished request. */
+export type ServerEventInput = {
+    method: string;
+    /** The raw pathname, before normalization. */
+    pathname: string;
+    /** The response status. Only consulted when `trackFailures` is false. */
+    status: number;
+    /** The submitted `intent`, if the body carried one. */
+    intent?: string | null;
+};
+/** The naming and filtering knobs, shared by the tracker and the pure helper. */
+export type ServerEventNameConfig = Pick<RequestTrackerOptions, 'ignorePrefixes' | 'ignoreRouteSuffixes' | 'ignoreEvents' | 'trackFailures' | 'methodSuffix'>;
+/**
+ * The event name for a mutation, or `null` when the request is not worth an
+ * event (a read, machine traffic, an ignored route, a failure the app does not
+ * track).
+ *
+ * Names are `route:intent` — an intent alone is ambiguous (`delete` and
+ * `update` appear on several routes), the pair is not. Without an intent the
+ * name is the bare route, or `route:post` / `route:delete` when
+ * `methodSuffix` is on, which keeps a REST route's methods distinct.
+ *
+ * ```ts
+ * serverEventName({ method: 'POST', pathname: '/team', status: 200, intent: 'invite' });
+ * // 'team:invite'
+ * ```
+ */
+export declare function serverEventName(input: ServerEventInput, config?: ServerEventNameConfig): string | null;
+export type RequestTrackerOptions = {
+    /** A Luchy API key. The public ingest key is fine — it ships in the HTML. */
+    apiKey: string;
+    /** The API root, without a trailing slash. Defaults to the hosted API. */
+    endpoint?: string;
+    /**
+     * Defaults to `true`. When false every call is a no-op — no clone, no
+     * request read, no network — so apps can pass
+     * `env.APP_ENV === 'production'` and leave the wiring in place.
+     */
+    enabled?: boolean;
+    /**
+     * Raw-pathname prefixes to drop, matched before normalization. Merged with
+     * the built-in defaults (`/__manifest`) rather than replacing them.
+     */
+    ignorePrefixes?: string[];
+    /**
+     * Normalized-route suffixes to drop, e.g. `/user-keys/validate`. Matched on
+     * the route so that literal app ids in the path do not each need an entry.
+     */
+    ignoreRouteSuffixes?: string[];
+    /** Fully-formed event names to drop, e.g. `notifications:markRead`. */
+    ignoreEvents?: string[];
+    /**
+     * Defaults to `false`: a 4xx/5xx produces no event. Turn it on when failed
+     * mutations are themselves product signal (the `status` payload field tells
+     * them apart).
+     */
+    trackFailures?: boolean;
+    /**
+     * Defaults to `false`: an intent-less mutation is named after its route
+     * alone. Turn it on for REST-ish routes, where `PATCH` and `DELETE` on the
+     * same path should report as `route:patch` and `route:delete`.
+     */
+    methodSuffix?: boolean;
+    /**
+     * App enrichment — session ids, actor labels, plan names. It runs inside
+     * `waitUntil` (never on the request's critical path), its result is merged
+     * over the tracker's own `status` field, and a rejection is swallowed: a
+     * failed lookup costs the payload, not the event.
+     */
+    payload?: (request: Request, response: Response) => Promise<LuchyRequestPayload> | LuchyRequestPayload;
+    /** Called when anything in the pipeline fails. Nothing else surfaces it. */
+    onError?: (error: unknown) => void;
+};
+/**
+ * Flushes work after the response is sent. Structurally Cloudflare's
+ * `ExecutionContext`, declared here so this module imports no runtime types.
+ */
+export type FlushContext = {
+    waitUntil(promise: Promise<unknown>): void;
+};
+/** Ends a tracked request. Never throws, never blocks the response. */
+export type FinishFn = (response: Response, ctx: FlushContext) => void;
+export type RequestTracker = {
+    /**
+     * Called with the incoming request, before the React Router handler consumes
+     * its body. Returns the function to call with the response.
+     */
+    begin(request: Request): FinishFn;
+};
+/**
+ * Creates the request tracker: one hook in the Worker's `fetch`, and every
+ * mutation the app serves becomes an event.
+ *
+ * `begin` must run before the request is handed to React Router, because it is
+ * what clones the body — once the handler has read it, it is gone. `finish`
+ * does everything else on `ctx.waitUntil`, so the response is not held up by
+ * analytics.
+ *
+ * @example
+ * ```ts
+ * const tracker = createRequestTracker({ apiKey, enabled: env.APP_ENV === 'production' })
+ * // in fetch(request, env, ctx):
+ * const finish = tracker.begin(request)
+ * const response = await requestHandler(request, loadContext)
+ * finish(response, ctx)
+ * return response
+ * ```
+ */
+export declare function createRequestTracker(options: RequestTrackerOptions): RequestTracker;
+//# sourceMappingURL=react-router.d.ts.map

package/dist/react-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-router.d.ts","sourceRoot":"","sources":["../src/react-router.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,0EAA0E;AAC1E,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAe5E;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE7E;AAaD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQvD;AAED,qEAAqE;AACrE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF,iFAAiF;AACjF,MAAM,MAAM,qBAAqB,GAAG,IAAI,CACtC,qBAAqB,EACnB,gBAAgB,GAChB,qBAAqB,GACrB,cAAc,GACd,eAAe,GACf,cAAc,CACjB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,gBAAgB,EACvB,MAAM,GAAE,qBAA0B,GACjC,MAAM,GAAG,IAAI,CA0Bf;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CACR,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,QAAQ,KACf,OAAO,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAAC;IACxD,4EAA4E;IAC5E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC5C,CAAC;AAEF,uEAAuE;AACvE,MAAM,MAAM,QAAQ,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,YAAY,KAAK,IAAI,CAAC;AAEvE,MAAM,MAAM,cAAc,GAAG;IAC3B;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,CAAC;CACnC,CAAC;AAKF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAgFhB"}

package/dist/react-router.js

@@ -0,0 +1,107 @@
+import { createLuchyClient } from "./api/index.js";
+const MUTATING_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
+const DEFAULT_IGNORE_PREFIXES = ["/__manifest"];
+const INTENT_PATTERN = /^[A-Za-z0-9_-]{1,40}$/;
+function isMutatingMethod(method) {
+  return MUTATING_METHODS.has(method.toUpperCase());
+}
+function carriesIntent(contentType) {
+  return (contentType ?? "").includes("application/x-www-form-urlencoded");
+}
+function isIdSegment(segment) {
+  if (segment.length === 0) return false;
+  if (/^\d+$/.test(segment)) return true;
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(segment)) return true;
+  return segment.length >= 16 && /\d/.test(segment);
+}
+function normalizeRoute(pathname) {
+  const segments = pathname.replace(/\.data$/, "").split("/").filter(Boolean);
+  if (segments.length === 0) return "home";
+  if (segments.length === 1 && segments[0] === "_root") return "home";
+  return segments.map((s) => isIdSegment(s) ? ":id" : s).join("/");
+}
+function serverEventName(input, config = {}) {
+  const method = input.method.toUpperCase();
+  if (!MUTATING_METHODS.has(method)) return null;
+  if (!config.trackFailures && input.status >= 400) return null;
+  const prefixes = [
+    ...DEFAULT_IGNORE_PREFIXES,
+    ...config.ignorePrefixes ?? []
+  ];
+  if (prefixes.some((p) => input.pathname.startsWith(p))) return null;
+  const route = normalizeRoute(input.pathname);
+  if ((config.ignoreRouteSuffixes ?? []).some((s) => route.endsWith(s))) {
+    return null;
+  }
+  const intent = input.intent && INTENT_PATTERN.test(input.intent) ? input.intent : null;
+  const name = intent ? `${route}:${intent}` : config.methodSuffix ? `${route}:${method.toLowerCase()}` : route;
+  if ((config.ignoreEvents ?? []).includes(name)) return null;
+  return name;
+}
+const NOOP_FINISH = () => {
+};
+function createRequestTracker(options) {
+  const enabled = options.enabled ?? true;
+  const prefixes = [
+    ...DEFAULT_IGNORE_PREFIXES,
+    ...options.ignorePrefixes ?? []
+  ];
+  const client = createLuchyClient({
+    apiKey: options.apiKey,
+    endpoint: options.endpoint,
+    onError: options.onError
+  });
+  return {
+    begin(request) {
+      if (!enabled) return NOOP_FINISH;
+      if (!isMutatingMethod(request.method)) return NOOP_FINISH;
+      const url = new URL(request.url);
+      if (prefixes.some((p) => url.pathname.startsWith(p))) return NOOP_FINISH;
+      const clone = carriesIntent(request.headers.get("content-type")) ? request.clone() : null;
+      return (response, ctx) => {
+        ctx.waitUntil(
+          (async () => {
+            const intent = clone ? new URLSearchParams(await clone.text()).get("intent") : null;
+            const name = serverEventName(
+              {
+                method: request.method,
+                pathname: url.pathname,
+                status: response.status,
+                intent
+              },
+              options
+            );
+            if (!name) return;
+            let payload = { status: response.status };
+            if (options.payload) {
+              try {
+                const extra = await options.payload(request, response);
+                payload = { ...payload, ...extra };
+              } catch (error) {
+                options.onError?.(error);
+              }
+            }
+            await client.trackEvent({
+              name,
+              type: "server",
+              // The raw pathname, not the normalized route: the name carries
+              // the shape, the pathname keeps the detail.
+              pathname: url.pathname,
+              payload,
+              userAgent: request.headers.get("user-agent") ?? void 0
+            });
+          })().catch((error) => {
+            options.onError?.(error);
+          })
+        );
+      };
+    }
+  };
+}
+export {
+  carriesIntent,
+  createRequestTracker,
+  isMutatingMethod,
+  normalizeRoute,
+  serverEventName
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "luchy",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Luchy tracking - browser script + server-side tracker",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,6 +14,10 @@
       "types": "./dist/server.d.ts",
       "import": "./dist/server.js"
     },
+    "./react-router": {
+      "types": "./dist/react-router.d.ts",
+      "import": "./dist/react-router.js"
+    },
     "./api": {
       "types": "./dist/api/index.d.ts",
       "import": "./dist/api/index.js"