@inventbuild/supamachine 0.3.0

package/dist/core/runtime.js

@@ -0,0 +1,177 @@
+import { AuthEventType, AuthStateStatus } from "./constants";
+import { reducer, setReducerLogLevel } from "./reducer";
+import { createLogger } from "./logger";
+const DEFAULT_LOAD_CONTEXT_TIMEOUT_MS = 10000;
+const DEFAULT_INITIALIZE_APP_TIMEOUT_MS = 30000;
+const DEFAULT_AUTHENTICATING_TIMEOUT_MS = 30000;
+function computeAppState(state, mapState) {
+    if (state.status !== AuthStateStatus.AUTH_READY) {
+        return state;
+    }
+    if (mapState && state.context != null) {
+        const snapshot = {
+            status: state.status,
+            session: state.session,
+            context: state.context,
+        };
+        const base = mapState(snapshot);
+        return {
+            ...base,
+            session: state.session,
+            context: state.context,
+        };
+    }
+    return state;
+}
+export class SupamachineCore {
+    constructor(options) {
+        var _a, _b, _c, _d;
+        this.options = options;
+        this.state = {
+            status: AuthStateStatus.START,
+            context: null,
+        };
+        this.sessionForLoading = null;
+        this.authenticatingTimer = null;
+        this.listeners = new Set();
+        this.loadContextTimeoutMs =
+            (_a = options.loadContextTimeoutMs) !== null && _a !== void 0 ? _a : DEFAULT_LOAD_CONTEXT_TIMEOUT_MS;
+        this.initializeAppTimeoutMs =
+            (_b = options.initializeAppTimeoutMs) !== null && _b !== void 0 ? _b : DEFAULT_INITIALIZE_APP_TIMEOUT_MS;
+        this.authenticatingTimeoutMs =
+            (_c = options.authenticatingTimeoutMs) !== null && _c !== void 0 ? _c : DEFAULT_AUTHENTICATING_TIMEOUT_MS;
+        const level = (_d = options.logLevel) !== null && _d !== void 0 ? _d : 2;
+        this.log = createLogger("core", level);
+        setReducerLogLevel(level);
+    }
+    setLogLevel(level) {
+        this.log = createLogger("core", level);
+        setReducerLogLevel(level);
+    }
+    async updateContext(updater) {
+        if (this.state.status !== AuthStateStatus.AUTH_READY) {
+            return;
+        }
+        const current = this.state.context;
+        if (current == null) {
+            return;
+        }
+        const next = await updater(current);
+        if (next !== current) {
+            this.state = { ...this.state, context: next };
+            this.emit();
+        }
+    }
+    beginAuth() {
+        this.dispatch({ type: AuthEventType.AUTH_INITIATED });
+    }
+    cancelAuth() {
+        this.dispatch({ type: AuthEventType.AUTH_CANCELLED });
+    }
+    dispatch(event) {
+        var _a;
+        const prevState = this.state;
+        this.state = reducer(this.state, event);
+        if (event.type === AuthEventType.AUTH_CHANGED) {
+            this.sessionForLoading = (_a = event.session) !== null && _a !== void 0 ? _a : null;
+        }
+        this.emit();
+        // AUTHENTICATING timeout management
+        if (this.state.status === AuthStateStatus.AUTHENTICATING &&
+            prevState.status !== AuthStateStatus.AUTHENTICATING) {
+            this.authenticatingTimer = setTimeout(() => {
+                this.log.warn("authenticating timeout — cancelling");
+                this.dispatch({ type: AuthEventType.AUTH_CANCELLED });
+            }, this.authenticatingTimeoutMs);
+        }
+        if (prevState.status === AuthStateStatus.AUTHENTICATING &&
+            this.state.status !== AuthStateStatus.AUTHENTICATING) {
+            if (this.authenticatingTimer) {
+                clearTimeout(this.authenticatingTimer);
+                this.authenticatingTimer = null;
+            }
+        }
+        if (this.state.status === AuthStateStatus.CONTEXT_LOADING &&
+            prevState.status !== AuthStateStatus.CONTEXT_LOADING) {
+            const session = this.sessionForLoading;
+            if (session && this.options.loadContext) {
+                this.log.debug("entered CONTEXT_LOADING, loading context");
+                this.loadContextWithTimeout(session);
+            }
+            else if (session && !this.options.loadContext) {
+                this.log.debug("no loadContext, resolving with empty context");
+                this.dispatch({
+                    type: AuthEventType.CONTEXT_RESOLVED,
+                    context: {},
+                });
+            }
+        }
+        else if (this.state.status === AuthStateStatus.SIGNED_OUT &&
+            prevState.status !== AuthStateStatus.SIGNED_OUT) {
+            this.sessionForLoading = null;
+            this.log.debug("signed out");
+        }
+        else if (this.state.status === AuthStateStatus.INITIALIZING &&
+            prevState.status === AuthStateStatus.CONTEXT_LOADING) {
+            this.log.debug("entered INITIALIZING, running initializeApp");
+            this.initializeAppWithTimeout();
+        }
+    }
+    async loadContextWithTimeout(session) {
+        const loadContext = this.options.loadContext;
+        if (!loadContext)
+            return;
+        const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("loadContext timeout")), this.loadContextTimeoutMs));
+        try {
+            const context = await Promise.race([
+                loadContext(session),
+                timeoutPromise,
+            ]);
+            this.dispatch({
+                type: AuthEventType.CONTEXT_RESOLVED,
+                context,
+            });
+        }
+        catch (error) {
+            this.log.error("loadContext failed", error);
+            this.dispatch({
+                type: AuthEventType.ERROR_CONTEXT,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        }
+    }
+    async initializeAppWithTimeout() {
+        const { initializeApp } = this.options;
+        if (!initializeApp || this.state.status !== AuthStateStatus.INITIALIZING) {
+            return;
+        }
+        const { session, context } = this.state;
+        const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("initializeApp timeout")), this.initializeAppTimeoutMs));
+        try {
+            await Promise.race([initializeApp({ session, context }), timeoutPromise]);
+            this.dispatch({ type: AuthEventType.INITIALIZED });
+        }
+        catch (error) {
+            this.log.error("initializeApp failed", error);
+            this.dispatch({
+                type: AuthEventType.ERROR_INITIALIZING,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        }
+    }
+    subscribe(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    getSnapshot() {
+        return this.state;
+    }
+    getAppState() {
+        return computeAppState(this.state, this.options.mapState);
+    }
+    emit() {
+        const appState = computeAppState(this.state, this.options.mapState);
+        for (const l of this.listeners)
+            l(this.state, appState);
+    }
+}

package/dist/core/states.d.ts

@@ -0,0 +1,42 @@
+import type { Session } from "@supabase/supabase-js";
+import { AuthStateStatus } from "./constants";
+/** context is always present: null before load, C once loaded */
+export type CoreState<C> = {
+    status: typeof AuthStateStatus.START;
+    context: null;
+} | {
+    status: typeof AuthStateStatus.CHECKING_SESSION;
+    context: null;
+} | {
+    status: typeof AuthStateStatus.AUTHENTICATING;
+    context: null;
+} | {
+    status: typeof AuthStateStatus.ERROR_CHECKING_SESSION;
+    error: Error;
+    context: null;
+} | {
+    status: typeof AuthStateStatus.SIGNED_OUT;
+    context: null;
+} | {
+    status: typeof AuthStateStatus.CONTEXT_LOADING;
+    session: Session;
+    context: null;
+} | {
+    status: typeof AuthStateStatus.ERROR_CONTEXT;
+    error: Error;
+    session: Session;
+    context: null;
+} | {
+    status: typeof AuthStateStatus.INITIALIZING;
+    session: Session;
+    context: C;
+} | {
+    status: typeof AuthStateStatus.ERROR_INITIALIZING;
+    error: Error;
+    session: Session;
+    context: C;
+} | {
+    status: typeof AuthStateStatus.AUTH_READY;
+    session: Session;
+    context: C | null;
+};

package/dist/core/states.js

@@ -0,0 +1 @@
+export {};

package/dist/core/types.d.ts

@@ -0,0 +1,49 @@
+import type { Session } from "@supabase/supabase-js";
+import type { CoreState } from "./states";
+import { AuthStateStatus } from "./constants";
+type DisallowedStatuses = typeof AuthStateStatus.START | typeof AuthStateStatus.CHECKING_SESSION | typeof AuthStateStatus.AUTHENTICATING | typeof AuthStateStatus.ERROR_CHECKING_SESSION | typeof AuthStateStatus.SIGNED_OUT | typeof AuthStateStatus.CONTEXT_LOADING | typeof AuthStateStatus.ERROR_CONTEXT | typeof AuthStateStatus.INITIALIZING | typeof AuthStateStatus.ERROR_INITIALIZING | typeof AuthStateStatus.AUTH_READY;
+type CustomStateConstraint = {
+    status: Exclude<string, DisallowedStatuses>;
+};
+/** mapState is only called when we have context. Custom states inherit guaranteed context. */
+type WithSessionContext<C, T> = T extends {
+    status: string;
+} ? T & {
+    session: Session;
+    context: C;
+} : never;
+/** Snapshot passed to mapState. Context is guaranteed—mapState only runs when we have context to derive from. */
+export type MapStateSnapshot<C> = {
+    status: typeof AuthStateStatus.AUTH_READY;
+    session: Session;
+    context: C;
+};
+/** When D is void (default), returns CoreState. When D is custom states, returns core states | (D with session+context added) */
+export type AppState<C, D = void> = [D] extends [void] ? CoreState<C> : Exclude<CoreState<C>, {
+    status: typeof AuthStateStatus.AUTH_READY;
+}> | WithSessionContext<C, D>;
+/** Default actions provided when none are passed. signOut is always available. */
+export type DefaultActions = {
+    signOut: () => void | Promise<unknown>;
+};
+/** User-provided auth actions (signIn, signOut, etc.). Merged with default signOut. */
+export type SupamachineActions<A = Record<string, never>> = DefaultActions & A;
+export interface SupamachineProviderProps<C, D extends CustomStateConstraint | void = void, A extends Record<string, (...args: any[]) => any> = Record<string, (...args: any[]) => any>> {
+    loadContext?: (session: Session) => Promise<C>;
+    initializeApp?: (snapshot: {
+        session: Session;
+        context: C;
+    }) => void | Promise<void>;
+    mapState?: [D] extends [void] ? never : (snapshot: MapStateSnapshot<C>) => D;
+    /** Auth actions to expose via useSupamachine(). Merged with default signOut. */
+    actions?: A;
+    children: React.ReactNode;
+}
+export type UseSupamachineReturn<C, D extends CustomStateConstraint | void = void, A extends Record<string, (...args: any[]) => any> = Record<string, (...args: any[]) => any>> = {
+    state: AppState<C, D>;
+    updateContext: (updater: (current: C) => C | Promise<C>) => Promise<void>;
+    beginAuth: () => void;
+    cancelAuth: () => void;
+    actions: SupamachineActions<A>;
+};
+export {};

package/dist/core/types.js

@@ -0,0 +1,2 @@
+// API-facing types for Supamachine
+export {};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { SupamachineProvider, useSupamachine, } from "./react/SupamachineProvider";
+export type { SupamachineOptions } from "./react/SupamachineProvider";
+export { AuthStateStatus } from "./core/constants";
+export { LogLevel } from "./core/logger";
+export type { AppState, DefaultActions, MapStateSnapshot, SupamachineActions, SupamachineProviderProps, UseSupamachineReturn, } from "./core/types";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { SupamachineProvider, useSupamachine, } from "./react/SupamachineProvider";
+export { AuthStateStatus } from "./core/constants";
+export { LogLevel } from "./core/logger";

package/dist/react/SupamachineProvider.d.ts

@@ -0,0 +1,32 @@
+import type { SupabaseClient } from "@supabase/supabase-js";
+import type { SupamachineProviderProps, SupamachineActions } from "../core/types";
+export type SupamachineOptions = {
+    getSessionTimeoutMs?: number;
+    loadContextTimeoutMs?: number;
+    initializeAppTimeoutMs?: number;
+    authenticatingTimeoutMs?: number;
+    /** 'none' | 'error' | 'warn' | 'info' | 'debug'. Default: 'warn'. Uses [Supamachine][subsystem] format. */
+    logLevel?: "none" | "error" | "warn" | "info" | "debug";
+};
+export interface SupamachineProviderPropsWithSupabase<C, D extends {
+    status: string;
+} | void = void, A extends Record<string, (...args: any[]) => any> = Record<string, (...args: any[]) => any>> extends SupamachineProviderProps<C, D, A> {
+    supabase: SupabaseClient;
+}
+export interface SupamachineContextValue<C, D extends {
+    status: string;
+} | void = void, A extends Record<string, (...args: any[]) => any> = Record<string, (...args: any[]) => any>> {
+    state: import("../core/types").AppState<C, D>;
+    updateContext: (updater: (current: C) => C | Promise<C>) => Promise<void>;
+    beginAuth: () => void;
+    cancelAuth: () => void;
+    actions: SupamachineActions<A>;
+}
+export declare function SupamachineProvider<C, D extends {
+    status: string;
+} | void = void, A extends Record<string, (...args: any[]) => any> = Record<string, (...args: any[]) => any>>({ supabase, loadContext, mapState, initializeApp, actions: userActions, children, options: opts, }: SupamachineProviderPropsWithSupabase<C, D, A> & {
+    options?: SupamachineOptions;
+}): import("react/jsx-runtime").JSX.Element | null;
+export declare function useSupamachine<C, D extends {
+    status: string;
+} | void = void, A extends Record<string, (...args: any[]) => any> = Record<string, (...args: any[]) => any>>(): SupamachineContextValue<C, D, A>;

package/dist/react/SupamachineProvider.js

@@ -0,0 +1,78 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { SupamachineCore } from "../core/runtime";
+import { attachSupabase } from "../supabase/adapter";
+import { AuthEventType } from "../core/constants";
+import { parseLogLevel, LogLevel } from "../core/logger";
+const defaultSignOut = (supabase) => () => {
+    void supabase.auth.signOut();
+};
+const SupamachineContext = createContext(null);
+export function SupamachineProvider({ supabase, loadContext, mapState, initializeApp, actions: userActions, children, options: opts = {}, }) {
+    var _a;
+    const coreRef = useRef(null);
+    const unsubAdapterRef = useRef(null);
+    const [contextValue, setContextValue] = useState(null);
+    const actions = useMemo(() => ({
+        signOut: defaultSignOut(supabase),
+        ...userActions,
+    }), [supabase, userActions]);
+    const logLevel = typeof opts.logLevel === "string" ? parseLogLevel(opts.logLevel) : (_a = opts.logLevel) !== null && _a !== void 0 ? _a : LogLevel.WARN;
+    if (!coreRef.current) {
+        coreRef.current = new SupamachineCore({
+            loadContext,
+            mapState,
+            initializeApp,
+            loadContextTimeoutMs: opts.loadContextTimeoutMs,
+            initializeAppTimeoutMs: opts.initializeAppTimeoutMs,
+            authenticatingTimeoutMs: opts.authenticatingTimeoutMs,
+            logLevel,
+        });
+        unsubAdapterRef.current = attachSupabase(coreRef.current, supabase, {
+            getSessionTimeoutMs: opts.getSessionTimeoutMs,
+            logLevel,
+        });
+        coreRef.current.dispatch({ type: AuthEventType.START });
+    }
+    // Stable references — coreRef.current is set once and never changes
+    const updateContext = useCallback((updater) => coreRef.current.updateContext(updater), []);
+    const beginAuth = useCallback(() => coreRef.current.beginAuth(), []);
+    const cancelAuth = useCallback(() => coreRef.current.cancelAuth(), []);
+    if (!contextValue) {
+        setContextValue({
+            state: coreRef.current.getAppState(),
+            updateContext,
+            beginAuth,
+            cancelAuth,
+            actions,
+        });
+    }
+    useEffect(() => {
+        const core = coreRef.current;
+        const unsubscribe = core.subscribe(() => {
+            setContextValue({
+                state: core.getAppState(),
+                updateContext,
+                beginAuth,
+                cancelAuth,
+                actions,
+            });
+        });
+        return () => {
+            var _a;
+            unsubscribe();
+            (_a = unsubAdapterRef.current) === null || _a === void 0 ? void 0 : _a.call(unsubAdapterRef);
+        };
+    }, [actions, updateContext, beginAuth, cancelAuth]);
+    if (!contextValue) {
+        return null;
+    }
+    return (_jsx(SupamachineContext.Provider, { value: contextValue, children: children }));
+}
+export function useSupamachine() {
+    const ctx = useContext(SupamachineContext);
+    if (!ctx) {
+        throw new Error("useSupamachine must be used within SupamachineProvider");
+    }
+    return ctx;
+}

package/dist/react/useSupamachine.d.ts

@@ -0,0 +1 @@
+export { useSupamachine } from './SupamachineProvider';

package/dist/react/useSupamachine.js

@@ -0,0 +1 @@
+export { useSupamachine } from './SupamachineProvider';

package/dist/src/core/constants.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Core machine states. Use these when checking state or in mapState.
+ * Distinct from AuthEventType (event types that drive transitions).
+ */
+export declare const AuthStateStatus: {
+    readonly START: "START";
+    readonly CHECKING: "CHECKING";
+    readonly SIGNED_OUT: "SIGNED_OUT";
+    readonly CONTEXT_LOADING: "CONTEXT_LOADING";
+    readonly INITIALIZING: "INITIALIZING";
+    readonly AUTH_READY: "AUTH_READY";
+    readonly ERROR_CHECKING: "ERROR_CHECKING";
+    readonly ERROR_CONTEXT: "ERROR_CONTEXT";
+    readonly ERROR_INITIALIZING: "ERROR_INITIALIZING";
+};
+export type AuthStateStatus = (typeof AuthStateStatus)[keyof typeof AuthStateStatus];
+/**
+ * Internal event types that drive the state machine.
+ * Mapped from Supabase auth events by the adapter.
+ */
+export declare const AuthEventType: {
+    readonly START: "START";
+    readonly AUTH_RESOLVED: "AUTH_RESOLVED";
+    readonly AUTH_CHANGED: "AUTH_CHANGED";
+    readonly CONTEXT_RESOLVED: "CONTEXT_RESOLVED";
+    readonly INITIALIZED: "INITIALIZED";
+    readonly ERROR_CHECKING: "ERROR_CHECKING";
+    readonly ERROR_CONTEXT: "ERROR_CONTEXT";
+    readonly ERROR_INITIALIZING: "ERROR_INITIALIZING";
+};
+export type AuthEventType = (typeof AuthEventType)[keyof typeof AuthEventType];

package/dist/src/core/events.d.ts

@@ -0,0 +1,25 @@
+import type { Session } from "@supabase/supabase-js";
+import { AuthEventType } from "./constants";
+export type AuthEvent<C> = {
+    type: typeof AuthEventType.START;
+} | {
+    type: typeof AuthEventType.AUTH_RESOLVED;
+    session: Session | null;
+} | {
+    type: typeof AuthEventType.AUTH_CHANGED;
+    session: Session | null;
+} | {
+    type: "CONTEXT_RESOLVED";
+    context: C;
+} | {
+    type: "INITIALIZED";
+} | {
+    type: "ERROR_CHECKING";
+    error: Error;
+} | {
+    type: "ERROR_CONTEXT";
+    error: Error;
+} | {
+    type: "ERROR_INITIALIZING";
+    error: Error;
+};

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

@@ -0,0 +1,15 @@
+export declare const LogLevel: {
+    readonly NONE: 0;
+    readonly ERROR: 1;
+    readonly WARN: 2;
+    readonly INFO: 3;
+    readonly DEBUG: 4;
+};
+export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
+export declare function createLogger(subsystem: string, level: LogLevel): {
+    error: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    debug: (message: string, ...args: unknown[]) => void;
+};
+export declare function parseLogLevel(value: string | undefined): LogLevel;

package/dist/src/core/reducer.d.ts

@@ -0,0 +1,5 @@
+import type { CoreState } from "./states";
+import type { AuthEvent } from "./events";
+import { type LogLevel } from "./logger";
+export declare function setReducerLogLevel(level: LogLevel): void;
+export declare function reducer<C>(state: CoreState<C>, event: AuthEvent<C>): CoreState<C>;

package/dist/src/core/runtime.d.ts

@@ -0,0 +1,39 @@
+import type { Session } from "@supabase/supabase-js";
+import type { CoreState } from "./states";
+import type { AuthEvent } from "./events";
+import { AuthStateStatus } from "./constants";
+import type { AppState } from "./types";
+import { type LogLevel } from "./logger";
+export interface RuntimeOptions<C, D> {
+    loadContext?: (session: Session) => Promise<C>;
+    mapState?: (snapshot: Extract<CoreState<C>, {
+        status: typeof AuthStateStatus.AUTH_READY;
+    }>) => D;
+    initializeApp?: (snapshot: {
+        session: Session;
+        context: C;
+        updateContext: (updater: (current: C) => C | Promise<C>) => Promise<void>;
+    }) => void | Promise<void>;
+    loadContextTimeoutMs?: number;
+    initializeAppTimeoutMs?: number;
+    logLevel?: LogLevel;
+}
+export declare class SupamachineCore<C, D> {
+    private readonly options;
+    private state;
+    private sessionForLoading;
+    private listeners;
+    private loadContextTimeoutMs;
+    private initializeAppTimeoutMs;
+    private log;
+    constructor(options: RuntimeOptions<C, D>);
+    setLogLevel(level: LogLevel): void;
+    updateContext(updater: (current: C) => C | Promise<C>): Promise<void>;
+    dispatch(event: AuthEvent<C>): void;
+    private loadContextWithTimeout;
+    private initializeAppWithTimeout;
+    subscribe(fn: (coreState: CoreState<C>, appState: AppState<C, D>) => void): () => boolean;
+    getSnapshot(): CoreState<C>;
+    getAppState(): AppState<C, D>;
+    private emit;
+}

package/dist/src/core/states.d.ts

@@ -0,0 +1,32 @@
+import type { Session } from "@supabase/supabase-js";
+import { AuthStateStatus } from "./constants";
+export type CoreState<C> = {
+    status: typeof AuthStateStatus.START;
+} | {
+    status: typeof AuthStateStatus.CHECKING;
+} | {
+    status: typeof AuthStateStatus.ERROR_CHECKING;
+    error: Error;
+} | {
+    status: typeof AuthStateStatus.SIGNED_OUT;
+} | {
+    status: typeof AuthStateStatus.CONTEXT_LOADING;
+    session: Session;
+} | {
+    status: typeof AuthStateStatus.ERROR_CONTEXT;
+    error: Error;
+    session: Session;
+} | {
+    status: typeof AuthStateStatus.INITIALIZING;
+    session: Session;
+    context: C;
+} | {
+    status: typeof AuthStateStatus.ERROR_INITIALIZING;
+    error: Error;
+    session: Session;
+    context: C;
+} | {
+    status: typeof AuthStateStatus.AUTH_READY;
+    session: Session;
+    context: C | null;
+};

package/dist/src/core/types.d.ts

@@ -0,0 +1,33 @@
+import type { Session } from "@supabase/supabase-js";
+import type { CoreState } from "./states";
+import { AuthStateStatus } from "./constants";
+type DisallowedStatuses = typeof AuthStateStatus.START | typeof AuthStateStatus.CHECKING | typeof AuthStateStatus.ERROR_CHECKING | typeof AuthStateStatus.SIGNED_OUT | typeof AuthStateStatus.CONTEXT_LOADING | typeof AuthStateStatus.ERROR_CONTEXT | typeof AuthStateStatus.INITIALIZING | typeof AuthStateStatus.ERROR_INITIALIZING | typeof AuthStateStatus.AUTH_READY;
+type CustomStateConstraint = {
+    status: Exclude<string, DisallowedStatuses>;
+};
+type WithSessionContext<C, T> = T extends {
+    status: string;
+} ? T & {
+    session: Session;
+    context: C | null;
+} : never;
+/** When D is void (default), returns CoreState. When D is custom states, returns core states | (D with session+context added) */
+export type AppState<C, D = void> = [D] extends [void] ? CoreState<C> : Exclude<CoreState<C>, {
+    status: typeof AuthStateStatus.AUTH_READY;
+}> | WithSessionContext<C, D>;
+export interface SupamachineProviderProps<C, D extends CustomStateConstraint | void = void> {
+    loadContext?: (session: Session) => Promise<C>;
+    initializeApp?: (snapshot: {
+        session: Session;
+        context: C;
+    }) => void | Promise<void>;
+    mapState?: [D] extends [void] ? never : (snapshot: Extract<CoreState<C>, {
+        status: typeof AuthStateStatus.AUTH_READY;
+    }>) => D;
+    children: React.ReactNode;
+}
+export type UseSupamachineReturn<C, D extends CustomStateConstraint | void = void> = {
+    state: AppState<C, D>;
+    updateContext: (updater: (current: C) => C | Promise<C>) => Promise<void>;
+};
+export {};

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export { SupamachineProvider, useSupamachine, } from "./react/SupamachineProvider";
+export type { SupamachineOptions } from "./react/SupamachineProvider";
+export { AuthStateStatus } from "./core/constants";
+export { LogLevel } from "./core/logger";
+export type { AppState, SupamachineProviderProps, UseSupamachineReturn, } from "./core/types";

package/dist/src/react/SupamachineProvider.d.ts

@@ -0,0 +1,28 @@
+import type { SupabaseClient } from "@supabase/supabase-js";
+import type { SupamachineProviderProps } from "../core/types";
+export type SupamachineOptions = {
+    getSessionTimeoutMs?: number;
+    loadContextTimeoutMs?: number;
+    initializeAppTimeoutMs?: number;
+    /** 'none' | 'error' | 'warn' | 'info' | 'debug'. Default: 'warn'. Uses [Supamachine][subsystem] format. */
+    logLevel?: "none" | "error" | "warn" | "info" | "debug";
+};
+export interface SupamachineProviderPropsWithSupabase<C, D extends {
+    status: string;
+} | void = void> extends SupamachineProviderProps<C, D> {
+    supabase: SupabaseClient;
+}
+export interface SupamachineContextValue<C, D extends {
+    status: string;
+} | void = void> {
+    state: import("../core/types").AppState<C, D>;
+    updateContext: (updater: (current: C) => C | Promise<C>) => Promise<void>;
+}
+export declare function SupamachineProvider<C, D extends {
+    status: string;
+} | void = void>({ supabase, loadContext, mapState, initializeApp, children, options: opts, }: SupamachineProviderPropsWithSupabase<C, D> & {
+    options?: SupamachineOptions;
+}): import("react/jsx-runtime").JSX.Element | null;
+export declare function useSupamachine<C, D extends {
+    status: string;
+} | void = void>(): SupamachineContextValue<C, D>;

package/dist/src/react/useSupamachine.d.ts

@@ -0,0 +1 @@
+export { useSupamachine } from './SupamachineProvider';

package/dist/src/supabase/adapter.d.ts

@@ -0,0 +1,7 @@
+import type { SupamachineCore } from "../core/runtime";
+import type { SupabaseClient } from "@supabase/supabase-js";
+import { type LogLevel } from "../core/logger";
+export declare function attachSupabase<C, D>(core: SupamachineCore<C, D>, supabase: SupabaseClient, options?: {
+    getSessionTimeoutMs?: number;
+    logLevel?: LogLevel;
+}): () => void;

package/dist/supabase/adapter.d.ts

@@ -0,0 +1,7 @@
+import type { SupamachineCore } from "../core/runtime";
+import type { SupabaseClient } from "@supabase/supabase-js";
+import { type LogLevel } from "../core/logger";
+export declare function attachSupabase<C, D>(core: SupamachineCore<C, D>, supabase: SupabaseClient, options?: {
+    getSessionTimeoutMs?: number;
+    logLevel?: LogLevel;
+}): () => void;