hazo_umetrics 0.1.1

package/dist/api/index.js

@@ -0,0 +1,375 @@
+// hazo_umetrics/src/api/index.ts — HTTP route handler factories.
+//
+// hazo_auth is NOT imported at the top level. It carries an `import 'server-only'`
+// guard inside `hazo_auth/server-lib`, which would crash test environments if
+// pulled in eagerly. Instead, each handler dynamically imports it on first use,
+// or callers supply their own `getAuth` implementation.
+import { createCrudService } from 'hazo_connect/server';
+import { recordStat as _recordStat, getLatestStat as _getLatestStat, getStatSeries as _getStatSeries, } from '../server/stats.js';
+import { resolveVariant } from '../server/flags.js';
+// ---------------------------------------------------------------------------
+// Default auth — dynamically imports hazo_auth/server-lib to avoid the
+// server-only guard firing at module-evaluation time (e.g. in test runners).
+// ---------------------------------------------------------------------------
+async function defaultGetAuth(req, opts) {
+    const { hazo_get_auth } = await import('hazo_auth/server-lib');
+    return hazo_get_auth(req, opts);
+}
+// ---------------------------------------------------------------------------
+// Auth gate helper
+// ---------------------------------------------------------------------------
+async function gateAuth(req, opts) {
+    const result = await opts.getAuth(req, {
+        required_permissions: opts.required_permissions,
+        scope_id: opts.scope_id,
+        strict: false,
+    });
+    if (!result.authenticated) {
+        return {
+            ok: false,
+            response: new Response(JSON.stringify({
+                ok: false,
+                error: { code: 'UNAUTHORIZED', message: 'Authentication required' },
+            }), { status: 401, headers: { 'Content-Type': 'application/json' } }),
+        };
+    }
+    if (!result.permission_ok) {
+        return {
+            ok: false,
+            response: new Response(JSON.stringify({
+                ok: false,
+                error: { code: 'FORBIDDEN', message: 'Missing required permission' },
+            }), { status: 403, headers: { 'Content-Type': 'application/json' } }),
+        };
+    }
+    if (opts.scope_id && result.scope_ok === false) {
+        return {
+            ok: false,
+            response: new Response(JSON.stringify({
+                ok: false,
+                error: { code: 'FORBIDDEN', message: 'Scope access denied' },
+            }), { status: 403, headers: { 'Content-Type': 'application/json' } }),
+        };
+    }
+    return { ok: true, userId: result.user.id };
+}
+// ---------------------------------------------------------------------------
+// JSON helpers
+// ---------------------------------------------------------------------------
+function jsonOk(data, status = 200) {
+    return new Response(JSON.stringify({ ok: true, data }), {
+        status,
+        headers: { 'Content-Type': 'application/json' },
+    });
+}
+function jsonError(code, message, status) {
+    return new Response(JSON.stringify({ ok: false, error: { code, message } }), {
+        status,
+        headers: { 'Content-Type': 'application/json' },
+    });
+}
+// ---------------------------------------------------------------------------
+// createStatHandlers
+// ---------------------------------------------------------------------------
+export function createStatHandlers(options) {
+    const getAuth = options.getAuth ?? defaultGetAuth;
+    return {
+        /**
+         * GET /...?scope_id=<id>&metric_key=<key>
+         * Returns the latest reading for the metric, or null if none.
+         */
+        async getStat(req) {
+            const url = new URL(req.url);
+            const scope_id = url.searchParams.get('scope_id') ?? '';
+            const metric_key = url.searchParams.get('metric_key') ?? '';
+            const gate = await gateAuth(req, {
+                required_permissions: ['metrics.view'],
+                scope_id: scope_id || undefined,
+                getAuth,
+            });
+            if (!gate.ok)
+                return gate.response;
+            if (!scope_id || !metric_key) {
+                return jsonError('BAD_REQUEST', 'scope_id and metric_key are required', 400);
+            }
+            const adapter = await options.getAdapter();
+            const stat = await _getLatestStat(adapter, { scope_id, metric_key });
+            return jsonOk({ stat });
+        },
+        /**
+         * GET /...?scope_id=<id>&metric_key=<key>[&since=<iso>][&limit=<n>]
+         * Returns time-series readings.
+         */
+        async getStatSeries(req) {
+            const url = new URL(req.url);
+            const scope_id = url.searchParams.get('scope_id') ?? '';
+            const metric_key = url.searchParams.get('metric_key') ?? '';
+            const since = url.searchParams.get('since') ?? undefined;
+            const limitParam = url.searchParams.get('limit');
+            const limit = limitParam != null ? parseInt(limitParam, 10) : undefined;
+            const gate = await gateAuth(req, {
+                required_permissions: ['metrics.view'],
+                scope_id: scope_id || undefined,
+                getAuth,
+            });
+            if (!gate.ok)
+                return gate.response;
+            if (!scope_id || !metric_key) {
+                return jsonError('BAD_REQUEST', 'scope_id and metric_key are required', 400);
+            }
+            const adapter = await options.getAdapter();
+            const series = await _getStatSeries(adapter, { scope_id, metric_key, since, limit });
+            return jsonOk({ series });
+        },
+        /**
+         * POST /...
+         * Body: { scope_id, metric_key, value, app_id?, unit?, dimensions? }
+         * Appends a new stat reading.
+         */
+        async recordStat(req) {
+            const url = new URL(req.url);
+            const scope_id = url.searchParams.get('scope_id') ?? '';
+            const gate = await gateAuth(req, {
+                required_permissions: ['metrics.view'],
+                scope_id: scope_id || undefined,
+                getAuth,
+            });
+            if (!gate.ok)
+                return gate.response;
+            let body;
+            try {
+                body = (await req.json());
+            }
+            catch {
+                return jsonError('BAD_REQUEST', 'Invalid JSON body', 400);
+            }
+            const { scope_id: bodyScopeId, metric_key, value, app_id, unit, dimensions } = body;
+            const resolvedScopeId = (bodyScopeId ?? scope_id);
+            if (!resolvedScopeId || !metric_key || value == null) {
+                return jsonError('BAD_REQUEST', 'scope_id, metric_key, and value are required', 400);
+            }
+            const adapter = await options.getAdapter();
+            await _recordStat(adapter, {
+                scope_id: resolvedScopeId,
+                metric_key,
+                value: value,
+                app_id,
+                unit,
+                dimensions,
+            });
+            return jsonOk({ recorded: true }, 201);
+        },
+    };
+}
+export function createExperimentHandlers(options) {
+    const getAuth = options.getAuth ?? defaultGetAuth;
+    function getExpCrud(adapter) {
+        return createCrudService(adapter, 'hazo_umetrics_experiment', {
+            primaryKeys: ['key', 'scope_id'],
+            autoId: false,
+        });
+    }
+    return {
+        /**
+         * GET /...?scope_id=<id>
+         * Lists all experiments for a scope.
+         */
+        async listExperiments(req) {
+            const url = new URL(req.url);
+            const scope_id = url.searchParams.get('scope_id') ?? '';
+            const gate = await gateAuth(req, {
+                required_permissions: ['metrics.view'],
+                scope_id: scope_id || undefined,
+                getAuth,
+            });
+            if (!gate.ok)
+                return gate.response;
+            if (!scope_id) {
+                return jsonError('BAD_REQUEST', 'scope_id is required', 400);
+            }
+            const adapter = await options.getAdapter();
+            const crud = getExpCrud(adapter);
+            const rows = await crud.list((qb) => qb.where('scope_id', 'eq', scope_id));
+            return jsonOk({ experiments: rows });
+        },
+        /**
+         * POST /...
+         * Body: { experimentKey, scope_id, subjectId?, consent? }
+         * Resolves the variant for a subject.
+         */
+        async evalVariant(req) {
+            const url = new URL(req.url);
+            const scope_id = url.searchParams.get('scope_id') ?? '';
+            const gate = await gateAuth(req, {
+                required_permissions: ['metrics.view'],
+                scope_id: scope_id || undefined,
+                getAuth,
+            });
+            if (!gate.ok)
+                return gate.response;
+            let body;
+            try {
+                body = (await req.json());
+            }
+            catch {
+                return jsonError('BAD_REQUEST', 'Invalid JSON body', 400);
+            }
+            const { experimentKey, scope_id: bodyScopeId, subjectId, consent, cookieValue, } = body;
+            const resolvedScopeId = (bodyScopeId ?? scope_id);
+            if (!resolvedScopeId || !experimentKey) {
+                return jsonError('BAD_REQUEST', 'experimentKey and scope_id are required', 400);
+            }
+            const adapter = await options.getAdapter();
+            const result = await resolveVariant(adapter, {
+                experimentKey,
+                scope_id: resolvedScopeId,
+                subjectId,
+                consent,
+                cookieValue,
+            });
+            return jsonOk(result);
+        },
+        /**
+         * POST /...
+         * Body: { key, scope_id }
+         * Transitions an experiment to 'running'. Requires metrics.manage.
+         */
+        async startExperiment(req) {
+            const url = new URL(req.url);
+            const scope_id = url.searchParams.get('scope_id') ?? '';
+            const gate = await gateAuth(req, {
+                required_permissions: ['metrics.manage'],
+                scope_id: scope_id || undefined,
+                getAuth,
+            });
+            if (!gate.ok)
+                return gate.response;
+            let body;
+            try {
+                body = (await req.json());
+            }
+            catch {
+                return jsonError('BAD_REQUEST', 'Invalid JSON body', 400);
+            }
+            const { key, scope_id: bodyScopeId } = body;
+            const resolvedScopeId = (bodyScopeId ?? scope_id);
+            if (!key || !resolvedScopeId) {
+                return jsonError('BAD_REQUEST', 'key and scope_id are required', 400);
+            }
+            const adapter = await options.getAdapter();
+            const crud = getExpCrud(adapter);
+            const existing = await crud.findOneBy({ key, scope_id: resolvedScopeId });
+            if (!existing) {
+                return jsonError('NOT_FOUND', `Experiment '${key}' not found in scope '${resolvedScopeId}'`, 404);
+            }
+            await crud.upsert({ ...existing, status: 'running' }, ['key', 'scope_id']);
+            await options.onAudit?.({
+                action: 'experiment.start',
+                actor_id: gate.userId,
+                scope_id: resolvedScopeId,
+                details: { key },
+            });
+            return jsonOk({ key, status: 'running' });
+        },
+        /**
+         * POST /...
+         * Body: { key, scope_id }
+         * Transitions an experiment to 'stopped'. Requires metrics.manage.
+         */
+        async stopExperiment(req) {
+            const url = new URL(req.url);
+            const scope_id = url.searchParams.get('scope_id') ?? '';
+            const gate = await gateAuth(req, {
+                required_permissions: ['metrics.manage'],
+                scope_id: scope_id || undefined,
+                getAuth,
+            });
+            if (!gate.ok)
+                return gate.response;
+            let body;
+            try {
+                body = (await req.json());
+            }
+            catch {
+                return jsonError('BAD_REQUEST', 'Invalid JSON body', 400);
+            }
+            const { key, scope_id: bodyScopeId } = body;
+            const resolvedScopeId = (bodyScopeId ?? scope_id);
+            if (!key || !resolvedScopeId) {
+                return jsonError('BAD_REQUEST', 'key and scope_id are required', 400);
+            }
+            const adapter = await options.getAdapter();
+            const crud = getExpCrud(adapter);
+            const existing = await crud.findOneBy({ key, scope_id: resolvedScopeId });
+            if (!existing) {
+                return jsonError('NOT_FOUND', `Experiment '${key}' not found in scope '${resolvedScopeId}'`, 404);
+            }
+            await crud.upsert({ ...existing, status: 'stopped' }, ['key', 'scope_id']);
+            await options.onAudit?.({
+                action: 'experiment.stop',
+                actor_id: gate.userId,
+                scope_id: resolvedScopeId,
+                details: { key },
+            });
+            return jsonOk({ key, status: 'stopped' });
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// createGa4ConnectHandlers — STUB (M1)
+// ---------------------------------------------------------------------------
+export function createGa4ConnectHandlers(options) {
+    const getAuth = options.getAuth ?? defaultGetAuth;
+    return {
+        /** STUB (M1): Initiate GA4 OAuth connection for a scope. */
+        async connect(req) {
+            const url = new URL(req.url);
+            const scope_id = url.searchParams.get('scope_id') ?? '';
+            const gate = await gateAuth(req, {
+                required_permissions: ['metrics.manage'],
+                scope_id: scope_id || undefined,
+                getAuth,
+            });
+            if (!gate.ok)
+                return gate.response;
+            // STUB (M1)
+            return jsonOk({ status: 'stub' });
+        },
+        /** STUB (M1): Provision a GA4 property for a scope. */
+        async provision(req) {
+            const url = new URL(req.url);
+            const scope_id = url.searchParams.get('scope_id') ?? '';
+            const gate = await gateAuth(req, {
+                required_permissions: ['metrics.manage'],
+                scope_id: scope_id || undefined,
+                getAuth,
+            });
+            if (!gate.ok)
+                return gate.response;
+            // STUB (M1)
+            return jsonOk({ status: 'stub' });
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// createQueryHandlers — STUB (M1)
+// ---------------------------------------------------------------------------
+export function createQueryHandlers(options) {
+    const getAuth = options.getAuth ?? defaultGetAuth;
+    return {
+        /** STUB (M1): Execute a GA4 or stat-store query. */
+        async query(req) {
+            const url = new URL(req.url);
+            const scope_id = url.searchParams.get('scope_id') ?? '';
+            const gate = await gateAuth(req, {
+                required_permissions: ['metrics.view'],
+                scope_id: scope_id || undefined,
+                getAuth,
+            });
+            if (!gate.ok)
+                return gate.response;
+            // STUB (M1)
+            return jsonOk([]);
+        },
+    };
+}

package/dist/index.client.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+interface MetricsContextValue {
+    scopeId: string | null | undefined;
+    identify: (userId: string) => void;
+    recordStat: (key: string, value: number, opts?: {
+        unit?: string;
+    }) => void;
+    track: (event: string, props?: Record<string, unknown>) => void;
+}
+export interface HazoMetricsProviderProps {
+    scopeId?: string;
+    children: React.ReactNode;
+}
+export declare function HazoMetricsProvider({ scopeId, children }: HazoMetricsProviderProps): React.FunctionComponentElement<React.ProviderProps<MetricsContextValue>>;
+export declare function useMetrics(): MetricsContextValue;
+export declare function getVariant(serverVariant: string): string;
+export declare function isEnabled(serverVariant: string): boolean;
+export declare function identify(_userId: string): void;
+export declare function recordStat(_key: string, _value: number, _opts?: {
+    unit?: string;
+}): void;
+export {};
+//# sourceMappingURL=index.client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.client.d.ts","sourceRoot":"","sources":["../src/index.client.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,MAAM,OAAO,CAAC;AAM1B,UAAU,mBAAmB;IAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACnC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC3E,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CACjE;AASD,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED,wBAAgB,mBAAmB,CAAC,EAAE,OAAmB,EAAE,QAAQ,EAAE,EAAE,wBAAwB,4EAW9F;AAMD,wBAAgB,UAAU,IAAI,mBAAmB,CAEhD;AAGD,wBAAgB,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAExD;AAGD,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAExF"}

package/dist/index.client.js

@@ -0,0 +1,44 @@
+// hazo_umetrics/src/index.client.ts — Client-safe entry point.
+// Never import Node.js builtins (fs/path/crypto) from this file.
+// Never import hazo_auth/server-lib or other server-only modules.
+// Full hook wiring is M1 — these are thin client shells.
+'use client';
+import React from 'react';
+const MetricsContext = React.createContext({
+    scopeId: null,
+    identify: () => { },
+    recordStat: () => { },
+    track: () => { },
+});
+export function HazoMetricsProvider({ scopeId = undefined, children }) {
+    const identify = React.useCallback((_userId) => {
+        // M1: send to /api/hazo_umetrics/identify
+    }, []);
+    const recordStat = React.useCallback((_key, _value, _opts) => {
+        // M1: send to /api/hazo_umetrics/stats
+    }, []);
+    const track = React.useCallback((_event, _props) => {
+        // M1: send to /api/hazo_umetrics/events
+    }, []);
+    return React.createElement(MetricsContext.Provider, { value: { scopeId, identify, recordStat, track } }, children);
+}
+// ---------------------------------------------------------------------------
+// Hooks
+// ---------------------------------------------------------------------------
+export function useMetrics() {
+    return React.useContext(MetricsContext);
+}
+// Hydrate a variant from a server-resolved decision (passed via props/cookie)
+export function getVariant(serverVariant) {
+    return serverVariant;
+}
+export function isEnabled(serverVariant) {
+    return serverVariant === 'on';
+}
+// Re-export identify + track as standalone functions for RSC/non-hook contexts
+export function identify(_userId) {
+    // M1: client-side identify via API
+}
+export function recordStat(_key, _value, _opts) {
+    // M1: client-side stat record via API
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+// hazo_umetrics/src/index.ts — Server entry point (no client imports)
+// Use 'hazo_umetrics/api' for HTTP route factories.
+// Use 'hazo_umetrics/client' for client-safe hooks/components.
+// Use 'hazo_umetrics/ui' for React UI components.
+export * from './lib/index.js';

package/dist/lib/index.d.ts

@@ -0,0 +1,7 @@
+export * from '../server/types.js';
+export * from '../server/stats.js';
+export * from '../server/flags.js';
+export * from '../server/cookie.js';
+export * from '../server/ga4.js';
+export * from '../server/experiments.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC"}

package/dist/lib/index.js

@@ -0,0 +1,7 @@
+// hazo_umetrics/src/lib/index.ts — re-exports server-side modules
+export * from '../server/types.js';
+export * from '../server/stats.js';
+export * from '../server/flags.js';
+export * from '../server/cookie.js';
+export * from '../server/ga4.js';
+export * from '../server/experiments.js';

package/dist/server/cookie.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Encrypt a subjectId into a cookie value string (JSON.stringify of EncryptedField).
+ */
+export declare function signSubjectCookie(subjectId: string): Promise<string>;
+/**
+ * Decrypt a cookie value → subjectId, or null on tamper / missing key / parse error.
+ */
+export declare function readSubjectCookie(value: string): Promise<string | null>;
+//# sourceMappingURL=cookie.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cookie.d.ts","sourceRoot":"","sources":["../../src/server/cookie.ts"],"names":[],"mappings":"AAiBA;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1E;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQ7E"}

package/dist/server/cookie.js

@@ -0,0 +1,32 @@
+// hazo_umetrics/src/server/cookie.ts — sign/verify the A/B assignment cookie
+// via hazo_secure/crypto (AES-256-GCM).
+//
+// Env vars required:
+//   HAZO_UMETRICS_COOKIE_KEY_CURRENT  — key id, e.g. "v1"
+//   HAZO_UMETRICS_COOKIE_KEY_v1       — base64-encoded 32-byte AES-256 key
+//
+// EnvKeyProvider reads lazily on first call, so setting env vars in beforeAll
+// in tests is sufficient.
+import { encryptField, decryptField, EnvKeyProvider } from 'hazo_secure/crypto';
+const cookieKeys = new EnvKeyProvider('HAZO_UMETRICS_COOKIE_KEY');
+const COOKIE_AAD = 'umetrics_assignment';
+/**
+ * Encrypt a subjectId into a cookie value string (JSON.stringify of EncryptedField).
+ */
+export async function signSubjectCookie(subjectId) {
+    const encrypted = await encryptField(subjectId, { keys: cookieKeys, aad: COOKIE_AAD });
+    return JSON.stringify(encrypted);
+}
+/**
+ * Decrypt a cookie value → subjectId, or null on tamper / missing key / parse error.
+ */
+export async function readSubjectCookie(value) {
+    try {
+        const field = JSON.parse(value);
+        const subjectId = await decryptField(field, { keys: cookieKeys, aad: COOKIE_AAD });
+        return subjectId;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/server/experiments.d.ts

@@ -0,0 +1,30 @@
+export interface SignificanceResult {
+    pValue: number;
+    confidenceInterval: [number, number];
+    significant: boolean;
+    sampleSize: number;
+    power: number;
+}
+export interface SignificanceParams {
+    control: {
+        conversions: number;
+        visitors: number;
+    };
+    variant: {
+        conversions: number;
+        visitors: number;
+    };
+    alpha?: number;
+}
+export declare function computeSignificance(_params: SignificanceParams): SignificanceResult;
+export interface SampleSizeEstimate {
+    requiredPerVariant: number;
+    estimatedDaysToComplete: number | null;
+}
+export declare function estimateSampleSize(_params: {
+    baselineRate: number;
+    minimumDetectableEffect: number;
+    alpha?: number;
+    power?: number;
+}): SampleSizeEstimate;
+//# sourceMappingURL=experiments.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"experiments.d.ts","sourceRoot":"","sources":["../../src/server/experiments.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,OAAO,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAGD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,kBAAkB,GAAG,kBAAkB,CAQnF;AAED,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAGD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,uBAAuB,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,kBAAkB,CAEzJ"}

package/dist/server/experiments.js

@@ -0,0 +1,17 @@
+// hazo_umetrics/src/server/experiments.ts — Experiment significance stubs.
+// STUB: z-test / confidence interval / low-traffic estimator deferred to M2+.
+// Re-exports the flag engine functions for the experiment layer.
+// STUB (M2/deferred) — returns a placeholder result
+export function computeSignificance(_params) {
+    return {
+        pValue: 1,
+        confidenceInterval: [0, 1],
+        significant: false,
+        sampleSize: 0,
+        power: 0,
+    };
+}
+// STUB (M2/deferred)
+export function estimateSampleSize(_params) {
+    return { requiredPerVariant: 0, estimatedDaysToComplete: null }; // STUB
+}

package/dist/server/flags.d.ts

@@ -0,0 +1,44 @@
+import type { HazoConnectAdapter } from 'hazo_connect/server';
+type Variant = {
+    name: string;
+    weight: number;
+};
+/**
+ * Given a list of variants with weights, deterministically assign a bucket
+ * using the hashInput string. Weights are normalized to sum to 100.
+ *
+ * Throws HazoError if variants is empty.
+ */
+export declare function weightedBucket(variants: Variant[], hashInput: string): string;
+export interface ResolveVariantOpts {
+    experimentKey: string;
+    scope_id: string;
+    subjectId?: string;
+    consent?: boolean;
+    /** Pass a signed cookie value from a previous call to restore anon identity. */
+    cookieValue?: string;
+}
+export interface ResolveVariantResult {
+    variant: string;
+    sticky: boolean;
+    cookieValue?: string;
+}
+/**
+ * Resolve the variant for a subject in an experiment.
+ *
+ * - draft/stopped experiment → first variant (or 'control'), no DB writes
+ * - running + subjectId (logged-in) → deterministic bucket, upsert assignment, write exposure
+ * - running + no subjectId + consent=true → ephemeral anon ID signed in cookie, sticky
+ * - running + no subjectId + consent=false/undefined → per-request bucket, no persistence
+ */
+export declare function resolveVariant(adapter: HazoConnectAdapter, opts: ResolveVariantOpts): Promise<ResolveVariantResult>;
+/**
+ * Resolve the variant name for a subject. Wraps resolveVariant.
+ */
+export declare function getVariant(adapter: HazoConnectAdapter, opts: ResolveVariantOpts): Promise<string>;
+/**
+ * Returns true when the resolved variant is 'on'. Useful for simple feature flags.
+ */
+export declare function isEnabled(adapter: HazoConnectAdapter, opts: ResolveVariantOpts): Promise<boolean>;
+export {};
+//# sourceMappingURL=flags.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../../src/server/flags.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAwB9D,KAAK,OAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CA2B7E;AA4CD,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,oBAAoB,CAAC,CAyI/B;AAkBD;;GAEG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;GAEG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,OAAO,CAAC,CAElB"}