@factoredui/core 0.3.0 → 0.4.0

package/dist/cli/{init.cjs → factoredui.cjs}

@@ -32,9 +32,10 @@ var DEFAULT_CONFIG = {
   supabaseAnonKey: "<your-anon-key>",
   schema: "factoredui"
 };
-function main() {
+function runInit() {
   const targetDir = process.cwd();
   copyMigrations(targetDir);
+  copyEdgeFunction(targetDir);
   writeConfig(targetDir);
   printSetupInstructions();
 }
@@ -54,7 +55,7 @@ function copyMigrations(targetDir) {
   const timestamp = generateTimestamp();
   for (const file of migrationFiles) {
     const sourcePath = path.join(migrationsSource, file);
-    const targetFilename = `${timestamp}_auxi_${file}`;
+    const targetFilename = `${timestamp}_factoredui_${file}`;
     const targetPath = path.join(migrationsTarget, targetFilename);
     if (fs.existsSync(targetPath)) {
       console.log(`  skip: ${targetFilename} (already exists)`);
@@ -75,6 +76,36 @@ function findMigrationsDir() {
     "Could not find factoredui migrations directory. Ensure @factoredui/core is installed correctly."
   );
 }
+function copyEdgeFunction(targetDir) {
+  const functionSource = findEdgeFunctionDir();
+  const functionTarget = path.join(targetDir, "supabase", "functions", "factoredui-cluster");
+  if (fs.existsSync(path.join(functionTarget, "index.ts"))) {
+    console.log("\nEdge function already exists \u2014 skipping.");
+    return;
+  }
+  fs.mkdirSync(functionTarget, { recursive: true });
+  const EDGE_FN_ALLOWED_FILES = /* @__PURE__ */ new Set([".ts", ".json"]);
+  const files = fs.readdirSync(functionSource).filter(
+    (file) => EDGE_FN_ALLOWED_FILES.has(path.extname(file))
+  );
+  for (const file of files) {
+    fs.copyFileSync(
+      path.join(functionSource, file),
+      path.join(functionTarget, file)
+    );
+  }
+  console.log(`
+Copied edge function to supabase/functions/factoredui-cluster/`);
+}
+function findEdgeFunctionDir() {
+  const packageDir = path.resolve(__dirname, "..", "..", "supabase", "functions", "factoredui-cluster");
+  if (fs.existsSync(packageDir)) return packageDir;
+  const devDir = path.resolve(__dirname, "..", "supabase", "functions", "factoredui-cluster");
+  if (fs.existsSync(devDir)) return devDir;
+  throw new Error(
+    "Could not find factoredui-cluster edge function. Ensure @factoredui/core is installed correctly."
+  );
+}
 function writeConfig(targetDir) {
   const configPath = path.join(targetDir, CONFIG_FILENAME);
   if (fs.existsSync(configPath)) {
@@ -95,13 +126,32 @@ function printSetupInstructions() {
 Setup complete! Next steps:
 
   1. Update ${CONFIG_FILENAME} with your Supabase URL and anon key
-  2. Run: npx supabase db push
-  3. In your app:
+
+  2. Enable required Postgres extensions (if not already enabled):
+       - pg_cron    (scheduled clustering jobs)
+       - pg_net     (edge function invocation from pg_cron)
+       - vector     (pgvector for factor embeddings)
+
+  3. Add "factoredui" to your PostgREST schema config:
+     In supabase/config.toml:
+       [api]
+       schemas = ["public", "factoredui"]
+     Or set the env var: PGRST_DB_SCHEMAS=public,factoredui
+
+  4. Apply migrations:
+       npx supabase db push
+
+  5. Deploy the clustering edge function:
+       npx supabase functions deploy factoredui-cluster
+
+  6. In your app:
 
      import { initCapture } from '@factoredui/core'
      import { createClient } from '@supabase/supabase-js'
 
-     const supabase = createClient(url, anonKey)
+     const supabase = createClient(url, anonKey, {
+       db: { schema: 'factoredui' }
+     })
      const capture = initCapture({ supabase })
 
   For React Native / Expo:
@@ -113,4 +163,67 @@ Setup complete! Next steps:
      </Provider>
 `);
 }
+
+// src/sdui/ed25519.ts
+async function generateEd25519Keypair() {
+  const keypair = await crypto.subtle.generateKey("Ed25519", true, ["sign", "verify"]);
+  const publicKeyBytes = await crypto.subtle.exportKey("raw", keypair.publicKey);
+  const privateKeyBytes = await crypto.subtle.exportKey("pkcs8", keypair.privateKey);
+  return {
+    publicKey: bytesToBase64(new Uint8Array(publicKeyBytes)),
+    privateKey: bytesToBase64(new Uint8Array(privateKeyBytes))
+  };
+}
+function bytesToBase64(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+// src/cli/keygen.ts
+async function runKeygen() {
+  const { publicKey, privateKey } = await generateEd25519Keypair();
+  console.log("Ed25519 keypair generated.\n");
+  console.log("Public key (embed in client app):");
+  console.log(`  ${publicKey}
+`);
+  console.log("Private key (keep secret, use server-side for signing specs):");
+  console.log(`  ${privateKey}
+`);
+  console.log("Store the private key securely (env var, secret manager).");
+  console.log("The public key goes in your app config for spec signature verification.");
+}
+
+// src/cli/cli.ts
+var COMMANDS = {
+  init: runInit,
+  keygen: runKeygen
+};
+function main() {
+  const command = process.argv[2];
+  if (!command) {
+    printUsage();
+    process.exit(1);
+  }
+  const handler = COMMANDS[command];
+  if (!handler) {
+    console.error(`Unknown command: ${command}
+`);
+    printUsage();
+    process.exit(1);
+  }
+  Promise.resolve(handler()).catch((err) => {
+    console.error(`factoredui ${command} failed:`, err.message);
+    process.exit(1);
+  });
+}
+function printUsage() {
+  console.log(`Usage: factoredui <command>
+
+Commands:
+  init      Copy migrations and create config file
+  keygen    Generate Ed25519 keypair for SDUI spec signing`);
+}
 main();

package/dist/index.cjs

@@ -105,7 +105,7 @@ function createSessionManager(supabase, adapter, platform, timeoutMs = DEFAULT_T
 // src/capture/writer.ts
 var DEFAULT_FLUSH_INTERVAL_MS = 2e3;
 var DEFAULT_FLUSH_BATCH_SIZE = 50;
-function createEventWriter(supabase, flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS, flushBatchSize = DEFAULT_FLUSH_BATCH_SIZE) {
+function createEventWriter(supabase, flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS, flushBatchSize = DEFAULT_FLUSH_BATCH_SIZE, adapter) {
   let queue = [];
   let flushTimer = null;
   let isFlushing = false;
@@ -129,15 +129,37 @@ function createEventWriter(supabase, flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS
       const { error } = await supabase.from("events").insert(batch);
       if (error) {
         queue.unshift(...batch);
+        persistQueueToAdapter();
         console.error("factoredui: flush failed:", error.message);
       }
     } catch (err) {
       queue.unshift(...batch);
+      persistQueueToAdapter();
       console.error("factoredui: flush error:", err);
     } finally {
       isFlushing = false;
     }
   }
+  function persistQueueToAdapter() {
+    if (!adapter?.persistQueue || queue.length === 0) return;
+    try {
+      adapter.persistQueue(JSON.stringify(queue));
+    } catch {
+    }
+  }
+  function drainPersistedQueue() {
+    if (!adapter?.loadQueue) return;
+    try {
+      const serialized = adapter.loadQueue();
+      if (!serialized) return;
+      const persisted = JSON.parse(serialized);
+      if (persisted.length > 0) {
+        queue.unshift(...persisted);
+        adapter.persistQueue?.("");
+      }
+    } catch {
+    }
+  }
   function startAutoFlush() {
     if (flushTimer) return;
     flushTimer = setInterval(flush, flushIntervalMs);
@@ -148,7 +170,7 @@ function createEventWriter(supabase, flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS
       flushTimer = null;
     }
   }
-  return { enqueue, flush, startAutoFlush, stopAutoFlush };
+  return { enqueue, flush, startAutoFlush, stopAutoFlush, drainPersistedQueue };
 }
 
 // src/capture/path.ts
@@ -225,6 +247,7 @@ function detectScrollReversal(state, scrollY, now) {
 var THROTTLE_INTERVAL_MS = 100;
 var DEAD_CLICK_WAIT_MS = 1e3;
 var SESSION_STORAGE_KEY = "factoredui:session_id";
+var QUEUE_STORAGE_KEY = "factoredui:offline_queue";
 function createWebAdapter() {
   const handlers = /* @__PURE__ */ new Map();
   const rageClickState = createRageClickState();
@@ -309,9 +332,28 @@ function createWebAdapter() {
     storeSessionId,
     loadSessionId,
     clearSessionId,
-    registerUnloadHandler
+    registerUnloadHandler,
+    persistQueue,
+    loadQueue
   };
 }
+function persistQueue(serialized) {
+  try {
+    if (!serialized || serialized === "") {
+      localStorage.removeItem(QUEUE_STORAGE_KEY);
+    } else {
+      localStorage.setItem(QUEUE_STORAGE_KEY, serialized);
+    }
+  } catch {
+  }
+}
+function loadQueue() {
+  try {
+    return localStorage.getItem(QUEUE_STORAGE_KEY);
+  } catch {
+    return null;
+  }
+}
 function collectSessionMetadata() {
   if (typeof window === "undefined") return {};
   return {
@@ -833,10 +875,10 @@ function createSeededRng(seed) {
 }
 
 // src/experiment/targeting.ts
-function evaluateTargeting(factors, rules) {
+function evaluateTargeting(factors, rules, deviceMetadata) {
   if (rules.length === 0) return true;
   const factorsByName = indexFactorsByName(factors);
-  return rules.every((rule) => evaluateRule(factorsByName, rule));
+  return rules.every((rule) => evaluateRule(factorsByName, rule, deviceMetadata));
 }
 function indexFactorsByName(factors) {
   const indexed = /* @__PURE__ */ new Map();
@@ -845,12 +887,32 @@ function indexFactorsByName(factors) {
   }
   return indexed;
 }
-function evaluateRule(factorsByName, rule) {
-  const value = factorsByName.get(rule.factor);
-  if (value === void 0) return false;
-  return compareValue(value, rule.operator, rule.threshold);
+function isMetadataRule(rule) {
+  return "type" in rule && rule.type === "metadata";
+}
+function isFactorRule(rule) {
+  return !("type" in rule) || rule.type === "factor";
+}
+function evaluateRule(factorsByName, rule, deviceMetadata) {
+  if (isMetadataRule(rule)) {
+    return evaluateMetadataRule(rule, deviceMetadata);
+  }
+  if (isFactorRule(rule)) {
+    const threshold = "threshold" in rule ? rule.threshold : 0;
+    const factorName = rule.factor;
+    const value = factorsByName.get(factorName);
+    if (value === void 0) return false;
+    return compareNumeric(value, rule.operator, threshold);
+  }
+  return false;
+}
+function evaluateMetadataRule(rule, metadata) {
+  if (!metadata) return false;
+  const fieldValue = metadata[rule.field];
+  if (fieldValue === void 0 || fieldValue === null) return false;
+  return compareString(fieldValue, rule.operator, rule.value);
 }
-function compareValue(value, operator, threshold) {
+function compareNumeric(value, operator, threshold) {
   switch (operator) {
     case "gt":
       return value > threshold;
@@ -864,9 +926,25 @@ function compareValue(value, operator, threshold) {
       return value === threshold;
   }
 }
+function compareString(value, operator, target) {
+  const lower = value.toLowerCase();
+  const targetLower = target.toLowerCase();
+  switch (operator) {
+    case "eq":
+      return lower === targetLower;
+    case "neq":
+      return lower !== targetLower;
+    case "contains":
+      return lower.includes(targetLower);
+    case "gte":
+      return lower >= targetLower;
+    case "lte":
+      return lower <= targetLower;
+  }
+}
 
 // src/experiment/flags.ts
-async function evaluateFlag(supabase, experimentName, platform) {
+async function evaluateFlag(supabase, experimentName, platform, deviceMetadata) {
   const userId = await resolveUserId2(supabase);
   if (!userId) return null;
   const existingAssignment = await fetchAssignment(supabase, userId, experimentName);
@@ -874,7 +952,7 @@ async function evaluateFlag(supabase, experimentName, platform) {
     await recordExposure(supabase, userId, existingAssignment);
     return existingAssignment;
   }
-  const newAssignment = await assignToExperiment(supabase, userId, experimentName, platform);
+  const newAssignment = await assignToExperiment(supabase, userId, experimentName, platform, deviceMetadata);
   if (newAssignment) {
     await recordExposure(supabase, userId, newAssignment);
   }
@@ -899,10 +977,17 @@ async function fetchAssignment(supabase, userId, experimentName) {
     config: row.experiment_variants?.config ?? {}
   };
 }
-async function assignToExperiment(supabase, userId, experimentName, platform) {
+async function assignToExperiment(supabase, userId, experimentName, platform, deviceMetadata) {
   const experiment = await fetchRunningExperiment(supabase, experimentName, platform);
   if (!experiment) return null;
-  const isTargeted = await checkTargeting(supabase, userId, experiment);
+  const hasConflict = await hasConflictingAssignment(
+    supabase,
+    userId,
+    experiment.component_path,
+    experiment.id
+  );
+  if (hasConflict) return null;
+  const isTargeted = await checkTargeting(supabase, userId, experiment, deviceMetadata);
   if (!isTargeted) return null;
   const variants = await fetchExperimentVariants(supabase, experiment.id);
   if (variants.length === 0) return null;
@@ -920,6 +1005,11 @@ async function assignToExperiment(supabase, userId, experimentName, platform) {
     config: selectedVariant.config
   };
 }
+async function hasConflictingAssignment(supabase, userId, componentPath, currentExperimentId) {
+  const { data, error } = await supabase.from("experiment_assignments").select("experiment_id, experiments!inner ( id, status, component_path )").eq("user_id", userId).eq("experiments.status", "running").eq("experiments.component_path", componentPath).neq("experiment_id", currentExperimentId).limit(1);
+  if (error) return false;
+  return (data?.length ?? 0) > 0;
+}
 async function fetchRunningExperiment(supabase, experimentName, platform) {
   const { data, error } = await supabase.from("experiments").select("id, name, component_path, targeting_rules, platforms").eq("name", experimentName).eq("status", "running").maybeSingle();
   if (error || !data) return null;
@@ -929,10 +1019,10 @@ async function fetchRunningExperiment(supabase, experimentName, platform) {
   }
   return experiment;
 }
-async function checkTargeting(supabase, userId, experiment) {
+async function checkTargeting(supabase, userId, experiment, deviceMetadata) {
   if (!experiment.targeting_rules || experiment.targeting_rules.length === 0) return true;
   const factors = await queryFactors(supabase, userId, experiment.component_path);
-  return evaluateTargeting(factors, experiment.targeting_rules);
+  return evaluateTargeting(factors, experiment.targeting_rules, deviceMetadata);
 }
 async function fetchExperimentVariants(supabase, experimentId) {
   const { data, error } = await supabase.from("experiment_variants").select("variant_key, config, traffic_percentage").eq("experiment_id", experimentId).order("variant_key");
@@ -974,8 +1064,11 @@ async function createExperiment(client, definition) {
   return experiment;
 }
 async function startExperiment(client, experimentId) {
-  const { error } = await client.from("experiments").update({ status: "running" }).eq("id", experimentId).eq("status", "draft");
+  const { data, error } = await client.from("experiments").update({ status: "running" }).eq("id", experimentId).eq("status", "draft").select("id");
   if (error) throw new Error(`startExperiment failed: ${error.message}`);
+  if (!data || data.length === 0) {
+    throw new Error(`startExperiment: experiment ${experimentId} not found or not in draft status`);
+  }
 }
 function validateDefinition(definition) {
   if (definition.variants.length < 2) {