@koryla/node 0.1.0 → 0.1.2

package/README.md

@@ -9,44 +9,59 @@ Works on Railway, Render, Fly.io, Heroku, AWS EC2/ECS, or any Node host.
 npm install @koryla/node
 ```
 
-## Setup (Express)
+## Setup
+
+### 1. Add environment variables
+
+```bash
+KORYLA_API_KEY=sk_live_...
+KORYLA_API_URL=https://koryla.com
+```
+
+### 2. Add the middleware
+
+Place it **before** your routes — Koryla rewrites `req.url` internally so Express routes to the correct handler:
 
 ```ts
+// server.ts
 import express from 'express'
 import { korylaMiddleware } from '@koryla/node'
 
 const app = express()
 
-// Add Koryla before your routes
 app.use(korylaMiddleware({
   apiKey: process.env.KORYLA_API_KEY!,
-  apiUrl: process.env.KORYLA_API_URL!,   // your deployed Koryla app URL
+  apiUrl: process.env.KORYLA_API_URL!,
 }))
 
-// Variant pages must exist as real routes in the same app
+// Routes come after — they receive the rewritten req.url
 app.get('/', (req, res) => res.render('home-control'))
 app.get('/variant-b', (req, res) => res.render('home-variant-b'))
-app.get('/pricing', (req, res) => res.render('pricing-control'))
-app.get('/pricing-b', (req, res) => res.render('pricing-variant-b'))
 ```
 
-### Environment variables
+### 3. Create your variant pages
 
-```bash
-KORYLA_API_KEY=sk_live_...
-KORYLA_API_URL=https://your-koryla-app.vercel.app
+Variant pages must be real routes in the same Express app:
+
+```
+app/
+  views/
+    home-control.ejs    ← control  (base_url: https://acme.com/)
+    home-variant-b.ejs  ← variant  (target_url: https://acme.com/variant-b)
 ```
 
-## Important: variant pages must be in the same app
+### 4. Create an experiment in Koryla
 
-Unlike edge adapters that can proxy to any URL, the Node middleware rewrites
-`req.url` internally and calls `next()`. This means:
+Go to your Koryla dashboard → New experiment:
 
-- ✅ Your variant pages are routes in the same Express app
-- ❌ Your variants are on a different domain/server
+| Field | Value |
+|-------|-------|
+| Base URL | `https://acme.com/` |
+| Variant A — Control | `https://acme.com/` · 50% |
+| Variant B | `https://acme.com/variant-b` · 50% |
+| Conversion URL | `https://acme.com/thank-you` |
 
-If your variants are on a different origin you'll need a reverse proxy
-(nginx, Caddy) in front of your app instead.
+Set it to **Active** and you're done.
 
 ## How it works
 
@@ -56,25 +71,25 @@ User visits /
      ▼
 Express middleware (in-process, ~1ms overhead)
      │
-     ├── fetches Koryla config once every 60s (cached in memory)
-     ├── reads sp_<experimentId> cookie
-     ├── assigns variant, rewrites req.url to /variant-b
-     └── sets Set-Cookie header on response
+     ├── calls Koryla API once every 60s to get experiment config
+     ├── reads koryla_sid cookie
+     │     ├── cookie present → use existing variant (sticky)
+     │     └── no cookie → assign variant by traffic weight
+     │
+     ├── rewrites req.url to /variant-b
+     └── sets Set-Cookie header for 30 days
      │
      ▼
 Express routes /variant-b to its handler
 Browser sees original URL (/) — no redirect, no flicker
 ```
 
-## Difference vs edge adapters
+## Why this is better than VWO / Optimizely
 
-| | @koryla/node | @koryla/next / @koryla/netlify |
+| | VWO / Optimizely | @koryla/node |
 |--|--|--|
-| Runs at | Your app server | CDN edge node near the user |
-| Latency added | ~1ms (in-process) | ~1ms (in-process) |
-| Koryla API call | Cached 60s | Cached 60s |
-| Variants on different origin | ❌ (same app only) | ✅ |
-| Zero flicker | ✅ | ✅ |
-
-Both approaches are server-side — neither has the flicker problem of client-side tools.
-The only difference is where the server runs.
+| When variant is decided | In the browser, after JS loads | On the server, before any HTML |
+| Flicker | Yes (page hides while swapping) | No |
+| Extra JS on page | ~80–150 KB | 0 KB |
+| Blockable by ad blockers | Yes | No |
+| Works without JS | No | Yes |

package/dist/index.cjs

@@ -20,7 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  korylaMiddleware: () => korylaMiddleware
+  korylaMiddleware: () => korylaMiddleware,
+  trackConversion: () => trackConversion
 });
 module.exports = __toCommonJS(index_exports);
 var import_core = require("@koryla/core");
@@ -39,17 +40,18 @@ function korylaMiddleware(options) {
       const variantPath = new URL(result.targetUrl).pathname;
       req.url = variantPath;
       if (req.originalUrl) req.originalUrl = variantPath;
+      const maxAge = 60 * 60 * 24 * 30;
+      const newCookies = [];
       if (result.isNewAssignment) {
-        const maxAge = 60 * 60 * 24 * 30;
-        const cookie = `${result.cookieName}=${result.variantId}; Path=/; Max-Age=${maxAge}; SameSite=Lax`;
+        newCookies.push(`${result.cookieName}=${result.variantId}; Path=/; Max-Age=${maxAge}; SameSite=Lax`);
+      }
+      if (result.isNewSession) {
+        newCookies.push(`ky_sid=${result.sessionId}; Path=/; Max-Age=${maxAge}; SameSite=Lax`);
+      }
+      if (newCookies.length) {
         const existing = res.getHeader("Set-Cookie");
-        if (Array.isArray(existing)) {
-          res.setHeader("Set-Cookie", [...existing, cookie]);
-        } else if (existing) {
-          res.setHeader("Set-Cookie", [existing, cookie]);
-        } else {
-          res.setHeader("Set-Cookie", cookie);
-        }
+        const all = [...Array.isArray(existing) ? existing : existing ? [existing] : [], ...newCookies];
+        res.setHeader("Set-Cookie", all.length === 1 ? all[0] : all);
       }
       next();
     } catch {
@@ -57,7 +59,28 @@ function korylaMiddleware(options) {
     }
   };
 }
+async function trackConversion(req, options) {
+  const cookieHeader = req.headers["cookie"] ?? "";
+  const cookies = Object.fromEntries(
+    cookieHeader.split(";").map((c) => c.trim().split("=").map((s) => s.trim())).filter(([k]) => k?.length > 0)
+  );
+  const sessionId = cookies["ky_sid"];
+  if (!sessionId) return;
+  for (const [key, value] of Object.entries(cookies)) {
+    if (!key.startsWith("ky_") || key === "ky_sid") continue;
+    const experimentId = key.slice(3);
+    try {
+      await fetch(`${options.apiUrl}/api/worker/event`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${options.apiKey}` },
+        body: JSON.stringify({ experiment_id: experimentId, variant_id: value, session_id: sessionId, event_type: "conversion" })
+      });
+    } catch {
+    }
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  korylaMiddleware
+  korylaMiddleware,
+  trackConversion
 });

package/dist/index.d.cts

@@ -51,5 +51,13 @@ interface NodeResponse {
 }
 type NextFunction = (err?: unknown) => void;
 declare function korylaMiddleware(options: SplitEngineOptions): (req: NodeRequest, res: NodeResponse, next: NextFunction) => Promise<void>;
+/**
+ * Manually fire a conversion event. Use this when the conversion happens
+ * via an API call or form POST rather than a page visit.
+ *
+ * For page-visit conversions, set the conversion URL on the experiment in
+ * the Koryla dashboard — the middleware fires the event automatically.
+ */
+declare function trackConversion(req: NodeRequest, options: SplitEngineOptions): Promise<void>;
 
-export { type NextFunction, type NodeRequest, type NodeResponse, korylaMiddleware };
+export { type NextFunction, type NodeRequest, type NodeResponse, korylaMiddleware, trackConversion };

package/dist/index.d.ts

@@ -51,5 +51,13 @@ interface NodeResponse {
 }
 type NextFunction = (err?: unknown) => void;
 declare function korylaMiddleware(options: SplitEngineOptions): (req: NodeRequest, res: NodeResponse, next: NextFunction) => Promise<void>;
+/**
+ * Manually fire a conversion event. Use this when the conversion happens
+ * via an API call or form POST rather than a page visit.
+ *
+ * For page-visit conversions, set the conversion URL on the experiment in
+ * the Koryla dashboard — the middleware fires the event automatically.
+ */
+declare function trackConversion(req: NodeRequest, options: SplitEngineOptions): Promise<void>;
 
-export { type NextFunction, type NodeRequest, type NodeResponse, korylaMiddleware };
+export { type NextFunction, type NodeRequest, type NodeResponse, korylaMiddleware, trackConversion };

package/dist/index.js

@@ -15,17 +15,18 @@ function korylaMiddleware(options) {
       const variantPath = new URL(result.targetUrl).pathname;
       req.url = variantPath;
       if (req.originalUrl) req.originalUrl = variantPath;
+      const maxAge = 60 * 60 * 24 * 30;
+      const newCookies = [];
       if (result.isNewAssignment) {
-        const maxAge = 60 * 60 * 24 * 30;
-        const cookie = `${result.cookieName}=${result.variantId}; Path=/; Max-Age=${maxAge}; SameSite=Lax`;
+        newCookies.push(`${result.cookieName}=${result.variantId}; Path=/; Max-Age=${maxAge}; SameSite=Lax`);
+      }
+      if (result.isNewSession) {
+        newCookies.push(`ky_sid=${result.sessionId}; Path=/; Max-Age=${maxAge}; SameSite=Lax`);
+      }
+      if (newCookies.length) {
         const existing = res.getHeader("Set-Cookie");
-        if (Array.isArray(existing)) {
-          res.setHeader("Set-Cookie", [...existing, cookie]);
-        } else if (existing) {
-          res.setHeader("Set-Cookie", [existing, cookie]);
-        } else {
-          res.setHeader("Set-Cookie", cookie);
-        }
+        const all = [...Array.isArray(existing) ? existing : existing ? [existing] : [], ...newCookies];
+        res.setHeader("Set-Cookie", all.length === 1 ? all[0] : all);
       }
       next();
     } catch {
@@ -33,6 +34,27 @@ function korylaMiddleware(options) {
     }
   };
 }
+async function trackConversion(req, options) {
+  const cookieHeader = req.headers["cookie"] ?? "";
+  const cookies = Object.fromEntries(
+    cookieHeader.split(";").map((c) => c.trim().split("=").map((s) => s.trim())).filter(([k]) => k?.length > 0)
+  );
+  const sessionId = cookies["ky_sid"];
+  if (!sessionId) return;
+  for (const [key, value] of Object.entries(cookies)) {
+    if (!key.startsWith("ky_") || key === "ky_sid") continue;
+    const experimentId = key.slice(3);
+    try {
+      await fetch(`${options.apiUrl}/api/worker/event`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${options.apiKey}` },
+        body: JSON.stringify({ experiment_id: experimentId, variant_id: value, session_id: sessionId, event_type: "conversion" })
+      });
+    } catch {
+    }
+  }
+}
 export {
-  korylaMiddleware
+  korylaMiddleware,
+  trackConversion
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koryla/node",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -18,15 +18,15 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
-    "dev": "tsup src/index.ts --format esm,cjs --dts --watch"
-  },
   "dependencies": {
     "@koryla/core": "^0.2.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0",
     "typescript": "^5"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch"
   }
-}
+}