hazo_umetrics 1.2.1 → 1.3.0

package/CHANGE_LOG.md

@@ -1,9 +1,19 @@
 # hazo_umetrics — Change Log
 
-## 1.3.0 — Analytics dashboard + behavioral fixes
+## 1.3.0 — Analytics dashboard + behavioral fixes + createUmetricsConnect
 
 **New features + bug fixes (no breaking changes):**
 
+### New: `createUmetricsConnect` — dedicated DB factory
+- `createUmetricsConnect(opts?)` builds a `HazoConnectAdapter` from `HAZO_UMETRICS_DATABASE_*`
+  env vars (type / URL / API key / SQLite path), with INI `[database]` as fallback. Returns a
+  cached adapter on no-arg calls; creates fresh when opts are passed.
+- Exported from main `hazo_umetrics` entry: `import { createUmetricsConnect } from 'hazo_umetrics'`
+- `UmetricsConnectOptions` type exported alongside the factory.
+- Enables wiring umetrics to a **separate DB** from the host app in one line:
+  `createStatHandlers({ getAdapter: createUmetricsConnect })`
+- Updated `config/hazo_umetrics_config.ini.sample` `[database]` section with dedicated env-var docs.
+
 ### New: `topActions` behavior aggregation
 - `topActions` function in `src/server/behavior.ts` — ranks all `action.*` events by frequency, no `user_id` required. Answers "what is the most common action?" without needing session segmentation.
 - Exposed as `metric=top_actions` in `GET /api/hazo_umetrics/analytics/behavior`.

package/README.md

@@ -139,7 +139,46 @@ const expHandlers = createExperimentHandlers({ getAdapter: () => myAdapter });
 
 ## DB setup
 
-Run `db_setup_sqlite.sql` (SQLite) or `db_setup_postgres.sql` (PostgreSQL) once. Creates 7 tables, all prefixed `hazo_umetrics_`.
+Run `db_setup_sqlite.sql` (SQLite) or `db_setup_postgres.sql` (PostgreSQL) once against your **umetrics DB**. Creates 7 tables, all prefixed `hazo_umetrics_`.
+
+> Run the migration against the **dedicated umetrics database**, not the host app's main DB.
+> If you use `createUmetricsConnect()` (recommended), the umetrics DB is the one pointed to
+> by `HAZO_UMETRICS_DATABASE_URL`.
+
+## Separate database for umetrics
+
+`hazo_umetrics` data (events, stats, flags, experiments) should live in its own database,
+**separate from the host app's main DB**. This keeps analytics writes from competing with
+product data, lets you point multiple apps at one shared analytics store, and lets you
+scale each independently.
+
+Use `createUmetricsConnect()` to build a dedicated adapter in one line:
+
+```ts
+import { createUmetricsConnect } from 'hazo_umetrics';
+
+// Reads HAZO_UMETRICS_DATABASE_URL + HAZO_UMETRICS_DATABASE_API_KEY from env.
+// Falls back to ./umetrics.sqlite when type=sqlite.
+export const getUmetricsAdapter = createUmetricsConnect;
+```
+
+Then inject it into every route factory:
+
+```ts
+const handlers = createStatHandlers({ getAdapter: createUmetricsConnect });
+```
+
+### Env vars
+
+| Variable | Required | Description |
+|---|---|---|
+| `HAZO_UMETRICS_DATABASE_URL` | PostgREST only | Base URL of the umetrics PostgREST server |
+| `HAZO_UMETRICS_DATABASE_API_KEY` | PostgREST only | Bearer token for the umetrics PostgREST server |
+| `HAZO_UMETRICS_DATABASE_TYPE` | No | `postgrest` (default) or `sqlite` |
+| `HAZO_UMETRICS_DATABASE_PATH` | SQLite only | Path to the SQLite file (default: `./umetrics.sqlite`) |
+
+These are independent of the host app's `POSTGREST_URL` / `POSTGREST_API_KEY` — the
+analytics DB can be a completely different PostgREST instance (or a local SQLite file for dev).
 
 ## Config
 

package/SETUP_CHECKLIST.md

@@ -33,7 +33,24 @@ db.close();
 
 **PostgreSQL:** Run `node_modules/hazo_umetrics/db_setup_postgres.sql` against your database.
 
-## 3. Set env vars for cookie signing
+## 3. Set env vars for the umetrics database
+
+`createUmetricsConnect()` reads these variables to connect to the dedicated umetrics DB:
+
+```bash
+# PostgREST mode (production / staging)
+HAZO_UMETRICS_DATABASE_URL=https://your-umetrics-postgrest.example.com
+HAZO_UMETRICS_DATABASE_API_KEY=<bearer-token>
+
+# SQLite mode (local dev — omit DATABASE_URL to fall back to ./umetrics.sqlite)
+# HAZO_UMETRICS_DATABASE_TYPE=sqlite
+# HAZO_UMETRICS_DATABASE_PATH=./umetrics.sqlite
+```
+
+> Run `db_setup_postgres.sql` (or `db_setup_sqlite.sql`) against this **umetrics DB**, not
+> the host app's main database.
+
+## 4. Set env vars for cookie signing
 
 ```bash
 # Generate a 32-byte key: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
@@ -41,11 +58,11 @@ HAZO_UMETRICS_COOKIE_KEY_CURRENT=v1
 HAZO_UMETRICS_COOKIE_KEY_v1=<base64-encoded 32-byte key>
 ```
 
-## 4. Add config file (optional)
+## 5. Add config file (optional)
 
 Copy `node_modules/hazo_umetrics/config/hazo_umetrics_config.ini.sample` to your app's config directory as `hazo_umetrics_config.ini` and fill in `[ga4]` when ready for M1.
 
-## 5. Mount API routes (Next.js)
+## 6. Mount API routes (Next.js)
 
 ```ts
 // app/api/hazo_umetrics/stats/route.ts
@@ -58,7 +75,7 @@ export async function GET(req: Request) { return handlers.getStat(req); }
 export async function POST(req: Request) { return handlers.recordStat(req); }
 ```
 
-## 6. Wrap your app in HazoMetricsProvider (client)
+## 7. Wrap your app in HazoMetricsProvider (client)
 
 ```tsx
 // app/layout.tsx
@@ -73,7 +90,7 @@ export default function RootLayout({ children }) {
 }
 ```
 
-## 7. Configure Tailwind (if you use hazo_umetrics UI components)
+## 8. Configure Tailwind (if you use hazo_umetrics UI components)
 
 `MetricsPanel` uses shadcn token utilities (`bg-background`, `text-muted-foreground`, `border`, etc.) from `hazo_ui`. Without the token definitions the dialog panel will render transparent. In your `globals.css`:
 
@@ -112,7 +129,7 @@ export default function RootLayout({ children }) {
 
 (Adjust `@import` and `@source` depth to match your project's distance from `node_modules`.)
 
-## 8. Smoke test
+## 9. Smoke test
 
 ```ts
 import { recordStat, getLatestStat } from 'hazo_umetrics';

package/config/hazo_umetrics_config.ini.sample

@@ -8,14 +8,25 @@
 app_id = my_app
 
 [database]
-; Set type = postgrest to use a PostgREST HTTP adapter (recommended for production).
-; Set type = sqlite for local development without a Postgres instance.
+; Dedicated hazo_umetrics database — separate from the host app's main DB.
+; Use createUmetricsConnect() from hazo_umetrics to wire this adapter.
+;
+; type: postgrest (default) | sqlite
+; Env-var override: HAZO_UMETRICS_DATABASE_TYPE
 ; type = postgrest
+;
+; PostgREST mode (recommended for production):
+;   base_url — the PostgREST server base URL
+;   Env-var override: HAZO_UMETRICS_DATABASE_URL
 ; base_url = http://your-postgrest-host:4444
-; api_key comes from POSTGREST_API_KEY env var — do not store it here.
+;   api_key — bearer token (env only, never store in INI)
+;   Set: HAZO_UMETRICS_DATABASE_API_KEY=<your-token>
+;
+; SQLite mode (local development without a Postgres instance):
+;   database_path — path to the SQLite file (default: ./umetrics.sqlite)
+;   Env-var override: HAZO_UMETRICS_DATABASE_PATH
 ; type = sqlite
-; driver = better-sqlite3
-; database_path = ./umetrics_test.sqlite
+; database_path = ./umetrics.sqlite
 
 [env]
 ; Uncomment to hard-code the environment name (overrides HAZO_ENV / NODE_ENV).

package/dist/lib/index.d.ts

@@ -7,4 +7,5 @@ export * from '../server/ga4.js';
 export * from '../server/experiments.js';
 export * from '../server/activity.js';
 export * from '../server/behavior.js';
+export * from '../server/connect.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AACA,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AACA,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC"}

package/dist/lib/index.js

@@ -8,3 +8,4 @@ export * from '../server/ga4.js';
 export * from '../server/experiments.js';
 export * from '../server/activity.js';
 export * from '../server/behavior.js';
+export * from '../server/connect.js';

package/dist/server/connect.d.ts

@@ -0,0 +1,11 @@
+import 'server-only';
+import { type HazoConnectAdapter } from 'hazo_connect/server';
+export interface UmetricsConnectOptions {
+    type?: string;
+    base_url?: string;
+    api_key?: string;
+    database_path?: string;
+    iniPath?: string;
+}
+export declare function createUmetricsConnect(opts?: UmetricsConnectOptions): HazoConnectAdapter;
+//# sourceMappingURL=connect.d.ts.map

package/dist/server/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../src/server/connect.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,CAAC;AACrB,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAIjF,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,wBAAgB,qBAAqB,CAAC,IAAI,CAAC,EAAE,sBAAsB,GAAG,kBAAkB,CASvF"}

package/dist/server/connect.js

@@ -0,0 +1,58 @@
+import 'server-only';
+import { createHazoConnect } from 'hazo_connect/server';
+import { HazoConfig } from 'hazo_config/server';
+import { resolve as pathResolve } from 'node:path';
+let _cached = null;
+export function createUmetricsConnect(opts) {
+    // If opts explicitly provided, always create fresh (not cached)
+    if (opts) {
+        return _build(opts);
+    }
+    if (!_cached) {
+        _cached = _build(opts);
+    }
+    return _cached;
+}
+function _build(opts) {
+    // Load INI config (graceful — missing file falls back to env/opts)
+    const iniPath = opts?.iniPath ?? pathResolve(process.cwd(), 'config/hazo_umetrics_config.ini');
+    let _cfg = null;
+    try {
+        _cfg = new HazoConfig({ filePath: iniPath });
+    }
+    catch {
+        // Config file missing — fall back to env vars and opts
+    }
+    function ini(section, key) {
+        return _cfg?.get(section, key);
+    }
+    // Resolution order: opts > env > INI > default
+    const type = opts?.type ??
+        process.env.HAZO_UMETRICS_DATABASE_TYPE ??
+        ini('database', 'type') ??
+        'postgrest';
+    if (type === 'sqlite') {
+        const database_path = opts?.database_path ??
+            process.env.HAZO_UMETRICS_DATABASE_PATH ??
+            ini('database', 'database_path') ??
+            './umetrics.sqlite';
+        return createHazoConnect({
+            type: 'sqlite',
+            sqlite: { driver: 'better-sqlite3', database_path },
+        });
+    }
+    // PostgREST mode
+    const base_url = opts?.base_url ??
+        process.env.HAZO_UMETRICS_DATABASE_URL ??
+        ini('database', 'base_url');
+    const api_key = opts?.api_key ??
+        process.env.HAZO_UMETRICS_DATABASE_API_KEY;
+    if (!base_url || !api_key) {
+        throw new Error('hazo_umetrics: HAZO_UMETRICS_DATABASE_URL and HAZO_UMETRICS_DATABASE_API_KEY must be set ' +
+            '(or pass { base_url, api_key } to createUmetricsConnect)');
+    }
+    return createHazoConnect({
+        type: 'postgrest',
+        postgrest: { base_url, api_key },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_umetrics",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Product analytics for hazo apps — GA4 hybrid + first-party stat store + feature flags",
   "type": "module",
   "module": "./dist/index.js",