feat: add Cloudflare Workers utility package and demo

Add @convertcom/js-sdk-cloudflare with edge-specific helpers for running
Convert experiments inside Cloudflare Workers: KV-backed DataStore adapter,
edge config cache, cookie helpers, and variation-aware cache utilities.

Includes a demo Worker (demo/cloudflare-workers/) demonstrating page-level
A/B testing with HTMLRewriter, asset swaps, split URL redirects, and SPA
injection patterns.

Updates release-please config, publish workflows, and root build scripts
to support the new package.

Author: abbaseya

.github/workflows/publish-package.yml

@@ -88,6 +88,12 @@ jobs:
           (cd packages/experience && npm publish --access public)
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - if: ${{ startsWith(env.RELEASE_TAG, 'js-sdk-cloudflare-v') }}
+        run: |
+          yarn cloudflare:build
+          (cd packages/cloudflare && npm publish --access public)
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
       - if: ${{ startsWith(env.RELEASE_TAG, 'js-sdk-v') }}
         run: |
           yarn sdk:build

.github/workflows/release-please.yml

@@ -56,5 +56,6 @@ jobs:
             packages/data)        yarn data:build        && (cd packages/data        && npm publish --access public) ;;
             packages/experience)  yarn experience:build  && (cd packages/experience  && npm publish --access public) ;;
             packages/js-sdk)      yarn sdk:build         && (cd packages/js-sdk      && npm publish --access public) ;;
+            packages/cloudflare)  yarn cloudflare:build  && (cd packages/cloudflare  && npm publish --access public) ;;
             *) echo "Unknown path: $REL_PATH" && exit 1 ;;
           esac

.release-please-manifest.json

@@ -10,5 +10,6 @@
   "packages/segments": "2.1.2",
   "packages/api": "2.1.4",
   "packages/data": "3.3.3",
-  "packages/experience": "2.3.2"
+  "packages/experience": "2.3.2",
+  "packages/cloudflare": "1.0.0"
 }

demo/cloudflare-workers/README.md

@@ -0,0 +1,71 @@
+# Convert SDK — Cloudflare Workers Demo
+
+A complete example of running Convert A/B tests at the Cloudflare edge with zero client-side flicker.
+
+## What This Demonstrates
+
+1. **Page-level A/B test** — HTMLRewriter modifies page content before delivery
+2. **Asset / image swap** — Replace images or stylesheets per variation
+3. **Split URL redirect** — Serve entirely different origin pages transparently
+4. **SPA injection** — Inject bucketing decisions as JSON for client-side SPAs
+5. **Edge caching** — Cache origin responses per variation
+
+## Setup
+
+### 1. Install Dependencies
+
+```bash
+yarn install
+```
+
+### 2. Create a KV Namespace
+
+```bash
+wrangler kv namespace create CONVERT_KV
+```
+
+Copy the output `id` into `wrangler.toml`.
+
+### 3. Configure
+
+Edit `wrangler.toml`:
+- Set your KV namespace ID
+- Set your Convert SDK key (`CONVERT_SDK_KEY`)
+
+### 4. Update Experiment Keys
+
+In `src/index.ts`, replace `'your-experience-key'` with your actual experience key from the Convert dashboard.
+
+### 5. Run
+
+```bash
+# Local development
+yarn dev
+
+# Deploy to production
+yarn deploy
+
+# View live logs
+yarn tail
+```
+
+## How It Works
+
+```
+Visitor → Cloudflare Edge → Worker
+                              ├── Read config from KV (cached, ~1ms)
+                              ├── Read visitor data from KV (~1ms)
+                              ├── SDK: bucket visitor into variation
+                              ├── Fetch origin page
+                              ├── HTMLRewriter: modify HTML per variation
+                              ├── Set visitor cookie
+                              └── Respond (total edge overhead: ~5-8ms)
+
+                              └── Background (waitUntil):
+                                  ├── Save bucketing to KV
+                                  └── Send tracking event to Convert
+```
+
+## Documentation
+
+Full guide: [Cloudflare Workers Edge Experimentation](https://github.com/convertcom/javascript-sdk/wiki/CloudflareWorkers)

demo/cloudflare-workers/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@convertcom/js-sdk-demo-cloudflare-workers",
+  "version": "1.0.0",
+  "author": "Convert Insights, Inc",
+  "license": "Apache-2.0",
+  "private": true,
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "tail": "wrangler tail"
+  },
+  "dependencies": {
+    "@convertcom/js-sdk": "^4.3.4",
+    "@convertcom/js-sdk-cloudflare": "^1.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20241205.0",
+    "typescript": "^5.9.3",
+    "wrangler": "^3.99.0"
+  }
+}