@hexclave/shared 1.0.3 → 1.0.5

package/src/utils/esbuild.tsx

@@ -0,0 +1,235 @@
+import * as esbuild from 'esbuild-wasm/lib/browser.js';
+import { join } from 'path';
+import { getProcessEnv, isBrowserLike } from './env';
+import { captureError, HexclaveAssertionError, throwErr } from "./errors";
+import { createGlobalAsync } from './globals';
+import { ignoreUnhandledRejection, runAsynchronously } from './promises';
+import { Result } from "./results";
+import { traceSpan, withTraceSpan } from './telemetry';
+
+
+// esbuild requires self property to be set, and it is not set by default in nodejs
+(globalThis.self as any) ??= globalThis as any;
+
+let esbuildInitializePromise: Promise<void> | null = null;
+
+if (typeof process !== "undefined" && typeof process.exit === "function" && getProcessEnv("NODE_ENV") === 'development') {
+  // On development Node.js servers, initialize ESBuild as soon as the module is imported so we have to wait less on the first request
+  runAsynchronously(async () => {
+    try {
+      await initializeEsbuild();
+    } catch (e) {
+      captureError("initialize-esbuild-in-dev", e);
+    }
+  });
+}
+
+export function initializeEsbuild(): Promise<void> {
+  const esbuildWasmUrl = `https://unpkg.com/esbuild-wasm@${esbuild.version}/esbuild.wasm`;
+  if (esbuildInitializePromise == null) {
+    esbuildInitializePromise = withTraceSpan('initializeEsbuild', async () => {
+      try {
+        let initOptions;
+        if (isBrowserLike()) {
+          initOptions = {
+            wasmURL: esbuildWasmUrl,
+          };
+        } else {
+          const esbuildWasmModule = await createGlobalAsync('esbuildWasmModule', async () => {
+            const esbuildWasmResponse = await fetch(esbuildWasmUrl);
+            if (!esbuildWasmResponse.ok) {
+              throw new HexclaveAssertionError(`Failed to fetch esbuild.wasm: ${esbuildWasmResponse.status} ${esbuildWasmResponse.statusText}: ${await esbuildWasmResponse.text()}`);
+            }
+            const esbuildWasm = await esbuildWasmResponse.arrayBuffer();
+            const esbuildWasmArray = new Uint8Array(esbuildWasm);
+            if (esbuildWasmArray[0] !== 0x00 || esbuildWasmArray[1] !== 0x61 || esbuildWasmArray[2] !== 0x73 || esbuildWasmArray[3] !== 0x6d) {
+              throw new HexclaveAssertionError(`Invalid esbuild.wasm file: ${new TextDecoder().decode(esbuildWasmArray)}`);
+            }
+            return new WebAssembly.Module(esbuildWasm);
+          });
+          initOptions = {
+            wasmModule: esbuildWasmModule,
+            worker: false,
+          };
+        }
+        try {
+          await esbuild.initialize(initOptions);
+        } catch (e) {
+          if (e instanceof Error && e.message === 'Cannot call "initialize" more than once') {
+            // this happens especially in local development, just ignore
+          } else {
+            throw e;
+          }
+        }
+      } catch (e) {
+        esbuildInitializePromise = null;
+        throw new HexclaveAssertionError("Failed to initialize ESBuild", { cause: e });
+      }
+    })();
+    ignoreUnhandledRejection(esbuildInitializePromise);
+  }
+
+  return esbuildInitializePromise;
+}
+
+export async function bundleJavaScript(sourceFiles: Record<string, string> & { '/entry.js': string }, options: {
+  format?: 'iife' | 'esm' | 'cjs',
+  externalPackages?: Record<string, string>,
+  keepAsImports?: string[],
+  sourcemap?: false | 'inline',
+  allowHttpImports?: boolean,
+} = {}): Promise<Result<string, string>> {
+  await initializeEsbuild();
+
+  const sourceFilesMap = new Map(Object.entries(sourceFiles));
+  const externalPackagesMap = new Map(Object.entries(options.externalPackages ?? {}));
+  const keepAsImports = options.keepAsImports ?? [];
+
+  const httpImportCache = new Map<string, { contents: string, loader: esbuild.Loader, resolveDir: string }>();
+
+  const extToLoader: Map<string, esbuild.Loader> = new Map([
+    ['tsx', 'tsx'],
+    ['ts', 'ts'],
+    ['js', 'js'],
+    ['jsx', 'jsx'],
+    ['json', 'json'],
+    ['css', 'css'],
+  ]);
+  let result;
+  try {
+    result = await traceSpan('bundleJavaScript', async () => await esbuild.build({
+      entryPoints: ['/entry.js'],
+      bundle: true,
+      write: false,
+      format: options.format ?? 'iife',
+      platform: 'browser',
+      target: 'es2015',
+      jsx: 'automatic',
+      sourcemap: options.sourcemap ?? 'inline',
+      external: keepAsImports,
+      plugins: [
+        ...options.allowHttpImports ? [{
+          name: "esm-sh-only",
+          setup(build: esbuild.PluginBuild) {
+            // Handle absolute URLs and relative imports from esm.sh modules.
+            build.onResolve({ filter: /.*/ }, (args) => {
+              // Only touch absolute http(s) specifiers or children of our own namespace
+              const isHttp = args.path.startsWith("http://") || args.path.startsWith("https://");
+              const fromEsmNs = args.namespace === "esm-sh";
+
+              if (!isHttp && !fromEsmNs) return null; // Let other plugins handle bare/relative/local
+
+              // Resolve relative URLs inside esm.sh-fetched modules
+              const url = new URL(args.path, fromEsmNs ? args.importer : undefined);
+
+              if (url.protocol !== "https:" || url.host !== "esm.sh") {
+                throw new Error(`Blocked non-esm.sh URL import: ${url.href}`);
+              }
+
+              return { path: url.href, namespace: "esm-sh" };
+            });
+
+            build.onLoad({ filter: /.*/, namespace: "esm-sh" }, async (args) => {
+              if (httpImportCache.has(args.path)) return httpImportCache.get(args.path)!;
+
+              const res = await fetch(args.path, { redirect: "follow" });
+              if (!res.ok) throw new Error(`Fetch ${res.status} ${res.statusText} for ${args.path}`);
+              const finalUrl = new URL(res.url);
+              // Defensive: follow shouldn’t leave esm.sh, but re-check.
+              if (finalUrl.host !== "esm.sh") {
+                throw new Error(`Redirect escaped esm.sh: ${finalUrl.href}`);
+              }
+
+              const ct = (res.headers.get("content-type") || "").toLowerCase();
+              let loader: esbuild.Loader =
+                ct.includes("css") ? "css" :
+                ct.includes("json") ? "json" :
+                ct.includes("typescript") ? "ts" :
+                ct.includes("jsx") ? "jsx" :
+                ct.includes("tsx") ? "tsx" :
+                  "js";
+
+              // Fallback by extension (esm.sh sometimes omits CT)
+              const p = finalUrl.pathname;
+              if (p.endsWith(".css")) loader = "css";
+              else if (p.endsWith(".json")) loader = "json";
+              else if (p.endsWith(".ts")) loader = "ts";
+              else if (p.endsWith(".tsx")) loader = "tsx";
+              else if (p.endsWith(".jsx")) loader = "jsx";
+
+              const contents = await res.text();
+              const result = {
+                contents,
+                loader,
+                // Ensures relative imports inside that module resolve against the file’s URL
+                resolveDir: new URL(".", finalUrl.href).toString(),
+                watchFiles: [finalUrl.href],
+              };
+              httpImportCache.set(args.path, result);
+              return result;
+            });
+          },
+        } as esbuild.Plugin] : [],
+        {
+          name: 'replace-packages-with-globals',
+          setup(build) {
+            build.onResolve({ filter: /.*/ }, args => {
+              // Skip packages that should remain external (not be shimmed)
+              if (keepAsImports.includes(args.path)) {
+                return undefined;
+              }
+              if (externalPackagesMap.has(args.path)) {
+                return { path: args.path, namespace: 'package-shim' };
+              }
+              return undefined;
+            });
+
+            build.onLoad({ filter: /.*/, namespace: 'package-shim' }, (args) => {
+              const contents = externalPackagesMap.get(args.path);
+              if (contents == null) throw new HexclaveAssertionError(`esbuild requested file ${args.path} that is not in the virtual file system`);
+
+              return { contents, loader: 'ts' };
+            });
+          },
+        },
+        {
+          name: 'virtual-fs',
+          setup(build) {
+            build.onResolve({ filter: /.*/ }, args => {
+              const absolutePath = join("/", args.path);
+              if (sourceFilesMap.has(absolutePath)) {
+                return { path: absolutePath, namespace: 'virtual' };
+              }
+              return undefined;
+            });
+
+            /* 2️⃣  Load the module from the map */
+            build.onLoad({ filter: /.*/, namespace: 'virtual' }, args => {
+              const contents = sourceFilesMap.get(args.path);
+              if (contents == null) throw new HexclaveAssertionError(`esbuild requested file ${args.path} that is not in the virtual file system`);
+
+              const ext = args.path.split('.').pop() ?? '';
+              const loader = extToLoader.get(ext) ?? throwErr(`esbuild requested file ${args.path} with unknown extension ${ext}`);
+
+              return { contents, loader };
+            });
+          },
+        },
+      ],
+    }));
+  } catch (e) {
+    if (e instanceof Error && e.message.startsWith("Build failed with ")) {
+      return Result.error(e.message);
+    }
+    throw e;
+  }
+
+  if (result.errors.length > 0) {
+    return Result.error(result.errors.map(e => e.text).join('\n'));
+  }
+
+  if (result.outputFiles.length > 0) {
+    return Result.ok(result.outputFiles[0].text);
+  }
+  return throwErr("No output generated??");
+}

package/src/utils/featurebase.tsx

@@ -0,0 +1,247 @@
+import { getEnvVariable } from "./env";
+import { HexclaveAssertionError } from "./errors";
+
+export type FeaturebaseUser = {
+  userId: string,
+  email: string,
+  name?: string,
+  profilePicture?: string,
+};
+
+export type HexclaveAuthUser = {
+  id: string,
+  primaryEmail: string | null,
+  displayName?: string | null,
+  profileImageUrl?: string | null,
+};
+
+/**
+ * Find a Featurebase user by their Hexclave user ID
+ */
+async function findFeaturebaseUserById(hexclaveAuthUserId: string, apiKey: string): Promise<FeaturebaseUser | null> {
+  try {
+    const response = await fetch(`https://do.featurebase.app/v2/organization/identifyUser?id=${hexclaveAuthUserId}`, {
+      method: 'GET',
+      headers: {
+        'X-API-Key': apiKey,
+      },
+    });
+
+    if (response.status === 404) {
+      return null;
+    }
+
+    if (!response.ok) {
+      throw new HexclaveAssertionError(`Failed to find Featurebase user by ID: ${response.statusText}`);
+    }
+
+    const data = await response.json();
+    const user = data.user;
+
+    if (!user) {
+      throw new HexclaveAssertionError(`Featurebase API returned success but no user data for ID: ${hexclaveAuthUserId}`, { data });
+    }
+
+    return {
+      userId: user.externalUserId || user.userId || hexclaveAuthUserId,
+      email: user.email,
+      name: user.name,
+      profilePicture: user.profilePicture,
+    };
+  } catch (error) {
+    if (error instanceof HexclaveAssertionError) {
+      throw error;
+    }
+    throw new HexclaveAssertionError("Failed to find Featurebase user by ID", { cause: error });
+  }
+}
+
+/**
+ * Find a Featurebase user by their email address
+ */
+async function findFeaturebaseUserByEmail(email: string, apiKey: string): Promise<FeaturebaseUser | null> {
+  try {
+    const response = await fetch(`https://do.featurebase.app/v2/organization/identifyUser?email=${encodeURIComponent(email)}`, {
+      method: 'GET',
+      headers: {
+        'X-API-Key': apiKey,
+      },
+    });
+
+    if (response.status === 404) {
+      return null;
+    }
+
+    if (!response.ok) {
+      throw new HexclaveAssertionError(`Failed to find Featurebase user by email: ${response.statusText}`);
+    }
+
+    const data = await response.json();
+    const user = data.user;
+
+    if (!user) {
+      throw new HexclaveAssertionError(`Featurebase API returned success but no user data for email: ${email}`, { data });
+    }
+
+    return {
+      userId: user.externalUserId || user.userId,
+      email: user.email,
+      name: user.name,
+      profilePicture: user.profilePicture,
+    };
+  } catch (error) {
+    console.error('Error finding Featurebase user by email:', error);
+    return null;
+  }
+}
+
+/**
+ * Create a new Featurebase user using the identifyUser endpoint
+ */
+async function createFeaturebaseUser(user: FeaturebaseUser, apiKey: string): Promise<FeaturebaseUser> {
+  try {
+    const response = await fetch('https://do.featurebase.app/v2/organization/identifyUser', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-API-Key': apiKey,
+      },
+      body: JSON.stringify({
+        userId: user.userId,
+        email: user.email,
+        name: user.name,
+        profilePicture: user.profilePicture,
+      }),
+    });
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({}));
+      throw new HexclaveAssertionError(`Failed to create Featurebase user: ${errorData.error || response.statusText}`, { errorData });
+    }
+
+    // The identifyUser endpoint just returns { "success": true }, so we return the input data
+    return user;
+  } catch (error) {
+    if (error instanceof HexclaveAssertionError) {
+      throw error;
+    }
+    throw new HexclaveAssertionError("Failed to create Featurebase user", { cause: error });
+
+  }
+}
+
+/**
+ * Update an existing Featurebase user (excluding email)
+ */
+async function updateFeaturebaseUser(userId: string, updates: Partial<Omit<FeaturebaseUser, 'userId' | 'email'>>, apiKey: string): Promise<FeaturebaseUser> {
+  try {
+    const response = await fetch(`https://do.featurebase.app/v2/users/${userId}`, {
+      method: 'PATCH',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-API-Key': apiKey,
+      },
+      body: JSON.stringify(updates),
+    });
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({}));
+      throw new HexclaveAssertionError(`Failed to update Featurebase user: ${errorData.error || response.statusText}`, { errorData });
+    }
+
+    const data = await response.json();
+    return {
+      userId: data.userId || userId,
+      email: data.email,
+      name: data.name,
+      profilePicture: data.profilePicture,
+    };
+  } catch (error) {
+    if (error instanceof HexclaveAssertionError) {
+      throw error;
+    }
+    throw new HexclaveAssertionError("Failed to update Featurebase user", { cause: error });
+  }
+}
+
+/**
+ * Get or create a Featurebase user based on Hexclave user data.
+ * This function ensures that:
+ * 1. We never change a user's email address on Featurebase
+ * 2. We use Hexclave user ID as the primary identifier
+ * 3. We handle email conflicts by using fallback emails
+ * 4. We update profile information when needed
+ */
+export async function getOrCreateFeaturebaseUser(
+  hexclaveAuthUser: HexclaveAuthUser,
+  options?: { apiKey?: string }
+): Promise<{ userId: string, email: string }> {
+  const apiKey = options?.apiKey || getEnvVariable("STACK_FEATUREBASE_API_KEY");
+  const fallbackEmail = `${hexclaveAuthUser.id}@featurebase-user.stack-auth-app.com`;
+
+  // First, try to find existing user by Hexclave user ID
+  const existingById = await findFeaturebaseUserById(hexclaveAuthUser.id, apiKey);
+  if (existingById) {
+    // Ensure the user has an email on Featurebase.
+    let ensuredEmail = existingById.email;
+    if (!ensuredEmail) {
+      try {
+        await createFeaturebaseUser({
+          userId: existingById.userId,
+          email: fallbackEmail,
+          name: hexclaveAuthUser.displayName || undefined,
+          profilePicture: hexclaveAuthUser.profileImageUrl || undefined,
+        }, apiKey);
+        ensuredEmail = fallbackEmail;
+      } catch (e) {
+        // If setting fallback email failed, keep ensuredEmail as-is (undefined) and let callers handle
+        throw new HexclaveAssertionError(`Failed to set fallback email for existing Featurebase user ${existingById.userId}`, { cause: e });
+      }
+    }
+
+    // Update profile information if needed (but not email)
+    try {
+      const updates: Partial<Omit<FeaturebaseUser, 'userId' | 'email'>> = {};
+
+      if (hexclaveAuthUser.displayName && hexclaveAuthUser.displayName !== existingById.name) {
+        updates.name = hexclaveAuthUser.displayName;
+      }
+
+      if (hexclaveAuthUser.profileImageUrl && hexclaveAuthUser.profileImageUrl !== existingById.profilePicture) {
+        updates.profilePicture = hexclaveAuthUser.profileImageUrl;
+      }
+
+      if (Object.keys(updates).length > 0) {
+        await updateFeaturebaseUser(existingById.userId, updates, apiKey);
+      }
+    } catch (error) {
+      console.error('Failed to update existing Featurebase user profile:', error);
+      // Continue with existing user data even if update fails
+    }
+
+    return {
+      userId: existingById.userId,
+      email: ensuredEmail,
+    };
+  }
+
+  // No existing user found by ID, need to create one
+  const candidateEmail = hexclaveAuthUser.primaryEmail ?? fallbackEmail;
+
+  // Check if someone already has this email on Featurebase
+  const existingByEmail = await findFeaturebaseUserByEmail(candidateEmail, apiKey);
+  const safeEmail = existingByEmail ? fallbackEmail : candidateEmail;
+
+  // Create new user
+  const created = await createFeaturebaseUser({
+    userId: hexclaveAuthUser.id,
+    email: safeEmail,
+    name: hexclaveAuthUser.displayName || hexclaveAuthUser.primaryEmail?.split('@')[0] || 'User',
+    profilePicture: hexclaveAuthUser.profileImageUrl || undefined,
+  }, apiKey);
+
+  return {
+    userId: created.userId,
+    email: created.email,
+  };
+}

package/src/utils/fs.tsx

@@ -0,0 +1,33 @@
+import * as hexclaveFs from "fs";
+import * as path from "path";
+
+export async function list(path: string) {
+  return await hexclaveFs.promises.readdir(path);
+}
+
+export async function listRecursively(p: string, options: { excludeDirectories?: boolean } = {}): Promise<string[]> {
+  const files = await list(p);
+  return [
+    ...(await Promise.all(files.map(async (fileName) => {
+      const filePath = path.join(p, fileName);
+      if ((await hexclaveFs.promises.stat(filePath)).isDirectory()) {
+        return [
+          ...(await listRecursively(filePath, options)),
+          ...(options.excludeDirectories ? [] : [filePath]),
+        ];
+      } else {
+        return [filePath];
+      }
+    }))).flat(),
+  ];
+}
+
+export function writeFileSyncIfChanged(path: string, content: string): void {
+  if (hexclaveFs.existsSync(path)) {
+    const existingContent = hexclaveFs.readFileSync(path, "utf-8");
+    if (existingContent === content) {
+      return;
+    }
+  }
+  hexclaveFs.writeFileSync(path, content);
+}

package/src/utils/functions.tsx

@@ -0,0 +1,22 @@
+export function identity<T>(t: T): T {
+  return t;
+}
+import.meta.vitest?.test("identity", ({ expect }) => {
+  expect(identity(1)).toBe(1);
+  expect(identity("test")).toBe("test");
+  expect(identity(null)).toBe(null);
+  expect(identity(undefined)).toBe(undefined);
+  const obj = { a: 1 };
+  expect(identity(obj)).toBe(obj);
+});
+
+export function identityArgs<T extends any[]>(...args: T): T {
+  return args;
+}
+import.meta.vitest?.test("identityArgs", ({ expect }) => {
+  expect(identityArgs()).toEqual([]);
+  expect(identityArgs(1)).toEqual([1]);
+  expect(identityArgs(1, 2, 3)).toEqual([1, 2, 3]);
+  expect(identityArgs("a", "b", "c")).toEqual(["a", "b", "c"]);
+  expect(identityArgs(null, undefined)).toEqual([null, undefined]);
+});

package/src/utils/geo.tsx

@@ -0,0 +1,16 @@
+
+import * as yup from "yup";
+import { yupNumber, yupObject, yupString } from "../schema-fields";
+
+export const geoInfoSchema = yupObject({
+  ip: yupString().defined(),
+  countryCode: yupString().nullable(),
+  regionCode: yupString().nullable(),
+  cityName: yupString().nullable(),
+  latitude: yupNumber().nullable(),
+  longitude: yupNumber().nullable(),
+  tzIdentifier: yupString().nullable(),
+});
+
+export type GeoInfo = yup.InferType<typeof geoInfoSchema>;
+

package/src/utils/globals.tsx

@@ -0,0 +1,48 @@
+const globalVar: any =
+  typeof globalThis !== 'undefined' ? globalThis :
+    typeof global !== 'undefined' ? global :
+      typeof window !== 'undefined' ? window :
+        typeof self !== 'undefined' ? self :
+          {};
+export {
+  globalVar
+};
+
+if (typeof globalThis === 'undefined') {
+  (globalVar as any).globalThis = globalVar;
+}
+
+// Hexclave rebrand: file-private symbol key, renamed outright (no cross-version compat needed).
+const hexclaveGlobalsSymbol = Symbol.for('__hexclave-globals');
+globalVar[hexclaveGlobalsSymbol] ??= {};
+
+export function createGlobal<T>(key: string, init: () => T) {
+  if (!globalVar[hexclaveGlobalsSymbol][key]) {
+    globalVar[hexclaveGlobalsSymbol][key] = init();
+  }
+  return globalVar[hexclaveGlobalsSymbol][key] as T;
+}
+
+/**
+ * Like createGlobal, but if the asynchronous initialization fails, the global will be reset and recomputed on the next
+ * invocation.
+ */
+export function createGlobalAsync<T>(key: string, init: () => Promise<T>): Promise<T> {
+  let promise: Promise<T> | null = null;
+  if (!globalVar[hexclaveGlobalsSymbol][key]) {
+    promise = init().catch((e) => {
+      delete globalVar[hexclaveGlobalsSymbol][key];
+      throw e;
+    });
+    globalVar[hexclaveGlobalsSymbol][key] = promise;
+  }
+  return promise ?? globalVar[hexclaveGlobalsSymbol][key] as Promise<T>;
+}
+
+export function getGlobal(key: string): any {
+  return globalVar[hexclaveGlobalsSymbol][key];
+}
+
+export function setGlobal(key: string, value: any) {
+  globalVar[hexclaveGlobalsSymbol][key] = value;
+}

package/src/utils/hashes.tsx

@@ -0,0 +1,52 @@
+import bcrypt from 'bcryptjs';
+import { HexclaveAssertionError } from './errors';
+import { toArrayBufferBacked } from './typed-arrays';
+
+export async function sha512(input: Uint8Array | string): Promise<Uint8Array> {
+  const bytes = typeof input === "string" ? new TextEncoder().encode(input) : toArrayBufferBacked(input);
+  return new Uint8Array(await crypto.subtle.digest("SHA-512", bytes));
+}
+
+export async function hashPassword(password: string) {
+  const passwordBytes = new TextEncoder().encode(password);
+  if (passwordBytes.length >= 72) {
+    throw new HexclaveAssertionError(`Password is too long for bcrypt`, { len: passwordBytes.length });
+  }
+  const salt = await bcrypt.genSalt(10);
+  return await bcrypt.hash(password, salt);
+}
+
+export async function comparePassword(password: string, hash: string): Promise<boolean> {
+  switch (await getPasswordHashAlgorithm(hash)) {
+    case "bcrypt": {
+      return await bcrypt.compare(password, hash);
+    }
+    default: {
+      return false;
+    }
+  }
+}
+
+export async function isPasswordHashValid(hash: string) {
+  return !!(await getPasswordHashAlgorithm(hash));
+}
+
+export async function getPasswordHashAlgorithm(hash: string): Promise<"bcrypt" | undefined> {
+  if (typeof hash !== "string") {
+    throw new HexclaveAssertionError(`Passed non-string value to getPasswordHashAlgorithm`, { hash });
+  }
+  if (hash.match(/^\$2[ayb]\$.{56}$/)) {
+    try {
+      if (bcrypt.getRounds(hash) > 16) {
+        return undefined;
+      }
+      await bcrypt.compare("any string", hash);
+      return "bcrypt";
+    } catch (e) {
+      console.warn(`Error while checking bcrypt password hash. Assuming the hash is invalid`, e);
+      return undefined;
+    }
+  } else {
+    return undefined;
+  }
+}