npm - @hellyeah/x-ray - Versions diffs - 0.1.0-beta.5 - Mend

@hellyeah/x-ray 0.1.0-beta.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (38) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,140 @@
+![X-Ray Analytics](https://github.com/finalroundai/xray-sdk/blob/main/.github/banner.png)
+<div align="center">
+  <strong>X-Ray Analytics SDK</strong>
+  <br />
+  <p>Privacy-friendly analytics for web and server applications</p>
+  <a href="https://www.npmjs.com/package/@hellyeah/x-ray"><img src="https://img.shields.io/npm/v/@hellyeah/x-ray.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@hellyeah/x-ray"><img src="https://img.shields.io/npm/dm/@hellyeah/x-ray.svg" alt="npm downloads" /></a>
+  <a href="https://github.com/finalroundai/xray-sdk/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@hellyeah/x-ray.svg" alt="license" /></a>
+</div>
+## Overview
+`@hellyeah/x-ray` allows you to track page views, custom events, and user identity across any JavaScript framework or server environment.
+All page views are automatically tracked by default. Custom events and user identification are available via a simple API.
+## Quickstart
+1. Install the package
+   ```bash
+   npm install @hellyeah/x-ray@beta
+   ```
+2. Add analytics to your app
+   **Next.js**
+   ```tsx
+   import { Analytics } from "@hellyeah/x-ray/next";
+   export default function RootLayout({ children }) {
+     return (
+       <html>
+         <body>
+           {children}
+           <Analytics websiteId="your-website-id" />
+         </body>
+       </html>
+     );
+   }
+   ```
+   **React**
+   ```tsx
+   import { Analytics } from "@hellyeah/x-ray/react";
+   function App() {
+     return (
+       <>
+         <Analytics websiteId="your-website-id" />
+         {/* your app */}
+       </>
+     );
+   }
+   ```
+   **Vue / Nuxt / Svelte / Remix / Astro** — see [Framework Guides](#frameworks) below.
+   **Vanilla JS**
+   ```ts
+   import { inject } from "@hellyeah/x-ray";
+   inject({ websiteId: "your-website-id" });
+   ```
+   **Server (Node.js / Bun)**
+   ```ts
+   import { XRay } from "@hellyeah/x-ray/server";
+   const xray = new XRay("your-website-id");
+   xray.track("signup", { distinctId: "user_42" });
+   // Before process exit, flush remaining events
+   await xray.shutdown();
+   ```
+   **Serverless / Edge (Vercel, AWS Lambda, Cloudflare Workers)**
+   In short-lived environments, set `flushAt: 1` and `flushInterval: 0` so events are sent immediately rather than batched:
+   ```ts
+   import { XRay } from "@hellyeah/x-ray/server";
+   const xray = new XRay("your-website-id", {
+     flushAt: 1,
+     flushInterval: 0,
+   });
+   xray.track("signup", { distinctId: "user_42" });
+   ```
+   Or use `trackImmediate` to bypass the queue entirely and await delivery:
+   ```ts
+   await xray.trackImmediate("signup", { distinctId: "user_42" });
+   ```
+3. Deploy your app and see data flowing in.
+## Frameworks
+| Framework | Import path              | Usage                                                 |
+| --------- | ------------------------ | ----------------------------------------------------- |
+| Next.js   | `@hellyeah/x-ray/next`   | `<Analytics />` component with Suspense boundary      |
+| React     | `@hellyeah/x-ray/react`  | `<Analytics />` component                             |
+| Remix     | `@hellyeah/x-ray/remix`  | `<Analytics />` component                             |
+| Vue       | `@hellyeah/x-ray/vue`    | `<Analytics />` component                             |
+| Svelte    | `@hellyeah/x-ray/svelte` | `injectAnalytics()` helper                            |
+| Nuxt      | `@hellyeah/x-ray/nuxt`   | `injectAnalytics()` + `<Analytics />`                 |
+| Astro     | `@hellyeah/x-ray/astro`  | Re-exports `inject` and `track`                       |
+| Server    | `@hellyeah/x-ray/server` | `XRay` class with batching, retry, and immediate send |
+| Vanilla   | `@hellyeah/x-ray`        | `inject()`, `track()`, `identify()`, `pageview()`     |
+## Custom Events
+```ts
+import { track } from "@hellyeah/x-ray";
+track("signup", { plan: "pro" });
+```
+For the full list of predefined conversion events and ad platform mappings, see the [Event Catalog](../../skills/references/event-catalog.md).
+## User Identification
+```ts
+import { identify } from "@hellyeah/x-ray";
+identify("user_42", { name: "Jane" });
+```
+## License
+[MIT](LICENSE)

package/dist/astro/index.cjs ADDED Viewed

@@ -0,0 +1,48 @@
+var import_node_module = require("node:module");
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+// src/astro/index.ts
+var exports_astro = {};
+__export(exports_astro, {
+  track: () => import_generic.track,
+  pageview: () => import_generic.pageview,
+  inject: () => import_generic.inject,
+  identify: () => import_generic.identify
+});
+module.exports = __toCommonJS(exports_astro);

package/dist/astro/index.d.cts ADDED Viewed

@@ -0,0 +1,36 @@
+/** Props accepted by the `<Analytics />` component and `inject()`. */
+type AnalyticsProps = {
+	/** Your x-ray website ID. */
+	websiteId: string;
+	/** Base URL of your x-ray server. @defaultValue `"https://xray-staging.hellyeahai.com"` */
+	hostUrl?: string;
+	/** Restrict tracking to this domain only. */
+	domains?: string;
+	/** Auto-track events on `data-hy-event` elements. @defaultValue true */
+	autoTrack?: boolean;
+	/** Custom `src` for the tracker script (overrides the default `/script.js`). */
+	src?: string;
+};
+/** Arbitrary event data passed to `track()`. */
+type EventData = Record<string, string | number | boolean | null>;
+/**
+* Inject the remote x-ray tracker `<script>` tag into `<head>`.
+*
+* Deduplicates — calling `inject()` twice with the same `websiteId` is a no-op.
+*/
+declare const inject: (props: AnalyticsProps) => void;
+/**
+* Track a custom event. If the tracker script hasn't loaded yet, the call is
+* buffered in `window._hy` and replayed once it initialises.
+*/
+declare const track: (name?: string, data?: EventData) => void;
+/**
+* Identify the current user. Buffered if the tracker script hasn't loaded yet.
+*/
+declare const identify: (id: string, data?: EventData) => void;
+/**
+* Record a pageview. Equivalent to calling `track()` with no arguments — the
+* remote tracker interprets this as a pageview event.
+*/
+declare const pageview: () => void;
+export { track, pageview, inject, identify, AnalyticsProps };

package/dist/astro/index.d.ts ADDED Viewed

@@ -0,0 +1,36 @@
+/** Props accepted by the `<Analytics />` component and `inject()`. */
+type AnalyticsProps = {
+	/** Your x-ray website ID. */
+	websiteId: string;
+	/** Base URL of your x-ray server. @defaultValue `"https://xray-staging.hellyeahai.com"` */
+	hostUrl?: string;
+	/** Restrict tracking to this domain only. */
+	domains?: string;
+	/** Auto-track events on `data-hy-event` elements. @defaultValue true */
+	autoTrack?: boolean;
+	/** Custom `src` for the tracker script (overrides the default `/script.js`). */
+	src?: string;
+};
+/** Arbitrary event data passed to `track()`. */
+type EventData = Record<string, string | number | boolean | null>;
+/**
+* Inject the remote x-ray tracker `<script>` tag into `<head>`.
+*
+* Deduplicates — calling `inject()` twice with the same `websiteId` is a no-op.
+*/
+declare const inject: (props: AnalyticsProps) => void;
+/**
+* Track a custom event. If the tracker script hasn't loaded yet, the call is
+* buffered in `window._hy` and replayed once it initialises.
+*/
+declare const track: (name?: string, data?: EventData) => void;
+/**
+* Identify the current user. Buffered if the tracker script hasn't loaded yet.
+*/
+declare const identify: (id: string, data?: EventData) => void;
+/**
+* Record a pageview. Equivalent to calling `track()` with no arguments — the
+* remote tracker interprets this as a pageview event.
+*/
+declare const pageview: () => void;
+export { track, pageview, inject, identify, AnalyticsProps };

package/dist/astro/index.js ADDED Viewed

@@ -0,0 +1,6 @@
+export {
+  track,
+  pageview,
+  inject,
+  identify
+};

package/dist/index.cjs ADDED Viewed

@@ -0,0 +1,49 @@
+var import_node_module = require("node:module");
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  track: () => import_generic.track,
+  pageview: () => import_generic.pageview,
+  inject: () => import_generic.inject,
+  identify: () => import_generic.identify,
+  cv: () => import_constants.cv
+});
+module.exports = __toCommonJS(exports_src);

package/dist/index.d.cts ADDED Viewed

@@ -0,0 +1,52 @@
+/** Props accepted by the `<Analytics />` component and `inject()`. */
+type AnalyticsProps = {
+	/** Your x-ray website ID. */
+	websiteId: string;
+	/** Base URL of your x-ray server. @defaultValue `"https://xray-staging.hellyeahai.com"` */
+	hostUrl?: string;
+	/** Restrict tracking to this domain only. */
+	domains?: string;
+	/** Auto-track events on `data-hy-event` elements. @defaultValue true */
+	autoTrack?: boolean;
+	/** Custom `src` for the tracker script (overrides the default `/script.js`). */
+	src?: string;
+};
+/** Arbitrary event data passed to `track()`. */
+type EventData = Record<string, string | number | boolean | null>;
+/**
+* Inject the remote x-ray tracker `<script>` tag into `<head>`.
+*
+* Deduplicates — calling `inject()` twice with the same `websiteId` is a no-op.
+*/
+declare const inject: (props: AnalyticsProps) => void;
+/**
+* Track a custom event. If the tracker script hasn't loaded yet, the call is
+* buffered in `window._hy` and replayed once it initialises.
+*/
+declare const track: (name?: string, data?: EventData) => void;
+/**
+* Identify the current user. Buffered if the tracker script hasn't loaded yet.
+*/
+declare const identify: (id: string, data?: EventData) => void;
+/**
+* Record a pageview. Equivalent to calling `track()` with no arguments — the
+* remote tracker interprets this as a pageview event.
+*/
+declare const pageview: () => void;
+declare const cv: {
+	readonly purchase: "cv_purchase";
+	readonly subscribe: "cv_subscribe";
+	readonly startTrial: "cv_start_trial";
+	readonly leadSubmit: "cv_lead_submit";
+	readonly registrationComplete: "cv_registration_complete";
+	readonly bookAppointment: "cv_book_appointment";
+	readonly contact: "cv_contact";
+	readonly submitApplication: "cv_submit_application";
+	readonly addToCart: "cv_add_to_cart";
+	readonly beginCheckout: "cv_begin_checkout";
+	readonly addPaymentInfo: "cv_add_payment_info";
+	readonly viewContent: "cv_view_content";
+	readonly search: "cv_search";
+};
+type ConversionEvent = (typeof cv)[keyof typeof cv];
+export { track, pageview, inject, identify, cv, EventData, ConversionEvent, AnalyticsProps };

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,52 @@
+/** Props accepted by the `<Analytics />` component and `inject()`. */
+type AnalyticsProps = {
+	/** Your x-ray website ID. */
+	websiteId: string;
+	/** Base URL of your x-ray server. @defaultValue `"https://xray-staging.hellyeahai.com"` */
+	hostUrl?: string;
+	/** Restrict tracking to this domain only. */
+	domains?: string;
+	/** Auto-track events on `data-hy-event` elements. @defaultValue true */
+	autoTrack?: boolean;
+	/** Custom `src` for the tracker script (overrides the default `/script.js`). */
+	src?: string;
+};
+/** Arbitrary event data passed to `track()`. */
+type EventData = Record<string, string | number | boolean | null>;
+/**
+* Inject the remote x-ray tracker `<script>` tag into `<head>`.
+*
+* Deduplicates — calling `inject()` twice with the same `websiteId` is a no-op.
+*/
+declare const inject: (props: AnalyticsProps) => void;
+/**
+* Track a custom event. If the tracker script hasn't loaded yet, the call is
+* buffered in `window._hy` and replayed once it initialises.
+*/
+declare const track: (name?: string, data?: EventData) => void;
+/**
+* Identify the current user. Buffered if the tracker script hasn't loaded yet.
+*/
+declare const identify: (id: string, data?: EventData) => void;
+/**
+* Record a pageview. Equivalent to calling `track()` with no arguments — the
+* remote tracker interprets this as a pageview event.
+*/
+declare const pageview: () => void;
+declare const cv: {
+	readonly purchase: "cv_purchase";
+	readonly subscribe: "cv_subscribe";
+	readonly startTrial: "cv_start_trial";
+	readonly leadSubmit: "cv_lead_submit";
+	readonly registrationComplete: "cv_registration_complete";
+	readonly bookAppointment: "cv_book_appointment";
+	readonly contact: "cv_contact";
+	readonly submitApplication: "cv_submit_application";
+	readonly addToCart: "cv_add_to_cart";
+	readonly beginCheckout: "cv_begin_checkout";
+	readonly addPaymentInfo: "cv_add_payment_info";
+	readonly viewContent: "cv_view_content";
+	readonly search: "cv_search";
+};
+type ConversionEvent = (typeof cv)[keyof typeof cv];
+export { track, pageview, inject, identify, cv, EventData, ConversionEvent, AnalyticsProps };

package/dist/index.js ADDED Viewed

@@ -0,0 +1,7 @@
+export {
+  track,
+  pageview,
+  inject,
+  identify,
+  cv
+};

package/dist/next/index.cjs ADDED Viewed

@@ -0,0 +1,145 @@
+"use client";
+'use client';
+var import_node_module = require("node:module");
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+// src/next/index.tsx
+var exports_next = {};
+__export(exports_next, {
+  track: () => track,
+  pageview: () => pageview,
+  identify: () => identify,
+  Analytics: () => Analytics2
+});
+module.exports = __toCommonJS(exports_next);
+var import_react2 = require("react");
+// src/react/index.tsx
+var import_react = require("react");
+// src/client/queue.ts
+var initQueue = () => {
+  if (typeof window !== "undefined") {
+    window._hy = window._hy || [];
+  }
+};
+// src/client/utils.ts
+var DEFAULT_HOST = "https://xray-staging.hellyeahai.com";
+var isBrowser = () => typeof window !== "undefined" && typeof document !== "undefined";
+var isDevelopment = () => typeof process !== "undefined" && process.env?.NODE_ENV === "development";
+var getDefaultHost = () => DEFAULT_HOST;
+// src/client/generic.ts
+var inject = (props) => {
+  if (!isBrowser())
+    return;
+  const { websiteId, domains, autoTrack = true, src } = props;
+  const hostUrl = props.hostUrl || getDefaultHost();
+  const scriptSrc = src || `${hostUrl}/script.js`;
+  if (document.head.querySelector(`script[src*="${scriptSrc}"]`))
+    return;
+  initQueue();
+  const dataset = {
+    websiteId,
+    hostUrl
+  };
+  if (domains)
+    dataset.domains = domains;
+  if (!autoTrack)
+    dataset.autoTrack = "false";
+  const script = document.createElement("script");
+  script.src = scriptSrc;
+  script.defer = true;
+  for (const [key, value] of Object.entries(dataset)) {
+    script.dataset[key] = value;
+  }
+  script.onerror = () => {
+    const msg = isDevelopment() ? "Please check if any ad blockers are enabled and try again." : "Check that the hostUrl is correct and the script is accessible.";
+    console.log(`[x-ray] Failed to load script from ${scriptSrc}. ${msg}`);
+  };
+  document.head.appendChild(script);
+};
+var track = (name, data) => {
+  if (!isBrowser())
+    return;
+  if (window.hy) {
+    window.hy.track(name, data);
+  } else {
+    initQueue();
+    window._hy = window._hy || [];
+    window._hy.push(["track", name, data]);
+  }
+};
+var identify = (id, data) => {
+  if (!isBrowser())
+    return;
+  if (window.hy) {
+    window.hy.identify(id, data);
+  } else {
+    initQueue();
+    window._hy = window._hy || [];
+    window._hy.push(["identify", id, data]);
+  }
+};
+var pageview = () => {
+  track();
+};
+// src/react/index.tsx
+var Analytics = (props) => {
+  import_react.useEffect(() => {
+    inject(props);
+  }, []);
+  return null;
+};
+// src/next/index.tsx
+var jsx_runtime = require("react/jsx-runtime");
+var AnalyticsInner = (props) => /* @__PURE__ */ jsx_runtime.jsx(Analytics, {
+  ...props
+});
+var Analytics2 = (props) => /* @__PURE__ */ jsx_runtime.jsx(import_react2.Suspense, {
+  fallback: null,
+  children: /* @__PURE__ */ jsx_runtime.jsx(AnalyticsInner, {
+    ...props
+  })
+});

package/dist/next/index.d.cts ADDED Viewed

@@ -0,0 +1,32 @@
+import { ReactNode } from "react";
+/** Props accepted by the `<Analytics />` component and `inject()`. */
+type AnalyticsProps = {
+	/** Your x-ray website ID. */
+	websiteId: string;
+	/** Base URL of your x-ray server. @defaultValue `"https://xray-staging.hellyeahai.com"` */
+	hostUrl?: string;
+	/** Restrict tracking to this domain only. */
+	domains?: string;
+	/** Auto-track events on `data-hy-event` elements. @defaultValue true */
+	autoTrack?: boolean;
+	/** Custom `src` for the tracker script (overrides the default `/script.js`). */
+	src?: string;
+};
+/** Arbitrary event data passed to `track()`. */
+type EventData = Record<string, string | number | boolean | null>;
+/**
+* Track a custom event. If the tracker script hasn't loaded yet, the call is
+* buffered in `window._hy` and replayed once it initialises.
+*/
+declare const track: (name?: string, data?: EventData) => void;
+/**
+* Identify the current user. Buffered if the tracker script hasn't loaded yet.
+*/
+declare const identify: (id: string, data?: EventData) => void;
+/**
+* Record a pageview. Equivalent to calling `track()` with no arguments — the
+* remote tracker interprets this as a pageview event.
+*/
+declare const pageview: () => void;
+declare const Analytics: (props: AnalyticsProps) => ReactNode;
+export { track, pageview, identify, AnalyticsProps, Analytics };

package/dist/next/index.d.ts ADDED Viewed

@@ -0,0 +1,32 @@
+import { ReactNode } from "react";
+/** Props accepted by the `<Analytics />` component and `inject()`. */
+type AnalyticsProps = {
+	/** Your x-ray website ID. */
+	websiteId: string;
+	/** Base URL of your x-ray server. @defaultValue `"https://xray-staging.hellyeahai.com"` */
+	hostUrl?: string;
+	/** Restrict tracking to this domain only. */
+	domains?: string;
+	/** Auto-track events on `data-hy-event` elements. @defaultValue true */
+	autoTrack?: boolean;
+	/** Custom `src` for the tracker script (overrides the default `/script.js`). */
+	src?: string;
+};
+/** Arbitrary event data passed to `track()`. */
+type EventData = Record<string, string | number | boolean | null>;
+/**
+* Track a custom event. If the tracker script hasn't loaded yet, the call is
+* buffered in `window._hy` and replayed once it initialises.
+*/
+declare const track: (name?: string, data?: EventData) => void;
+/**
+* Identify the current user. Buffered if the tracker script hasn't loaded yet.
+*/
+declare const identify: (id: string, data?: EventData) => void;
+/**
+* Record a pageview. Equivalent to calling `track()` with no arguments — the
+* remote tracker interprets this as a pageview event.
+*/
+declare const pageview: () => void;
+declare const Analytics: (props: AnalyticsProps) => ReactNode;
+export { track, pageview, identify, AnalyticsProps, Analytics };