@hexclave/js 1.0.2 → 1.0.5

package/src/lib/hexclave-app/apps/implementations/common.ts

@@ -0,0 +1,190 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { InternalSession } from "@hexclave/shared/dist/sessions";
+import { AsyncCache } from "@hexclave/shared/dist/utils/caches";
+import { isBrowserLike } from "@hexclave/shared/dist/utils/env";
+import { HexclaveAssertionError, captureError, concatStacktraces, throwErr } from "@hexclave/shared/dist/utils/errors";
+import { createGlobal, getGlobal } from "@hexclave/shared/dist/utils/globals";
+import { filterUndefined, omit } from "@hexclave/shared/dist/utils/objects";
+import { ReactPromise, runAsynchronously } from "@hexclave/shared/dist/utils/promises";
+import { suspendIfSsr, use } from "@hexclave/shared/dist/utils/react";
+import { Result } from "@hexclave/shared/dist/utils/results";
+import { Store } from "@hexclave/shared/dist/utils/stores";
+import { getDefaultApiUrls } from "@hexclave/shared/dist/utils/urls";
+import { envVars } from "../../../env";
+import { HandlerUrlOptions, ResolvedHandlerUrls, hexclaveAppInternalsSymbol } from "../../common";
+import { resolveHandlerUrls } from "../../url-targets";
+
+export const clientVersion = "STACK_COMPILE_TIME_CLIENT_PACKAGE_VERSION_SENTINEL";
+if (clientVersion.startsWith("STACK_COMPILE_TIME")) {
+  throw new HexclaveAssertionError("Client version was not replaced. Something went wrong during build!");
+}
+
+const replaceHexclavePortPrefix = <T extends string | undefined>(input: T): T => {
+  if (!input) return input;
+  const prefix = envVars.NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX;
+  return prefix ? input.replace(/\$\{NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81\}/g, prefix) as T : input;
+};
+
+
+export const createCache = <D extends any[], T>(fetcher: (dependencies: D) => Promise<T>) => {
+  return new AsyncCache<D, Result<T>>(
+    async (dependencies) => await Result.fromThrowingAsync(async () => await fetcher(dependencies)),
+    {},
+  );
+};
+
+export const createCacheBySession = <D extends any[], T>(fetcher: (session: InternalSession, extraDependencies: D) => Promise<T> ) => {
+  return new AsyncCache<[InternalSession, ...D], Result<T>>(
+    async ([session, ...extraDependencies]) => await Result.fromThrowingAsync(async () => await fetcher(session, extraDependencies)),
+    {
+      onSubscribe: ([session], refresh) => {
+        const handler = session.onInvalidate(() => refresh());
+        return () => handler.unsubscribe();
+      },
+    },
+  );
+};
+
+
+type AppLike = { [hexclaveAppInternalsSymbol]: { getConstructorOptions: () => any } };
+export function resolveConstructorOptions<T extends { inheritsFrom?: AppLike }>(options: T): T & { inheritsFrom?: undefined } {
+  return {
+    ...options.inheritsFrom?.[hexclaveAppInternalsSymbol].getConstructorOptions() ?? {},
+    ...filterUndefined(omit(options, ["inheritsFrom"])),
+  };
+}
+
+export function getUrls(partial: HandlerUrlOptions, options: { projectId: string }): ResolvedHandlerUrls {
+  return resolveHandlerUrls({
+    urls: partial,
+    projectId: options.projectId,
+  });
+}
+
+export function getDefaultProjectId() {
+  return envVars.NEXT_PUBLIC_STACK_PROJECT_ID || envVars.STACK_PROJECT_ID || throwErr(new Error("Welcome to Hexclave! It seems that you haven't provided a project ID. Please create a project on the Hexclave dashboard at https://app.hexclave.com and put it in the NEXT_PUBLIC_STACK_PROJECT_ID environment variable."));
+}
+
+export function getDefaultPublishableClientKey() {
+  return envVars.NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY || envVars.STACK_PUBLISHABLE_CLIENT_KEY;
+}
+
+export function getDefaultSecretServerKey() {
+  return envVars.STACK_SECRET_SERVER_KEY || throwErr(new Error("No secret server key provided. Please copy your key from the Hexclave dashboard and put it in the STACK_SECRET_SERVER_KEY environment variable."));
+}
+
+export function getDefaultSuperSecretAdminKey() {
+  return envVars.STACK_SUPER_SECRET_ADMIN_KEY || throwErr(new Error("No super secret admin key provided. Please copy your key from the Hexclave dashboard and put it in the STACK_SUPER_SECRET_ADMIN_KEY environment variable."));
+}
+
+export function getDefaultExtraRequestHeaders() {
+  return JSON.parse(envVars.NEXT_PUBLIC_STACK_EXTRA_REQUEST_HEADERS || envVars.STACK_EXTRA_REQUEST_HEADERS || '{}');
+}
+
+/**
+ * Returns the base URL for the Stack API.
+ *
+ * The URL can be specified in several ways, in order of precedence:
+ * 1. Directly through userSpecifiedBaseUrl parameter as string or browser/server object
+ * 2. Through environment variables:
+ *    - Browser: NEXT_PUBLIC_BROWSER_STACK_API_URL
+ *    - Server: NEXT_PUBLIC_SERVER_STACK_API_URL
+ *    - Fallback: NEXT_PUBLIC_STACK_API_URL or NEXT_PUBLIC_STACK_URL
+ * 3. Default base URL if none of the above are specified
+ *
+ * The function also ensures the URL doesn't end with a trailing slash
+ * by removing it if present.
+ *
+ * @param userSpecifiedBaseUrl - Optional URL override as string or {browser, server} object
+ * @returns The configured base URL without trailing slash
+
+ */
+export function getBaseUrl(userSpecifiedBaseUrl: string | { browser: string, server: string } | undefined) {
+  let url;
+  if (userSpecifiedBaseUrl) {
+    if (typeof userSpecifiedBaseUrl === "string") {
+      url = userSpecifiedBaseUrl;
+    } else {
+      if (isBrowserLike()) {
+        url = userSpecifiedBaseUrl.browser;
+      } else {
+        url = userSpecifiedBaseUrl.server;
+      }
+    }
+  } else {
+    // note: NEXT_PUBLIC_BROWSER_STACK_API_URL was renamed to NEXT_PUBLIC_STACK_API_URL_BROWSER, and NEXT_PUBLIC_STACK_URL to NEXT_PUBLIC_STACK_API_URL
+    if (isBrowserLike()) {
+      url = envVars.NEXT_PUBLIC_BROWSER_STACK_API_URL || envVars.NEXT_PUBLIC_STACK_API_URL_BROWSER || envVars.STACK_API_URL_BROWSER;
+    } else {
+      url = envVars.NEXT_PUBLIC_SERVER_STACK_API_URL || envVars.NEXT_PUBLIC_STACK_API_URL_SERVER || envVars.STACK_API_URL_SERVER;
+    }
+    url = url || envVars.NEXT_PUBLIC_STACK_API_URL || envVars.STACK_API_URL || envVars.NEXT_PUBLIC_STACK_URL || defaultBaseUrl;
+  }
+
+  return replaceHexclavePortPrefix(url.endsWith('/') ? url.slice(0, -1) : url);
+}
+
+export const defaultBaseUrl = "https://api.hexclave.com";
+export const defaultAnalyticsBaseUrl = "https://r.hexclave.com";
+
+const analyticsBaseUrlsByApiBaseUrl = new Map<string, string>([
+  [defaultBaseUrl, defaultAnalyticsBaseUrl],
+  ["https://api.stack-auth.com", "https://r.stack-auth.com"],
+]);
+
+export function getAnalyticsBaseUrl(regularBaseUrl: string): string {
+  return analyticsBaseUrlsByApiBaseUrl.get(regularBaseUrl) ?? regularBaseUrl;
+}
+
+
+function fetchBackendUrlsInBackground(primaryBaseUrl: string): void {
+  createGlobal('__stack-fetch-backend-urls-started', () => {
+    runAsynchronously(async () => {
+      try {
+        const res = await fetch(`${primaryBaseUrl}/api/v1/internal/backend-urls`);
+        if (!res.ok) {
+          return;
+        }
+        const data = await res.json();
+        if (!Array.isArray(data.urls) || !data.urls.every((u: unknown) => typeof u === 'string')) {
+          return;
+        }
+        createGlobal('__stack-fetched-backend-urls', () => data.urls as string[]);
+      } catch (e) {
+        captureError('fetch-backend-urls-in-background', e);
+      }
+    });
+    return true;
+  });
+}
+
+export function resolveApiUrls(userExplicitBaseUrl: string | { browser: string, server: string } | undefined): () => string[] {
+  return () => {
+    if (userExplicitBaseUrl != null) {
+      return [getBaseUrl(userExplicitBaseUrl)];
+    }
+    const primary = getBaseUrl(undefined);
+    // Always try to fetch server-configured URLs (supports custom domains via
+    // STACK_BACKEND_URLS_CONFIG). Hardcoded fallbacks are used as a default
+    // until the background fetch completes.
+    fetchBackendUrlsInBackground(primary);
+    return getGlobal('__stack-fetched-backend-urls') ?? getDefaultApiUrls(primary);
+  };
+}
+
+export type TokenObject = {
+  accessToken: string | null,
+  refreshToken: string | null,
+};
+
+export function createEmptyTokenStore() {
+  return new Store<TokenObject>({
+    refreshToken: null,
+    accessToken: null,
+  });
+}
+
+

package/src/lib/hexclave-app/apps/implementations/event-tracker.test.ts

@@ -0,0 +1,105 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+// @vitest-environment jsdom
+
+import { Result } from "@hexclave/shared/dist/utils/results";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { EventTracker } from "./event-tracker";
+
+async function advancePastFlush() {
+  await vi.advanceTimersByTimeAsync(10_000);
+  await Promise.resolve();
+}
+
+function getSentEventTypes(sentBodies: string[]) {
+  const [body] = sentBodies;
+
+  const payload = JSON.parse(body);
+  if (typeof payload !== "object" || payload === null || !("events" in payload) || !Array.isArray(payload.events)) {
+    throw new Error("Expected analytics batch payload to include an events array.");
+  }
+
+  return (payload.events as { event_type: string }[]).map((event) => event.event_type);
+}
+
+describe("EventTracker", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("captures events when browser globals are exposed as accessor descriptors", async () => {
+    vi.useFakeTimers();
+    document.body.innerHTML = "<button>Open project</button>";
+
+    const screenDescriptor = Object.getOwnPropertyDescriptor(window, "screen");
+    const historyDescriptor = Object.getOwnPropertyDescriptor(window, "history");
+    expect(screenDescriptor?.value).toBeUndefined();
+    expect(historyDescriptor?.value).toBeUndefined();
+    expect(screenDescriptor?.get).toBeTypeOf("function");
+    expect(historyDescriptor?.get).toBeTypeOf("function");
+
+    const sentBodies: string[] = [];
+    const tracker = new EventTracker({
+      projectId: "internal",
+      sendBatch: async (body) => {
+        sentBodies.push(body);
+        return Result.ok(new Response());
+      },
+    });
+
+    try {
+      tracker.start();
+      document.querySelector("button")?.dispatchEvent(new MouseEvent("click", {
+        bubbles: true,
+        clientX: 12,
+        clientY: 34,
+      }));
+
+      await advancePastFlush();
+
+      expect(getSentEventTypes(sentBodies)).toMatchInlineSnapshot(`
+        [
+          "$page-view",
+          "$click",
+        ]
+      `);
+    } finally {
+      tracker.stop();
+    }
+  });
+
+  it("captures client-side navigations when history is exposed as an accessor descriptor", async () => {
+    vi.useFakeTimers();
+
+    const historyDescriptor = Object.getOwnPropertyDescriptor(window, "history");
+    expect(historyDescriptor?.value).toBeUndefined();
+    expect(historyDescriptor?.get).toBeTypeOf("function");
+
+    const sentBodies: string[] = [];
+    const tracker = new EventTracker({
+      projectId: "internal",
+      sendBatch: async (body) => {
+        sentBodies.push(body);
+        return Result.ok(new Response());
+      },
+    });
+
+    try {
+      tracker.start();
+      window.history.pushState({}, "", "/projects/test-project");
+
+      await advancePastFlush();
+
+      expect(getSentEventTypes(sentBodies)).toMatchInlineSnapshot(`
+        [
+          "$page-view",
+          "$page-view",
+        ]
+      `);
+    } finally {
+      tracker.stop();
+    }
+  });
+});

package/src/lib/hexclave-app/apps/implementations/event-tracker.ts

@@ -0,0 +1,306 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { isBrowserLike } from "@hexclave/shared/dist/utils/env";
+import { runAsynchronously } from "@hexclave/shared/dist/utils/promises";
+import { Result } from "@hexclave/shared/dist/utils/results";
+import { generateUuid } from "./session-replay";
+
+const FLUSH_INTERVAL_MS = 10_000;
+const MAX_EVENTS_PER_BATCH = 50;
+const MAX_APPROX_BYTES_PER_BATCH = 64_000;
+
+function hasScreenDimensions(value: unknown): value is { width: number, height: number } {
+  if (value == null || typeof value !== "object") {
+    return false;
+  }
+  if (!("width" in value) || !("height" in value)) {
+    return false;
+  }
+  return typeof value.width === "number" && typeof value.height === "number";
+}
+
+function hasHistoryMethods(value: unknown): value is { pushState: History["pushState"], replaceState: History["replaceState"] } {
+  if (value == null || typeof value !== "object") {
+    return false;
+  }
+  if (!("pushState" in value) || !("replaceState" in value)) {
+    return false;
+  }
+  return typeof value.pushState === "function" && typeof value.replaceState === "function";
+}
+
+export type EventTrackerDeps = {
+  projectId: string,
+  sendBatch: (body: string, options: { keepalive: boolean }) => Promise<Result<Response, Error>>,
+};
+
+type TrackedEvent = {
+  event_type: "$page-view" | "$click",
+  event_at_ms: number,
+  data: Record<string, unknown>,
+};
+
+export class EventTracker {
+  private _started = false;
+  private _cancelled = false;
+  private _detachListeners: (() => void) | null = null;
+  private _flushTimer: ReturnType<typeof setInterval> | null = null;
+  private _events: TrackedEvent[] = [];
+  private _approxBytes = 0;
+  private _lastUrl: string | null = null;
+  private readonly _sessionReplaySegmentId: string;
+  private readonly _deps: EventTrackerDeps;
+
+  private _originalPushState: History["pushState"] | null = null;
+  private _originalReplaceState: History["replaceState"] | null = null;
+
+  constructor(deps: EventTrackerDeps) {
+    this._deps = deps;
+    this._sessionReplaySegmentId = generateUuid();
+  }
+
+  start() {
+    if (this._started) return;
+    if (!isBrowserLike()) return;
+    if (
+      typeof window.addEventListener !== "function"
+      || typeof window.removeEventListener !== "function"
+      || typeof document.addEventListener !== "function"
+      || typeof document.removeEventListener !== "function"
+      || !hasScreenDimensions(window.screen)
+    ) {
+      return;
+    }
+    this._started = true;
+
+    this._setupPageViewCapture();
+    this._setupClickCapture();
+    this._setupPageHideListeners();
+
+    this._flushTimer = setInterval(() => this._tick(), FLUSH_INTERVAL_MS);
+  }
+
+  stop() {
+    this._cancelled = true;
+    if (this._flushTimer !== null) {
+      clearInterval(this._flushTimer);
+      this._flushTimer = null;
+    }
+    runAsynchronously(() => this._flush({ keepalive: true }));
+    this._teardown();
+  }
+
+  clearBuffer() {
+    this._events = [];
+    this._approxBytes = 0;
+  }
+
+  private _pushEvent(event: TrackedEvent) {
+    this._events.push(event);
+    this._approxBytes += JSON.stringify(event).length;
+    if (this._events.length >= MAX_EVENTS_PER_BATCH || this._approxBytes >= MAX_APPROX_BYTES_PER_BATCH) {
+      runAsynchronously(() => this._flush({ keepalive: false }));
+    }
+  }
+
+  private _capturePageView(entryType: "initial" | "push" | "replace" | "pop") {
+    const screenObject = window.screen;
+    if (!hasScreenDimensions(screenObject)) {
+      return;
+    }
+
+    const url = window.location.href;
+    if (url === this._lastUrl && entryType !== "initial") return;
+    this._lastUrl = url;
+
+    this._pushEvent({
+      event_type: "$page-view",
+      event_at_ms: Date.now(),
+      data: {
+        url,
+        path: window.location.pathname,
+        referrer: document.referrer,
+        title: document.title,
+        entry_type: entryType,
+        viewport_width: window.innerWidth,
+        viewport_height: window.innerHeight,
+        screen_width: screenObject.width,
+        screen_height: screenObject.height,
+      },
+    });
+  }
+
+  private _setupPageViewCapture() {
+    // Fire initial page-view
+    this._capturePageView("initial");
+    const historyObject = window.history;
+    if (!hasHistoryMethods(historyObject)) {
+      return;
+    }
+    const originalPushState = historyObject.pushState;
+    const originalReplaceState = historyObject.replaceState;
+
+    // Monkey-patch history.pushState
+    this._originalPushState = (...args: Parameters<History["pushState"]>) => originalPushState.apply(historyObject, args);
+    historyObject.pushState = (...args: Parameters<History["pushState"]>) => {
+      this._originalPushState!(...args);
+      this._capturePageView("push");
+    };
+
+    // Monkey-patch history.replaceState
+    this._originalReplaceState = (...args: Parameters<History["replaceState"]>) => originalReplaceState.apply(historyObject, args);
+    historyObject.replaceState = (...args: Parameters<History["replaceState"]>) => {
+      this._originalReplaceState!(...args);
+      this._capturePageView("replace");
+    };
+
+    // Listen for popstate (back/forward navigation)
+    window.addEventListener("popstate", this._onPopState);
+  }
+
+  private readonly _onPopState = () => {
+    this._capturePageView("pop");
+  };
+
+  private _buildSelector(element: Element): string {
+    const parts: string[] = [];
+    let current: Element | null = element;
+    let depth = 0;
+
+    while (current && depth < 5) {
+      let part = current.tagName.toLowerCase();
+      if (current.id) {
+        part += `#${current.id}`;
+        parts.unshift(part);
+        break;
+      }
+      if (current.className && typeof current.className === "string") {
+        const classes = current.className.trim().split(/\s+/).filter(Boolean);
+        if (classes.length > 0) {
+          part += `.${classes.join(".")}`;
+        }
+      }
+      parts.unshift(part);
+      current = current.parentElement;
+      depth++;
+    }
+
+    return parts.join(" > ");
+  }
+
+  private _findNearestAnchorHref(element: Element): string | null {
+    let current: Element | null = element;
+    while (current) {
+      if (current.tagName === "A" && current.hasAttribute("href")) {
+        return current.getAttribute("href");
+      }
+      current = current.parentElement;
+    }
+    return null;
+  }
+
+  private readonly _onClickCapture = (event: MouseEvent) => {
+    const target = event.target;
+    if (!(target instanceof Element)) return;
+
+    this._pushEvent({
+      event_type: "$click",
+      event_at_ms: Date.now(),
+      data: {
+        tag_name: target.tagName.toLowerCase(),
+        text: target.textContent.trim().substring(0, 200),
+        href: this._findNearestAnchorHref(target),
+        selector: this._buildSelector(target),
+        x: event.clientX,
+        y: event.clientY,
+        page_x: event.pageX,
+        page_y: event.pageY,
+        viewport_width: window.innerWidth,
+        viewport_height: window.innerHeight,
+      },
+    });
+  };
+
+  private _setupClickCapture() {
+    document.addEventListener("click", this._onClickCapture, { capture: true });
+  }
+
+  private readonly _onPageHide = () => {
+    runAsynchronously(() => this._flush({ keepalive: true }));
+  };
+
+  private _setupPageHideListeners() {
+    window.addEventListener("pagehide", this._onPageHide);
+    document.addEventListener("visibilitychange", this._onPageHide);
+    this._detachListeners = () => {
+      window.removeEventListener("pagehide", this._onPageHide);
+      document.removeEventListener("visibilitychange", this._onPageHide);
+    };
+  }
+
+  private _teardown() {
+    if (this._detachListeners) {
+      this._detachListeners();
+      this._detachListeners = null;
+    }
+
+    // Restore history methods
+    const historyObject = window.history;
+    if (hasHistoryMethods(historyObject)) {
+      if (this._originalPushState) {
+        historyObject.pushState = this._originalPushState;
+      }
+      if (this._originalReplaceState) {
+        historyObject.replaceState = this._originalReplaceState;
+      }
+    }
+    this._originalPushState = null;
+    this._originalReplaceState = null;
+
+    window.removeEventListener("popstate", this._onPopState);
+    document.removeEventListener("click", this._onClickCapture, { capture: true });
+
+    this._events = [];
+    this._approxBytes = 0;
+  }
+
+  private async _flush(options: { keepalive: boolean }) {
+    if (this._events.length === 0) return;
+
+    const nowMs = Date.now();
+
+    const batchId = generateUuid();
+    const payload = {
+      session_replay_segment_id: this._sessionReplaySegmentId,
+      batch_id: batchId,
+      sent_at_ms: nowMs,
+      events: this._events,
+    };
+
+    this._events = [];
+    this._approxBytes = 0;
+
+    const res = await this._deps.sendBatch(
+      JSON.stringify(payload),
+      { keepalive: options.keepalive },
+    );
+
+    if (res.status === "error") {
+      console.warn("EventTracker flush failed:", res.error);
+      return;
+    }
+
+    if (!res.data.ok) {
+      console.warn("EventTracker flush failed:", res.data.status, await res.data.text());
+    }
+  }
+
+  private _tick() {
+    if (this._cancelled) return;
+    if (this._events.length > 0) {
+      runAsynchronously(() => this._flush({ keepalive: false }));
+    }
+  }
+}

package/src/lib/hexclave-app/apps/implementations/index.ts

@@ -0,0 +1,35 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+
+import { scrambleDuringCompileTime } from "@hexclave/shared/dist/utils/compile-time";
+import { _HexclaveAdminAppImplIncomplete } from "./admin-app-impl";
+import { _HexclaveClientAppImplIncomplete } from "./client-app-impl";
+import { _HexclaveServerAppImplIncomplete } from "./server-app-impl";
+
+
+/**
+ * Prevents a circular dependency between the client and admin apps. For more information, see the documentation comment
+ * of `_HexclaveClientAppImplIncomplete.LazyStackAdminAppImpl`.
+ *
+ * Note: This is an explicitly defined function that returns the new values (and not a barrel file with top-level side
+ * effects) because we have `sideEffects: false` in the package.json, and so it would be tree-shaken away if we just
+ * exported the values directly.
+ */
+function complete() {
+  _HexclaveClientAppImplIncomplete.LazyStackAdminAppImpl.value = _HexclaveAdminAppImplIncomplete;
+
+  return {
+    _HexclaveAdminAppImpl: scrambleDuringCompileTime(_HexclaveAdminAppImplIncomplete),
+    _HexclaveClientAppImpl: scrambleDuringCompileTime(_HexclaveClientAppImplIncomplete),
+    _HexclaveServerAppImpl: scrambleDuringCompileTime(_HexclaveServerAppImplIncomplete),
+  };
+}
+
+export const {
+  _HexclaveAdminAppImpl,
+  _HexclaveClientAppImpl,
+  _HexclaveServerAppImpl
+} = complete();
+