@mongrov/analytics 0.1.0-alpha.1 → 0.1.0-alpha.10

package/dist/core/hooks.js

@@ -1,23 +1,145 @@
-import { NotImplementedError } from './errors';
 /**
- * React hooks over the analytics engine. Stubs in T-02; real wiring via
- * `useSyncExternalStore` on `engine.subscribe()` lands in Phase 5 (T-11/12/13).
+ * React hooks over the analytics engine.
  *
- * React is an optional peer, so these stubs deliberately do not import
- * React — they simply throw NotImplementedError. This keeps @mongrov/analytics
- * consumable from non-React runtimes (Node CLI, background workers) until
- * the hooks are actually implemented.
+ * All three hooks resolve the engine via `useAnalyticsEngine()` (context) and
+ * subscribe to state transitions with `useSyncExternalStore`. Query hooks
+ * (`useTimeseries`, `useInsight`) block until the engine is attached; a
+ * detach + re-attach (family switch) refires them via the state subscription.
+ */
+import { useCallback, useEffect, useMemo, useReducer, useRef, useSyncExternalStore } from 'react';
+import { useAnalyticsEngine } from './context';
+/**
+ * Subscribe to the engine's state machine. Re-renders on every transition.
+ * `isReady` is true from `ready` onward (engine opened); `isAttached` is true
+ * only in the `attached` state.
  */
-// T-11 — public shape per analytics-core/spec.md §Hooks
 export function useAnalytics() {
-    throw new NotImplementedError('useAnalytics');
+    const engine = useAnalyticsEngine();
+    const state = useEngineState(engine);
+    return {
+        state,
+        isReady: state !== 'idle' && state !== 'opening' && state !== 'error',
+        isAttached: state === 'attached',
+        error: state === 'error' ? engine.lastError : null,
+    };
+}
+function timeseriesReducer(state, action) {
+    switch (action.type) {
+        case 'start':
+            return { ...state, loading: true, error: null };
+        case 'success':
+            return { data: action.data, loading: false, error: null };
+        case 'failure':
+            return { ...state, loading: false, error: action.error };
+        case 'reset':
+            return { data: undefined, loading: false, error: null };
+    }
+}
+/**
+ * Runs `sql` (with `params`) against the engine whenever `key`, `sql`,
+ * `params`, or the engine's attached state changes. `key === undefined`
+ * disables the query (data stays `undefined`).
+ *
+ * `refetch()` re-runs the current query; stale results from prior effects are
+ * discarded via a per-effect abort flag so out-of-order responses never win.
+ */
+export function useTimeseries(key, sql, params) {
+    const engine = useAnalyticsEngine();
+    const state = useEngineState(engine);
+    const attached = state === 'attached';
+    // Stable string key for params so effect deps don't retrigger on new refs.
+    const paramsKey = useMemo(() => (params ? stableJson(params) : ''), [params]);
+    const [store, dispatch] = useReducer(timeseriesReducer, { data: undefined, loading: false, error: null });
+    // Keep the latest params ref so refetch uses fresh values without re-arming
+    // the effect (params object identity changes on every render).
+    const latestParamsRef = useRef(params);
+    latestParamsRef.current = params;
+    const runQuery = useCallback(async (abortRef) => {
+        dispatch({ type: 'start' });
+        try {
+            const rows = await engine.execute(sql, latestParamsRef.current);
+            if (abortRef.aborted)
+                return;
+            dispatch({ type: 'success', data: rows });
+        }
+        catch (cause) {
+            if (abortRef.aborted)
+                return;
+            dispatch({
+                type: 'failure',
+                error: cause instanceof Error ? cause : new Error(String(cause)),
+            });
+        }
+    }, [engine, sql]);
+    // Track the currently active abort ref so `refetch()` can invalidate the
+    // background effect run without waiting for the deps to change.
+    const activeAbortRef = useRef(null);
+    useEffect(() => {
+        if (key === undefined) {
+            dispatch({ type: 'reset' });
+            return;
+        }
+        if (!attached) {
+            // Waiting for engine to attach; leave `data` as-is and don't set loading.
+            return;
+        }
+        const abortRef = { aborted: false };
+        activeAbortRef.current = abortRef;
+        void runQuery(abortRef);
+        return () => {
+            abortRef.aborted = true;
+            if (activeAbortRef.current === abortRef) {
+                activeAbortRef.current = null;
+            }
+        };
+        // paramsKey is a stable stringified marker; sql + key + attached round out deps.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key, sql, paramsKey, attached, runQuery]);
+    const refetch = useCallback(async () => {
+        if (key === undefined || !attached)
+            return;
+        // Cancel any in-flight query so its result can't overwrite ours.
+        if (activeAbortRef.current) {
+            activeAbortRef.current.aborted = true;
+        }
+        const abortRef = { aborted: false };
+        activeAbortRef.current = abortRef;
+        await runQuery(abortRef);
+    }, [key, attached, runQuery]);
+    return { data: store.data, loading: store.loading, error: store.error, refetch };
+}
+/**
+ * Reads a single insight row by id. Returns `undefined` if the engine is not
+ * attached or the row does not exist.
+ */
+export function useInsight(id) {
+    const engine = useAnalyticsEngine();
+    const catalog = engine.catalog;
+    const sql = catalog
+        ? `SELECT * FROM ${catalog}.insight WHERE id = $id LIMIT 1`
+        : '';
+    const params = useMemo(() => ({ id }), [id]);
+    const { data, loading } = useTimeseries(catalog ? id : undefined, sql, params);
+    return {
+        insight: data?.[0],
+        loading,
+    };
 }
-// T-12 — public shape per analytics-core/spec.md §Hooks
-export function useTimeseries(_key, _sql, _params) {
-    throw new NotImplementedError('useTimeseries');
+// -------------------- internal --------------------
+/** `useSyncExternalStore` bound to the engine's subscribe surface. */
+function useEngineState(engine) {
+    return useSyncExternalStore(useCallback((onStoreChange) => engine.subscribe(onStoreChange), [engine]), useCallback(() => engine.state, [engine]), useCallback(() => engine.state, [engine]));
 }
-// T-13 — public shape per analytics-core/spec.md §Hooks
-export function useInsight(_id) {
-    throw new NotImplementedError('useInsight');
+/**
+ * Deterministic JSON for effect-dep keys. Object.keys() order is
+ * insertion-defined in modern engines; we sort to be safe when apps compute
+ * params objects with varying key order.
+ */
+function stableJson(value) {
+    const keys = Object.keys(value).sort();
+    const out = {};
+    for (const k of keys)
+        out[k] = value[k];
+    return JSON.stringify(out);
 }
 //# sourceMappingURL=hooks.js.map

package/dist/core/hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/core/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAG9C;;;;;;;;GAQG;AAEH,wDAAwD;AACxD,MAAM,UAAU,YAAY;IAM1B,MAAM,IAAI,mBAAmB,CAAC,cAAc,CAAC,CAAA;AAC/C,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,aAAa,CAC3B,IAAwB,EACxB,IAAY,EACZ,OAAiC;IAOjC,MAAM,IAAI,mBAAmB,CAAC,eAAe,CAAC,CAAA;AAChD,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,UAAU,CAAC,GAAW;IAIpC,MAAM,IAAI,mBAAmB,CAAC,YAAY,CAAC,CAAA;AAC7C,CAAC"}
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/core/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAA;AAEjG,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAY9C;;;;GAIG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAA;IACnC,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,CAAC,CAAA;IACpC,OAAO;QACL,KAAK;QACL,OAAO,EAAE,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,OAAO;QACrE,UAAU,EAAE,KAAK,KAAK,UAAU;QAChC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;KACnD,CAAA;AACH,CAAC;AAuBD,SAAS,iBAAiB,CACxB,KAAyB,EACzB,MAA2B;IAE3B,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,OAAO;YACV,OAAO,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;QACjD,KAAK,SAAS;YACZ,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;QAC3D,KAAK,SAAS;YACZ,OAAO,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAA;QAC1D,KAAK,OAAO;YACV,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;IAC3D,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAuB,EACvB,GAAW,EACX,MAAgC;IAEhC,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAA;IACnC,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,CAAC,CAAA;IACpC,MAAM,QAAQ,GAAG,KAAK,KAAK,UAAU,CAAA;IAErC,2EAA2E;IAC3E,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAA;IAE7E,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,UAAU,CAClC,iBAGuB,EACvB,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAwB,CACvE,CAAA;IAED,4EAA4E;IAC5E,+DAA+D;IAC/D,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,CAAA;IACtC,eAAe,CAAC,OAAO,GAAG,MAAM,CAAA;IAEhC,MAAM,QAAQ,GAAG,WAAW,CAC1B,KAAK,EAAE,QAA8B,EAAiB,EAAE;QACtD,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAA;QAC3B,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,CAAI,GAAG,EAAE,eAAe,CAAC,OAAO,CAAC,CAAA;YAClE,IAAI,QAAQ,CAAC,OAAO;gBAAE,OAAM;YAC5B,QAAQ,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;QAC3C,CAAC;QACD,OAAO,KAAK,EAAE,CAAC;YACb,IAAI,QAAQ,CAAC,OAAO;gBAAE,OAAM;YAC5B,QAAQ,CAAC;gBACP,IAAI,EAAE,SAAS;gBACf,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;aACjE,CAAC,CAAA;QACJ,CAAC;IACH,CAAC,EACD,CAAC,MAAM,EAAE,GAAG,CAAC,CACd,CAAA;IAED,yEAAyE;IACzE,gEAAgE;IAChE,MAAM,cAAc,GAAG,MAAM,CAA8B,IAAI,CAAC,CAAA;IAEhE,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAA;YAC3B,OAAM;QACR,CAAC;QACD,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,0EAA0E;YAC1E,OAAM;QACR,CAAC;QACD,MAAM,QAAQ,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;QACnC,cAAc,CAAC,OAAO,GAAG,QAAQ,CAAA;QACjC,KAAK,QAAQ,CAAC,QAAQ,CAAC,CAAA;QACvB,OAAO,GAAG,EAAE;YACV,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAA;YACvB,IAAI,cAAc,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;gBACxC,cAAc,CAAC,OAAO,GAAG,IAAI,CAAA;YAC/B,CAAC;QACH,CAAC,CAAA;QACD,iFAAiF;QACjF,uDAAuD;IACzD,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAA;IAE7C,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,IAAmB,EAAE;QACpD,IAAI,GAAG,KAAK,SAAS,IAAI,CAAC,QAAQ;YAAE,OAAM;QAC1C,iEAAiE;QACjE,IAAI,cAAc,CAAC,OAAO,EAAE,CAAC;YAC3B,cAAc,CAAC,OAAO,CAAC,OAAO,GAAG,IAAI,CAAA;QACvC,CAAC;QACD,MAAM,QAAQ,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;QACnC,cAAc,CAAC,OAAO,GAAG,QAAQ,CAAA;QACjC,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAA;IAC1B,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAA;IAE7B,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,CAAA;AAClF,CAAC;AASD;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,EAAU;IACnC,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAA;IACnC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAA;IAC9B,MAAM,GAAG,GAAG,OAAO;QACjB,CAAC,CAAC,iBAAiB,OAAO,iCAAiC;QAC3D,CAAC,CAAC,EAAE,CAAA;IACN,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IAC5C,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,aAAa,CACrC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,EACxB,GAAG,EACH,MAAM,CACP,CAAA;IACD,OAAO;QACL,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAClB,OAAO;KACR,CAAA;AACH,CAAC;AAED,qDAAqD;AAErD,sEAAsE;AACtE,SAAS,cAAc,CAAC,MAAuB;IAC7C,OAAO,oBAAoB,CACzB,WAAW,CACT,CAAC,aAAa,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,aAAa,CAAC,EAClD,CAAC,MAAM,CAAC,CACT,EACD,WAAW,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,CAAC,EACzC,WAAW,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,CAAC,CAC1C,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAC,KAA8B;IAChD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAA;IACtC,MAAM,GAAG,GAA4B,EAAE,CAAA;IACvC,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;IACvC,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAA;AAC5B,CAAC"}

package/dist/core/index.d.ts

@@ -6,6 +6,9 @@
  */
 export { createAnalytics } from './factory';
 export { useAnalytics, useInsight, useTimeseries } from './hooks';
+export type { UseAnalyticsResult, UseInsightResult, UseTimeseriesResult, } from './hooks';
+export { AnalyticsProvider } from './context';
+export type { AnalyticsProviderProps } from './context';
 export { AnalyticsError, NotImplementedError } from './errors';
 export type { AnalyticsErrorCode } from './errors';
 export type { AnalyticsAppender, AnalyticsConfig, AnalyticsEngine, AnalyticsLogger, AnalyticsState, AttachContext, EventBus, FamilyMembersProvider, Insight, KVStore, TenantScope, TokenContext, TokenResponse, TokenVendor, Unsubscribe, } from './types';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAG3C,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAGjE,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC9D,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAGlD,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,aAAa,EACb,QAAQ,EACR,qBAAqB,EACrB,OAAO,EACP,OAAO,EACP,WAAW,EACX,YAAY,EACZ,aAAa,EACb,WAAW,EACX,WAAW,GACZ,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAG3C,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AACjE,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAC7C,YAAY,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AAGvD,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC9D,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAGlD,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,aAAa,EACb,QAAQ,EACR,qBAAqB,EACrB,OAAO,EACP,OAAO,EACP,WAAW,EACX,YAAY,EACZ,aAAa,EACb,WAAW,EACX,WAAW,GACZ,MAAM,SAAS,CAAA"}

package/dist/core/index.js

@@ -6,8 +6,10 @@
  */
 // Factory (T-02 stub → T-10 real)
 export { createAnalytics } from './factory';
-// Hooks (T-02 stubs → T-11/12/13 real)
+// Hooks (T-11/12/13)
 export { useAnalytics, useInsight, useTimeseries } from './hooks';
+// Provider (Phase 5)
+export { AnalyticsProvider } from './context';
 // Errors
 export { AnalyticsError, NotImplementedError } from './errors';
 //# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,kCAAkC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAE3C,uCAAuC;AACvC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAEjE,SAAS;AACT,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,kCAAkC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAE3C,qBAAqB;AACrB,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAOjE,qBAAqB;AACrB,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAG7C,SAAS;AACT,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA"}

package/dist/core/logger.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Structured logger plumbing for @mongrov/analytics.
+ *
+ * Apps supply an `AnalyticsLogger` via `AnalyticsConfig.logger`. When absent
+ * we fall back to a no-op sink so callers can `log.debug(...)` unconditionally
+ * without null-checks. The library only emits at these levels:
+ *
+ *   - **debug** — state transitions (hot on attach/detach churn; app can drop)
+ *   - **info**  — lifecycle milestones (attached, detached, closed)
+ *   - **warn**  — best-effort operations that failed but didn't reject the caller
+ *                (retention sweep miss, last-attach persist miss, KV eviction)
+ *   - **error** — reserved for callers who want to surface an
+ *                 `AnalyticsError` before re-throwing (not used by the library
+ *                 today — errors bubble via `throw`)
+ *
+ * No logs on the hot query path (`execute`, `stream`, `createAppender`) per
+ * T-17 AC — apps can enable debug tracing at their integration layer if
+ * needed.
+ */
+import type { AnalyticsLogger } from './types';
+/** No-op logger — used when `AnalyticsConfig.logger` is absent. */
+export declare function noopLogger(): AnalyticsLogger;
+/** Resolve the effective logger — provided or no-op. */
+export declare function resolveLogger(provided: AnalyticsLogger | undefined): AnalyticsLogger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/core/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,mEAAmE;AACnE,wBAAgB,UAAU,IAAI,eAAe,CAO5C;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,GAAG,SAAS,GAAG,eAAe,CAEpF"}

package/dist/core/logger.js

@@ -0,0 +1,33 @@
+/**
+ * Structured logger plumbing for @mongrov/analytics.
+ *
+ * Apps supply an `AnalyticsLogger` via `AnalyticsConfig.logger`. When absent
+ * we fall back to a no-op sink so callers can `log.debug(...)` unconditionally
+ * without null-checks. The library only emits at these levels:
+ *
+ *   - **debug** — state transitions (hot on attach/detach churn; app can drop)
+ *   - **info**  — lifecycle milestones (attached, detached, closed)
+ *   - **warn**  — best-effort operations that failed but didn't reject the caller
+ *                (retention sweep miss, last-attach persist miss, KV eviction)
+ *   - **error** — reserved for callers who want to surface an
+ *                 `AnalyticsError` before re-throwing (not used by the library
+ *                 today — errors bubble via `throw`)
+ *
+ * No logs on the hot query path (`execute`, `stream`, `createAppender`) per
+ * T-17 AC — apps can enable debug tracing at their integration layer if
+ * needed.
+ */
+/** No-op logger — used when `AnalyticsConfig.logger` is absent. */
+export function noopLogger() {
+    return {
+        debug() { },
+        info() { },
+        warn() { },
+        error() { },
+    };
+}
+/** Resolve the effective logger — provided or no-op. */
+export function resolveLogger(provided) {
+    return provided ?? noopLogger();
+}
+//# sourceMappingURL=logger.js.map

package/dist/core/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,mEAAmE;AACnE,MAAM,UAAU,UAAU;IACxB,OAAO;QACL,KAAK,KAAI,CAAC;QACV,IAAI,KAAI,CAAC;QACT,IAAI,KAAI,CAAC;QACT,KAAK,KAAI,CAAC;KACX,CAAA;AACH,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,aAAa,CAAC,QAAqC;IACjE,OAAO,QAAQ,IAAI,UAAU,EAAE,CAAA;AACjC,CAAC"}

package/dist/core/machine.d.ts

@@ -0,0 +1,174 @@
+/**
+ * XState v5 state machine that drives the analytics engine lifecycle.
+ *
+ * `idle → opening → ready → attaching → attached → detaching → error`
+ *
+ * The machine owns lifecycle transitions only; side effects live in injected
+ * actors (`openEngine`, `attachEngine`, `detachEngine`, `refreshToken`) so
+ * tests can substitute fakes without a real DuckDB.
+ *
+ * Token refresh runs silently on `attached` via a delayed self-transition
+ * to `refreshing`, computed as 75% of the remaining TTL (spec §Token
+ * refresh policy). Refresh success re-enters `attached` and re-arms the
+ * timer; failure lands in `error`.
+ *
+ * Consumers (T-10 factory + T-11 hook) drive the machine via `send` and
+ * observe via `subscribe`.
+ */
+import { AnalyticsError } from './errors';
+import type { AttachContext } from './types';
+/**
+ * Compute the delay before firing `TOKEN_REFRESH_TICK`. Spec calls for 75%
+ * TTL. Falls back to a 30-minute default when the vendor's `expiresAt` is
+ * missing or already in the past — the refresh will fail loudly rather than
+ * silently skipping.
+ */
+export declare function computeRefreshDelay(now: number, expiresAt: number | undefined): number;
+export interface AttachSuccess {
+    warehouseSecret: string;
+    tokenExpiresAt: number;
+}
+export interface RefreshSuccess {
+    tokenExpiresAt: number;
+}
+/**
+ * Actors are injected by the factory (T-10). Each returns a promise the
+ * machine invokes on entry to the relevant state.
+ */
+export interface MachineActors {
+    openEngine: () => Promise<void>;
+    attachEngine: (input: {
+        ctx: AttachContext;
+    }) => Promise<AttachSuccess>;
+    detachEngine: (input: {
+        ctx: AttachContext;
+    }) => Promise<void>;
+    refreshToken: (input: {
+        ctx: AttachContext;
+    }) => Promise<RefreshSuccess>;
+}
+export interface MachineContext {
+    deps: MachineActors;
+    ctx: AttachContext | undefined;
+    tokenExpiresAt: number | undefined;
+    warehouseSecret: string | undefined;
+    lastError: AnalyticsError | undefined;
+}
+export type MachineEvent = {
+    type: 'OPEN';
+} | {
+    type: 'ATTACH';
+    ctx: AttachContext;
+} | {
+    type: 'DETACH';
+} | {
+    type: 'CLOSE';
+} | {
+    type: 'TOKEN_REFRESH_TICK';
+};
+export interface MachineInput {
+    deps: MachineActors;
+}
+export type MachineState = 'idle' | 'opening' | 'ready' | 'attaching' | 'attached' | 'refreshing' | 'detaching' | 'error';
+export declare const analyticsMachine: import("xstate").StateMachine<MachineContext, {
+    type: "OPEN";
+} | {
+    type: "ATTACH";
+    ctx: AttachContext;
+} | {
+    type: "DETACH";
+} | {
+    type: "CLOSE";
+} | {
+    type: "TOKEN_REFRESH_TICK";
+}, {
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<void, {
+        deps: MachineActors;
+    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<AttachSuccess, {
+        deps: MachineActors;
+        ctx: AttachContext;
+    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<void, {
+        deps: MachineActors;
+        ctx: AttachContext;
+    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<RefreshSuccess, {
+        deps: MachineActors;
+        ctx: AttachContext;
+    }, import("xstate").EventObject>> | undefined;
+}, {
+    src: "openEngine";
+    logic: import("xstate").PromiseActorLogic<void, {
+        deps: MachineActors;
+    }, import("xstate").EventObject>;
+    id: string | undefined;
+} | {
+    src: "attachEngine";
+    logic: import("xstate").PromiseActorLogic<AttachSuccess, {
+        deps: MachineActors;
+        ctx: AttachContext;
+    }, import("xstate").EventObject>;
+    id: string | undefined;
+} | {
+    src: "detachEngine";
+    logic: import("xstate").PromiseActorLogic<void, {
+        deps: MachineActors;
+        ctx: AttachContext;
+    }, import("xstate").EventObject>;
+    id: string | undefined;
+} | {
+    src: "refreshToken";
+    logic: import("xstate").PromiseActorLogic<RefreshSuccess, {
+        deps: MachineActors;
+        ctx: AttachContext;
+    }, import("xstate").EventObject>;
+    id: string | undefined;
+}, {
+    type: "assignAttachCtx";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "assignAttachSuccess";
+    params: {
+        output: AttachSuccess;
+    };
+} | {
+    type: "assignRefreshSuccess";
+    params: {
+        output: RefreshSuccess;
+    };
+} | {
+    type: "assignOpenError";
+    params: {
+        error: unknown;
+    };
+} | {
+    type: "assignAttachError";
+    params: {
+        error: unknown;
+    };
+} | {
+    type: "assignRefreshError";
+    params: {
+        error: unknown;
+    };
+} | {
+    type: "clearError";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "clearAttachState";
+    params: import("xstate").NonReducibleUnknown;
+}, {
+    type: "hasAttachCtx";
+    params: unknown;
+}, "tokenRefresh", "idle" | "opening" | "ready" | "attaching" | "attached" | "detaching" | "error" | "refreshing", string, MachineInput, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject, {
+    id: "analytics";
+    states: {
+        readonly idle: {};
+        readonly opening: {};
+        readonly ready: {};
+        readonly attaching: {};
+        readonly attached: {};
+        readonly refreshing: {};
+        readonly detaching: {};
+        readonly error: {};
+    };
+}>;
+//# sourceMappingURL=machine.d.ts.map

package/dist/core/machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../../src/core/machine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAI5C;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAMtF;AAID,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE,MAAM,CAAA;IACvB,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,cAAc,EAAE,MAAM,CAAA;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/B,YAAY,EAAE,CAAC,KAAK,EAAE;QAAE,GAAG,EAAE,aAAa,CAAA;KAAE,KAAK,OAAO,CAAC,aAAa,CAAC,CAAA;IACvE,YAAY,EAAE,CAAC,KAAK,EAAE;QAAE,GAAG,EAAE,aAAa,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9D,YAAY,EAAE,CAAC,KAAK,EAAE;QAAE,GAAG,EAAE,aAAa,CAAA;KAAE,KAAK,OAAO,CAAC,cAAc,CAAC,CAAA;CACzE;AAID,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,aAAa,CAAA;IACnB,GAAG,EAAE,aAAa,GAAG,SAAS,CAAA;IAC9B,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,SAAS,EAAE,cAAc,GAAG,SAAS,CAAA;CACtC;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,aAAa,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,oBAAoB,CAAA;CAAE,CAAA;AAElC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,aAAa,CAAA;CACpB;AAED,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,SAAS,GACT,OAAO,GACP,WAAW,GACX,UAAU,GACV,YAAY,GACZ,WAAW,GACX,OAAO,CAAA;AAgBX,eAAO,MAAM,gBAAgB;UAlCjB,MAAM;;UACN,QAAQ;SAAO,aAAa;;UAC5B,QAAQ;;UACR,OAAO;;UACP,oBAAoB;;;cAqCU,aAAa;;cAGF,aAAa;aAAO,aAAa;;cAG1C,aAAa;aAAO,aAAa;;cAKvB,aAAa;aAAO,aAAa;;;;;cAX7C,aAAa;;;;;;cAGF,aAAa;aAAO,aAAa;;;;;;cAG1C,aAAa;aAAO,aAAa;;;;;;cAKvB,aAAa;aAAO,aAAa;;;;;;;;;gBASjC,aAAa;;;;;gBAKZ,cAAc;;;;;eAIpB,OAAO;;;;;eAGL,OAAO;;;;;eAGN,OAAO;;;;;;;;;;;;;;;;;;;;;;;EAoJzD,CAAA"}