@hexclave/js 1.0.2 → 1.0.5

package/src/dev-tool/dev-tool-trigger-position.test.ts

@@ -0,0 +1,113 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { describe, expect, it } from "vitest";
+import { clampTriggerPosition, getSnappedTriggerPlacement, resolveTriggerPosition } from "./dev-tool-trigger-position";
+
+const triggerSize = { width: 36, height: 36 };
+const viewport = { width: 1000, height: 700 };
+
+describe("corner snapping", () => {
+  it("snaps to bottom-right when trigger is in the bottom-right quadrant", () => {
+    const placement = getSnappedTriggerPlacement({ left: 800, top: 600 }, triggerSize, viewport);
+    expect(placement).toEqual({ corner: "bottom-right" });
+  });
+
+  it("snaps to top-left when trigger is in the top-left quadrant", () => {
+    const placement = getSnappedTriggerPlacement({ left: 10, top: 20 }, triggerSize, viewport);
+    expect(placement).toEqual({ corner: "top-left" });
+  });
+
+  it("snaps to top-right when trigger is in the top-right quadrant", () => {
+    const placement = getSnappedTriggerPlacement({ left: 900, top: 50 }, triggerSize, viewport);
+    expect(placement).toEqual({ corner: "top-right" });
+  });
+
+  it("snaps to bottom-left when trigger is in the bottom-left quadrant", () => {
+    const placement = getSnappedTriggerPlacement({ left: 50, top: 650 }, triggerSize, viewport);
+    expect(placement).toEqual({ corner: "bottom-left" });
+  });
+});
+
+describe("corner position resolution", () => {
+  it("resolves bottom-right to margin from bottom and right edges", () => {
+    const pos = resolveTriggerPosition({ corner: "bottom-right" }, triggerSize, viewport);
+    expect(pos).toEqual({ left: 1000 - 36 - 16, top: 700 - 36 - 16 });
+  });
+
+  it("resolves top-left to margin from top and left edges", () => {
+    const pos = resolveTriggerPosition({ corner: "top-left" }, triggerSize, viewport);
+    expect(pos).toEqual({ left: 16, top: 16 });
+  });
+
+  it("resolves top-right to margin from top and right edges", () => {
+    const pos = resolveTriggerPosition({ corner: "top-right" }, triggerSize, viewport);
+    expect(pos).toEqual({ left: 1000 - 36 - 16, top: 16 });
+  });
+
+  it("resolves bottom-left to margin from bottom and left edges", () => {
+    const pos = resolveTriggerPosition({ corner: "bottom-left" }, triggerSize, viewport);
+    expect(pos).toEqual({ left: 16, top: 700 - 36 - 16 });
+  });
+
+  it("has equal left/top margin for top-left corner", () => {
+    const pos = resolveTriggerPosition({ corner: "top-left" }, triggerSize, viewport);
+    expect(pos.left).toBe(pos.top);
+  });
+
+  it("keeps the trigger on-screen when the viewport is smaller than the margin and trigger", () => {
+    const tinyViewport = { width: 40, height: 40 };
+    const pos = resolveTriggerPosition({ corner: "bottom-right" }, triggerSize, tinyViewport);
+    expect(pos).toEqual({ left: 4, top: 4 });
+  });
+});
+
+describe("resize anchor regression", () => {
+  it("bottom-right corner tracks the bottom-right edge after viewport shrinks", () => {
+    const placement = { corner: "bottom-right" } as const;
+    const pos1 = resolveTriggerPosition(placement, triggerSize, { width: 800, height: 600 });
+    expect(pos1).toEqual({ left: 800 - 36 - 16, top: 600 - 36 - 16 });
+  });
+
+  it("bottom-right corner tracks the bottom-right edge after viewport grows", () => {
+    const placement = { corner: "bottom-right" } as const;
+    const pos2 = resolveTriggerPosition(placement, triggerSize, { width: 1440, height: 900 });
+    expect(pos2).toEqual({ left: 1440 - 36 - 16, top: 900 - 36 - 16 });
+  });
+
+  it("top-right corner tracks the top-right edge across resize cycles", () => {
+    const placement = { corner: "top-right" } as const;
+    for (const vw of [600, 800, 1000, 1440]) {
+      const pos = resolveTriggerPosition(placement, triggerSize, { width: vw, height: 700 });
+      expect(pos.left).toBe(vw - 36 - 16);
+      expect(pos.top).toBe(16);
+    }
+  });
+
+  it("corner does not change on resize (placement is stable)", () => {
+    // The same corner placement always resolves without changing its corner.
+    const placement = getSnappedTriggerPlacement({ left: 950, top: 650 }, triggerSize, viewport);
+    expect(placement.corner).toBe("bottom-right");
+
+    // After resize, applying resolveTriggerPosition still produces bottom-right geometry.
+    const smallVp = resolveTriggerPosition(placement, triggerSize, { width: 400, height: 300 });
+    expect(smallVp.left).toBe(400 - 36 - 16);
+    expect(smallVp.top).toBe(300 - 36 - 16);
+  });
+});
+
+describe("clampTriggerPosition", () => {
+  it("clamps positions outside the viewport", () => {
+    expect(clampTriggerPosition({ left: -50, top: -20 }, triggerSize, viewport)).toEqual({ left: 0, top: 0 });
+    expect(clampTriggerPosition({ left: 9999, top: 9999 }, triggerSize, viewport)).toEqual({
+      left: viewport.width - triggerSize.width,
+      top: viewport.height - triggerSize.height,
+    });
+  });
+
+  it("preserves positions already within bounds", () => {
+    const pos = { left: 200, top: 300 };
+    expect(clampTriggerPosition(pos, triggerSize, viewport)).toEqual(pos);
+  });
+});

package/src/dev-tool/dev-tool-trigger-position.ts

@@ -0,0 +1,109 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+export type TriggerCorner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+export type TriggerPlacement = {
+  corner: TriggerCorner;
+};
+
+export type TriggerPosition = {
+  left: number;
+  top: number;
+};
+
+export type TriggerSize = {
+  width: number;
+  height: number;
+};
+
+export type TriggerViewport = {
+  width: number;
+  height: number;
+};
+
+export const TRIGGER_EDGE_MARGIN = 16;
+
+function getSnapBounds(
+  triggerSize: TriggerSize,
+  viewport: TriggerViewport,
+) {
+  const maxLeft = Math.max(0, viewport.width - triggerSize.width);
+  const maxTop = Math.max(0, viewport.height - triggerSize.height);
+  const minLeft = Math.min(TRIGGER_EDGE_MARGIN, maxLeft);
+  const minTop = Math.min(TRIGGER_EDGE_MARGIN, maxTop);
+  return {
+    minLeft,
+    maxLeft: Math.max(minLeft, maxLeft - TRIGGER_EDGE_MARGIN),
+    minTop,
+    maxTop: Math.max(minTop, maxTop - TRIGGER_EDGE_MARGIN),
+  };
+}
+
+/**
+ * Clamps a position so the trigger stays fully within the viewport.
+ * Used during drag to prevent the pill from leaving the screen.
+ */
+export function clampTriggerPosition(
+  position: TriggerPosition,
+  triggerSize: TriggerSize,
+  viewport: TriggerViewport,
+): TriggerPosition {
+  const maxLeft = Math.max(0, viewport.width - triggerSize.width);
+  const maxTop = Math.max(0, viewport.height - triggerSize.height);
+  return {
+    left: Math.max(0, Math.min(position.left, maxLeft)),
+    top: Math.max(0, Math.min(position.top, maxTop)),
+  };
+}
+
+/**
+ * Returns the exact pixel position for a corner placement.
+ * The trigger is always `TRIGGER_EDGE_MARGIN` px from both adjacent edges.
+ */
+export function resolveTriggerPosition(
+  placement: TriggerPlacement,
+  triggerSize: TriggerSize,
+  viewport: TriggerViewport,
+): TriggerPosition {
+  const bounds = getSnapBounds(triggerSize, viewport);
+  const position = (() => {
+    switch (placement.corner) {
+      case 'top-left': {
+        return { left: bounds.minLeft, top: bounds.minTop };
+      }
+      case 'top-right': {
+        return { left: bounds.maxLeft, top: bounds.minTop };
+      }
+      case 'bottom-left': {
+        return { left: bounds.minLeft, top: bounds.maxTop };
+      }
+      case 'bottom-right': {
+        return { left: bounds.maxLeft, top: bounds.maxTop };
+      }
+    }
+  })();
+
+  return clampTriggerPosition(position, triggerSize, viewport);
+}
+
+/**
+ * Snaps a free position to the nearest corner by checking which viewport
+ * quadrant the trigger center falls in.
+ */
+export function getSnappedTriggerPlacement(
+  position: TriggerPosition,
+  triggerSize: TriggerSize,
+  viewport: TriggerViewport,
+): TriggerPlacement {
+  const cx = position.left + triggerSize.width / 2;
+  const cy = position.top + triggerSize.height / 2;
+
+  const corner: TriggerCorner =
+    cy < viewport.height / 2
+      ? cx < viewport.width / 2 ? 'top-left' : 'top-right'
+      : cx < viewport.width / 2 ? 'bottom-left' : 'bottom-right';
+
+  return { corner };
+}

package/src/dev-tool/index.ts

@@ -0,0 +1,149 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+
+import type { StackClientApp } from "../lib/hexclave-app";
+import { captureError } from "@hexclave/shared/dist/utils/errors";
+import { runAsynchronously } from "@hexclave/shared/dist/utils/promises";
+import { isLocalhost } from "@hexclave/shared/dist/utils/urls";
+import type { createDevTool as CreateDevToolFn } from "./dev-tool-core";
+
+// Hexclave rebrand: UI-only local pref — straight rename (one-time reset is harmless)
+const OVERRIDE_KEY = '__hexclave-dev-tool-override';
+
+function hasAppendChild(value: unknown): value is { appendChild(node: Node): void } {
+  return typeof value === 'object' && value !== null && typeof Reflect.get(value, 'appendChild') === 'function';
+}
+
+function canMountIntoDom(): boolean {
+  if (typeof window === 'undefined' || typeof document === 'undefined') {
+    return false;
+  }
+  if (typeof document.createElement !== 'function') {
+    return false;
+  }
+  return hasAppendChild(Reflect.get(document, 'body'));
+}
+
+function getOverride(): boolean | null {
+  try {
+    const val = localStorage.getItem(OVERRIDE_KEY);
+    if (val === 'true') return true;
+    if (val === 'false') return false;
+  } catch {}
+  return null;
+}
+
+function shouldShow(): boolean {
+  const override = getOverride();
+  if (override !== null) return override;
+  if (!canMountIntoDom()) return false;
+  return isLocalhost(window.location.href);
+}
+
+let activeCleanup: (() => void) | null = null;
+let activeApp: StackClientApp<true> | null = null;
+let mountGeneration = 0;
+
+let createDevToolPromise: Promise<typeof CreateDevToolFn> | null = null;
+function loadCreateDevTool(): Promise<typeof CreateDevToolFn> {
+  if (!createDevToolPromise) {
+    createDevToolPromise = import("./dev-tool-core").then(m => m.createDevTool).catch((err) => {
+      createDevToolPromise = null;
+      throw err;
+    });
+  }
+  return createDevToolPromise;
+}
+
+function tryMount() {
+  if (activeCleanup) {
+    activeCleanup();
+    activeCleanup = null;
+  }
+
+  if (!shouldShow() || !activeApp || !canMountIntoDom()) return;
+
+  const generation = ++mountGeneration;
+  const app = activeApp;
+
+  runAsynchronously(async () => {
+    const createDevTool = await loadCreateDevTool();
+    if (generation !== mountGeneration) return;
+    if (!shouldShow() || activeApp !== app || !canMountIntoDom()) return;
+    activeCleanup = createDevTool(app);
+  }, {
+    noErrorLogging: true,
+    onError: (error) => {
+      captureError("dev-tool-mount", error);
+    },
+  });
+}
+
+/**
+ * Mounts the Hexclave dev tool on the page.
+ *
+ * - Only renders on localhost (or when overridden via console)
+ * - Lazily loads the dev tool UI via dynamic import
+ * - Returns a cleanup function to unmount
+ *
+ * Console commands (also work in production):
+ *   HexclaveDevTool.enable()  — force-show the dev tool
+ *   HexclaveDevTool.disable() — force-hide the dev tool
+ *   HexclaveDevTool.reset()   — revert to default (localhost-only)
+ */
+export function mountDevTool(app: StackClientApp<true>): () => void {
+  activeApp = app;
+  tryMount();
+
+  // Capture the cleanup created by THIS specific mount call so that React
+  // StrictMode's double-invoke doesn't let the first effect's cleanup tear
+  // down the second mount (which would cause the tool to disappear silently).
+  const myCleanup = activeCleanup;
+
+  return () => {
+    activeApp = null;
+    if (activeCleanup === myCleanup && myCleanup != null) {
+      activeCleanup = null;
+      myCleanup();
+    }
+  };
+}
+
+// Expose console commands: HexclaveDevTool.enable() / .disable() / .reset()
+if (typeof window !== 'undefined') {
+  // Hexclave rebrand: expose under both the legacy and new global names.
+  (window as any).HexclaveDevTool = (window as any).HexclaveDevTool = {
+    enable() {
+      try {
+        localStorage.setItem(OVERRIDE_KEY, 'true');
+      } catch {}
+      tryMount();
+      console.log('[Stack DevTool] Enabled. Refresh if the panel does not appear.');
+    },
+    disable() {
+      try {
+        localStorage.setItem(OVERRIDE_KEY, 'false');
+      } catch {}
+      if (activeCleanup) {
+        activeCleanup();
+        activeCleanup = null;
+      }
+      console.log('[Stack DevTool] Disabled.');
+    },
+    reset() {
+      try {
+        localStorage.removeItem(OVERRIDE_KEY);
+      } catch {}
+      if (shouldShow()) {
+        tryMount();
+      } else if (activeCleanup) {
+        activeCleanup();
+        activeCleanup = null;
+      }
+      console.log('[Stack DevTool] Reset to default (visible on localhost only).');
+    },
+  };
+}
+

package/src/index.ts

@@ -0,0 +1,12 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+export * from './lib/hexclave-app';
+export { getConvexProvidersConfig } from "./integrations/convex";
+// Hexclave aliases and legacy Stack* names — @deprecated JSDoc lives on the original
+// declarations in @hexclave/shared/config so it survives dts bundling
+// (per-specifier JSDoc on re-exports does not).
+export type { HexclaveConfig, StackConfig } from "@hexclave/shared/config";
+export { defineHexclaveConfig, defineStackConfig } from "@hexclave/shared/config";
+

package/src/integrations/convex/component/README.md

@@ -0,0 +1,74 @@
+# Hexclave Convex Component
+
+This component is the official way to integrate Hexclave with your Convex project.
+
+## Installation
+
+To get started, first install Hexclave using the setup wizard:
+
+```bash
+npx @hexclave/cli@latest init
+```
+
+## Get Started
+
+[Create a new Hexclave project](https://app.hexclave.com) and set the environment variables in Convex to the project ID & API key environment variables from the Hexclave dashboard. Also, add the same values to the `.env.local` file.
+
+Next, update or create a file in `convex/auth.config.ts`:
+
+```ts
+import { getConvexProvidersConfig } from "@hexclave/js/convex-auth.config";  // Vanilla JS
+// or: import { getConvexProvidersConfig } from "@hexclave/react/convex-auth.config";  // React
+// or: import { getConvexProvidersConfig } from "@hexclave/next/convex-auth.config";  // Next.js
+
+export default {
+  providers: getConvexProvidersConfig({
+    projectId: process.env.STACK_PROJECT_ID,  // or: process.env.NEXT_PUBLIC_STACK_PROJECT_ID
+  }),
+}
+```
+
+Next, update or create a file in `convex/convex.config.ts`:
+
+```ts
+import { defineApp } from "convex/server";
+import stackAuthComponent from "@hexclave/js/convex.config";  // Vanilla JS
+// or: import stackAuthComponent from "@hexclave/react/convex.config";  // React
+// or: import stackAuthComponent from "@hexclave/next/convex.config";  // Next.js
+
+
+const app = defineApp();
+app.use(stackAuthComponent);
+
+export default app;
+```
+
+Then, update your Convex client to use Hexclave:
+
+```ts
+convexClient.setAuth(hexclaveClientApp.getConvexClientAuth({}));  // browser JS
+convexReactClient.setAuth(hexclaveClientApp.getConvexClientAuth({}));  // React
+convexHttpClient.setAuth(hexclaveClientApp.getConvexHttpClientAuth({ tokenStore: requestObject }));  // HTTP, see Hexclave docs for more information on tokenStore
+```
+
+Now, you'll be able to access Hexclave's functionality from your frontend & backend:
+
+```ts
+// MyPage.tsx
+export function MyPage() {
+  // see https://docs.hexclave.com for more information on how to use Hexclave
+  const user = useUser();
+  return <div>Your email is {user.email}</div>;
+}
+
+// myFunctions.ts
+export const myQuery = query({
+  handler: async (ctx, args) => {
+    // In queries & mutations, use the special `getPartialUser` function to get user info
+    const obj = await hexclaveServerApp.getPartialUser({ from: "convex", ctx });
+    return JSON.stringify(obj);
+  },
+});
+```
+
+For more information on how to use Hexclave, see the [Hexclave docs](https://docs.hexclave.com).

package/src/integrations/convex/component/convex.config.ts

@@ -0,0 +1,9 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { defineComponent } from "convex/server";
+
+const component = defineComponent("stack_auth");
+
+export default component;

package/src/integrations/convex.ts

@@ -0,0 +1,28 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { urlString } from "@hexclave/shared/dist/utils/urls";
+import { defaultBaseUrl } from "../lib/hexclave-app/apps/implementations/common";
+
+export function getConvexProvidersConfig(options: {
+  baseUrl?: string,
+  projectId: string,
+}) {
+  const baseUrl = options.baseUrl || defaultBaseUrl;
+  const projectId = options.projectId;
+  return [
+    {
+      type: "customJwt",
+      issuer: new URL(urlString`/api/v1/projects/${projectId}`, baseUrl),
+      jwks: new URL(urlString`/api/v1/projects/${projectId}/.well-known/jwks.json`, baseUrl),
+      algorithm: "ES256",
+    },
+    {
+      type: "customJwt",
+      issuer: new URL(urlString`/api/v1/projects-anonymous-users/${projectId}`, baseUrl),
+      jwks: new URL(urlString`/api/v1/projects/${projectId}/.well-known/jwks.json?include_anonymous=true`, baseUrl),
+      algorithm: "ES256",
+    },
+  ];
+}

package/src/lib/auth.test.ts

@@ -0,0 +1,67 @@
+
+//===========================================
+// 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 { HexclaveClientInterface } from "@hexclave/shared";
+import { describe, expect, it, vi } from "vitest";
+import { getNewOAuthProviderOrScopeUrl } from "./auth";
+
+vi.mock("./cookie", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./cookie")>();
+  return {
+    ...actual,
+    saveVerifierAndState: async () => ({
+      codeChallenge: "<stripped code challenge>",
+      state: "<stripped state>",
+    }),
+  };
+});
+
+describe("getNewOAuthProviderOrScopeUrl", () => {
+  it("returns the OAuth URL without performing navigation", async () => {
+    window.history.replaceState({}, "", "/account?after_auth_return_to=%2Fsettings");
+
+    const iface = new HexclaveClientInterface({
+      clientVersion: "test",
+      getBaseUrl: () => "https://api.example.com",
+      getApiUrls: () => ["https://api.example.com"],
+      extraRequestHeaders: {},
+      projectId: "00000000-0000-4000-8000-000000000000",
+      publishableClientKey: "pck_test",
+    });
+    const session = iface.createSession({ refreshToken: null, accessToken: null });
+
+    const location = await getNewOAuthProviderOrScopeUrl(
+      iface,
+      {
+        provider: "github",
+        redirectUrl: "/handler/oauth-callback",
+        errorRedirectUrl: "/handler/error",
+        providerScope: "repo user",
+      },
+      session,
+    );
+
+    const url = new URL(location);
+    expect(`${url.origin}${url.pathname}`).toBe("https://api.example.com/api/v1/auth/oauth/authorize/github");
+    expect(Object.fromEntries(url.searchParams.entries())).toMatchInlineSnapshot(`
+      {
+        "after_callback_redirect_url": "http://localhost:3000/account?after_auth_return_to=%2Fsettings",
+        "client_id": "00000000-0000-4000-8000-000000000000",
+        "client_secret": "pck_test",
+        "code_challenge": "<stripped code challenge>",
+        "code_challenge_method": "S256",
+        "error_redirect_url": "http://localhost:3000/handler/error?after_auth_return_to=%2Fsettings",
+        "grant_type": "authorization_code",
+        "provider_scope": "repo user",
+        "redirect_uri": "http://localhost:3000/handler/oauth-callback?after_auth_return_to=%2Fsettings",
+        "response_type": "code",
+        "scope": "legacy",
+        "state": "<stripped state>",
+        "type": "link",
+      }
+    `);
+  });
+});