@inventbuild/supamachine 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InventBuild.Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# Supamachine
+
+A deterministic authentication state machine for Supabase web and mobile apps.
+
+This is an early-stage library designed to make authentication easier and way less error-prone, especially as your app grows in complexity.
+
+## Overview
+
+Does this kind of auth code look familiar to you?
+
+```ts
+const {
+  data: { subscription },
+} = supabase.auth.onAuthStateChange((event, session) => {
+  if (event === "INITIAL_SESSION" || event === "TOKEN_REFRESHED") {
+    setLoading(false);
+  }
+  if (session) {
+    setSession(session);
+  } else {
+    setSession(null);
+  }
+  ...and so much more of this
+});
+```
+
+**THERE'S GOT TO BE A BETTER WAY!**
+
+Supamachine models auth as an explicit state machine with clear states (CHECKING, SIGNED_OUT, CONTEXT_LOADING, INITIALIZING, AUTH_READY, plus error states) and allows you to derive custom app states via `mapState`.
+
+## Real-World Benefits
+
+When I moved a client project from my original AuthContext to Supamachine, Supamachine turned ~300 lines of lifecycle orchestration (session management, auth state changes, post-login flow, navigation decisions) into ~50 lines of configuration (loadContext, initializeApp, mapState).
+
+## Usage
+
+`pnpm add @inventbuild/supamachine`
+
+### Basic setup
+
+```tsx
+import {
+  SupamachineProvider,
+  useSupamachine,
+  AuthStateStatus,
+} from "@inventbuild/supamachine";
+
+type MyContext = { userData: { name: string } };
+type MyAppState = { status: "MAIN_APP"; session: Session; context: MyContext };
+
+return (
+  <SupamachineProvider<MyContext, MyAppState>
+    supabase={supabase}
+    loadContext={async (session) => {
+      const { data } = await supabase
+        .from("profiles")
+        .select("*")
+        .eq("id", session.user.id)
+        .single();
+      return { userData: data };
+    }}
+    mapState={(snapshot) => ({
+      status: "MAIN_APP",
+      session: snapshot.session,
+      context: snapshot.context!,
+    })}
+  >
+    <App />
+  </SupamachineProvider>
+);
+
+function App() {
+  const { state, updateContext } = useSupamachine<MyContext, MyAppState>();
+
+  switch (state.status) {
+    case AuthStateStatus.CHECKING:
+    case AuthStateStatus.CONTEXT_LOADING:
+      return <Loading />;
+    case AuthStateStatus.SIGNED_OUT:
+      return <Login />;
+    case "MAIN_APP":
+      return <Home session={state.session} />;
+    default:
+      return <Loading />;
+  }
+}
+```
+
+### Provider API
+
+- **supabase** (required) – Supabase client instance
+- **loadContext(session)** – Optional. Fetches app context (e.g. user profile) after auth
+- **initializeApp({ session, context })** – Optional. Side effects after context is loaded (e.g. set avatar)
+- **mapState(snapshot)** – Optional. Maps the internal AUTH_READY state to your custom app states
+- **actions** – Optional. Auth actions (signIn, signOut, etc.) to expose via `useSupamachine()`. Merged with a default `signOut` so you always have `actions.signOut()` available.
+- **options** – Optional. `logLevel`, `getSessionTimeoutMs`, `loadContextTimeoutMs`, `initializeAppTimeoutMs`
+
+### actions
+
+This is an optional convenience for your imperative Supabase auth methods, like signInWith... and signOut, etc. Pass your auth actions to the provider; they're exposed via `useSupamachine().actions`. Since Supamachine responds to Supabase events, you don't need to use updateContext. A default `signOut` is included since it's simple (but can be overriden). Example usage:
+
+```tsx
+<SupamachineProvider
+  supabase={supabase}
+  actions={{
+    signOut: () => supabase.auth.signOut(),
+    signInWithOtp: (email) => supabase.auth.signInWithOtp({ email }),
+    signInWithGoogle: () => { /* platform-specific */ },
+  }}
+>
+```
+
+```ts
+const { state, actions } = useSupamachine();
+actions.signOut();
+actions.signInWithOtp("user@example.com");
+```
+
+If you omit `actions`, you still get `actions.signOut()` from the default.
+
+### updateContext
+
+Use `updateContext` to imperatively update context and trigger a re-run of `mapState`:
+
+```ts
+const { updateContext } = useSupamachine();
+updateContext((current) => ({
+  ...current,
+  userData: { ...current.userData, onboardingComplete: true },
+}));
+```
+
+## Philosophy
+
+Handling auth in your app is all about _states._ Supamachine explicitly defines every possible state (CHECKING, SIGNED*OUT, CONTEXT_LOADING, INITIALIZING, AUTH_READY, ERROR*\*) and lets you extend with custom states via `mapState`. By capturing all states and transitions, edge cases are handled deterministically.

package/dist/core/constants.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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_SESSION: "CHECKING_SESSION";
+    readonly AUTHENTICATING: "AUTHENTICATING";
+    readonly SIGNED_OUT: "SIGNED_OUT";
+    readonly CONTEXT_LOADING: "CONTEXT_LOADING";
+    readonly INITIALIZING: "INITIALIZING";
+    readonly AUTH_READY: "AUTH_READY";
+    readonly ERROR_CHECKING_SESSION: "ERROR_CHECKING_SESSION";
+    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_CHANGED: "AUTH_CHANGED";
+    readonly AUTH_INITIATED: "AUTH_INITIATED";
+    readonly AUTH_CANCELLED: "AUTH_CANCELLED";
+    readonly CONTEXT_RESOLVED: "CONTEXT_RESOLVED";
+    readonly INITIALIZED: "INITIALIZED";
+    readonly ERROR_CHECKING_SESSION: "ERROR_CHECKING_SESSION";
+    readonly ERROR_CONTEXT: "ERROR_CONTEXT";
+    readonly ERROR_INITIALIZING: "ERROR_INITIALIZING";
+};
+export type AuthEventType = (typeof AuthEventType)[keyof typeof AuthEventType];

package/dist/core/constants.js

@@ -0,0 +1,31 @@
+/**
+ * Core machine states. Use these when checking state or in mapState.
+ * Distinct from AuthEventType (event types that drive transitions).
+ */
+export const AuthStateStatus = {
+    START: "START",
+    CHECKING_SESSION: "CHECKING_SESSION",
+    AUTHENTICATING: "AUTHENTICATING",
+    SIGNED_OUT: "SIGNED_OUT",
+    CONTEXT_LOADING: "CONTEXT_LOADING",
+    INITIALIZING: "INITIALIZING",
+    AUTH_READY: "AUTH_READY",
+    ERROR_CHECKING_SESSION: "ERROR_CHECKING_SESSION",
+    ERROR_CONTEXT: "ERROR_CONTEXT",
+    ERROR_INITIALIZING: "ERROR_INITIALIZING",
+};
+/**
+ * Internal event types that drive the state machine.
+ * Mapped from Supabase auth events by the adapter.
+ */
+export const AuthEventType = {
+    START: "START",
+    AUTH_CHANGED: "AUTH_CHANGED",
+    AUTH_INITIATED: "AUTH_INITIATED",
+    AUTH_CANCELLED: "AUTH_CANCELLED",
+    CONTEXT_RESOLVED: "CONTEXT_RESOLVED",
+    INITIALIZED: "INITIALIZED",
+    ERROR_CHECKING_SESSION: "ERROR_CHECKING_SESSION",
+    ERROR_CONTEXT: "ERROR_CONTEXT",
+    ERROR_INITIALIZING: "ERROR_INITIALIZING",
+};

package/dist/core/events.d.ts

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

package/dist/core/events.js

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

package/dist/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/core/logger.js

@@ -0,0 +1,41 @@
+export const LogLevel = {
+    NONE: 0,
+    ERROR: 1,
+    WARN: 2,
+    INFO: 3,
+    DEBUG: 4,
+};
+const PREFIX = '[Supamachine]';
+export function createLogger(subsystem, level) {
+    const prefix = `${PREFIX}[${subsystem}]`;
+    return {
+        error: level >= LogLevel.ERROR
+            ? (msg, ...a) => console.error(prefix, msg, ...a)
+            : () => { },
+        warn: level >= LogLevel.WARN
+            ? (msg, ...a) => console.warn(prefix, msg, ...a)
+            : () => { },
+        info: level >= LogLevel.INFO
+            ? (msg, ...a) => console.log(prefix, msg, ...a)
+            : () => { },
+        debug: level >= LogLevel.DEBUG
+            ? (msg, ...a) => console.log(prefix, msg, ...a)
+            : () => { },
+    };
+}
+export function parseLogLevel(value) {
+    if (!value)
+        return LogLevel.WARN;
+    const v = value.toLowerCase();
+    if (v === 'none')
+        return LogLevel.NONE;
+    if (v === 'error')
+        return LogLevel.ERROR;
+    if (v === 'warn')
+        return LogLevel.WARN;
+    if (v === 'info')
+        return LogLevel.INFO;
+    if (v === 'debug')
+        return LogLevel.DEBUG;
+    return LogLevel.WARN;
+}

package/dist/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/core/reducer.js

@@ -0,0 +1,223 @@
+import { AuthStateStatus, AuthEventType } from "./constants";
+import { createLogger, LogLevel as LL } from "./logger";
+let log = createLogger("reducer", LL.WARN);
+export function setReducerLogLevel(level) {
+    log = createLogger("reducer", level);
+}
+/** Pre-context states use null; avoids TS inferring C = null from literal */
+const NO_CONTEXT = null;
+function invalidTransition(state, event) {
+    log.warn(`invalid transition: ${state.status} + ${event.type}`);
+    return state;
+}
+export function reducer(state, event) {
+    let next;
+    switch (state.status) {
+        case AuthStateStatus.START:
+            switch (event.type) {
+                case AuthEventType.START:
+                    next = { status: AuthStateStatus.CHECKING_SESSION, context: NO_CONTEXT };
+                    break;
+                default:
+                    return invalidTransition(state, event);
+            }
+            break;
+        case AuthStateStatus.CHECKING_SESSION:
+            switch (event.type) {
+                case AuthEventType.AUTH_CHANGED:
+                    if (event.session) {
+                        next = {
+                            status: AuthStateStatus.CONTEXT_LOADING,
+                            session: event.session,
+                            context: NO_CONTEXT,
+                        };
+                    }
+                    else {
+                        next = { status: AuthStateStatus.SIGNED_OUT, context: NO_CONTEXT };
+                    }
+                    break;
+                case AuthEventType.ERROR_CHECKING_SESSION:
+                    next = {
+                        status: AuthStateStatus.ERROR_CHECKING_SESSION,
+                        error: event.error,
+                        context: NO_CONTEXT,
+                    };
+                    break;
+                default:
+                    return invalidTransition(state, event);
+            }
+            break;
+        case AuthStateStatus.AUTHENTICATING:
+            switch (event.type) {
+                case AuthEventType.AUTH_CHANGED:
+                    if (event.session) {
+                        next = {
+                            status: AuthStateStatus.CONTEXT_LOADING,
+                            session: event.session,
+                            context: NO_CONTEXT,
+                        };
+                    }
+                    else {
+                        next = { status: AuthStateStatus.SIGNED_OUT, context: NO_CONTEXT };
+                    }
+                    break;
+                case AuthEventType.AUTH_CANCELLED:
+                    next = { status: AuthStateStatus.SIGNED_OUT, context: NO_CONTEXT };
+                    break;
+                default:
+                    return invalidTransition(state, event);
+            }
+            break;
+        case AuthStateStatus.CONTEXT_LOADING:
+            switch (event.type) {
+                case AuthEventType.CONTEXT_RESOLVED:
+                    next = {
+                        status: AuthStateStatus.INITIALIZING,
+                        session: state.session,
+                        context: event.context,
+                    };
+                    break;
+                case AuthEventType.ERROR_CONTEXT:
+                    next = {
+                        status: AuthStateStatus.ERROR_CONTEXT,
+                        session: state.session,
+                        error: event.error,
+                        context: NO_CONTEXT,
+                    };
+                    break;
+                case AuthEventType.AUTH_CHANGED:
+                    if (!event.session) {
+                        next = { status: AuthStateStatus.SIGNED_OUT, context: NO_CONTEXT };
+                    }
+                    else {
+                        next = {
+                            status: AuthStateStatus.CONTEXT_LOADING,
+                            session: event.session,
+                            context: NO_CONTEXT,
+                        };
+                    }
+                    break;
+                default:
+                    return invalidTransition(state, event);
+            }
+            break;
+        case AuthStateStatus.INITIALIZING:
+            switch (event.type) {
+                case AuthEventType.INITIALIZED:
+                    next = {
+                        status: AuthStateStatus.AUTH_READY,
+                        session: state.session,
+                        context: state.context,
+                    };
+                    break;
+                case AuthEventType.ERROR_INITIALIZING:
+                    next = {
+                        status: AuthStateStatus.ERROR_INITIALIZING,
+                        error: event.error,
+                        session: state.session,
+                        context: state.context,
+                    };
+                    break;
+                case AuthEventType.AUTH_CHANGED:
+                    if (!event.session) {
+                        next = { status: AuthStateStatus.SIGNED_OUT, context: NO_CONTEXT };
+                    }
+                    else {
+                        next = {
+                            status: AuthStateStatus.CONTEXT_LOADING,
+                            session: event.session,
+                            context: NO_CONTEXT,
+                        };
+                    }
+                    break;
+                default:
+                    return invalidTransition(state, event);
+            }
+            break;
+        case AuthStateStatus.AUTH_READY:
+            switch (event.type) {
+                case AuthEventType.AUTH_CHANGED:
+                    if (!event.session) {
+                        next = { status: AuthStateStatus.SIGNED_OUT, context: NO_CONTEXT };
+                    }
+                    else {
+                        next = {
+                            status: AuthStateStatus.CONTEXT_LOADING,
+                            session: event.session,
+                            context: NO_CONTEXT,
+                        };
+                    }
+                    break;
+                default:
+                    return invalidTransition(state, event);
+            }
+            break;
+        case AuthStateStatus.SIGNED_OUT:
+            switch (event.type) {
+                case AuthEventType.AUTH_CHANGED:
+                    if (event.session) {
+                        next = {
+                            status: AuthStateStatus.CONTEXT_LOADING,
+                            session: event.session,
+                            context: NO_CONTEXT,
+                        };
+                    }
+                    else {
+                        next = state;
+                    }
+                    break;
+                case AuthEventType.AUTH_INITIATED:
+                    next = { status: AuthStateStatus.AUTHENTICATING, context: NO_CONTEXT };
+                    break;
+                default:
+                    return invalidTransition(state, event);
+            }
+            break;
+        case AuthStateStatus.ERROR_CHECKING_SESSION:
+            switch (event.type) {
+                case AuthEventType.AUTH_CHANGED:
+                    if (event.session) {
+                        next = {
+                            status: AuthStateStatus.CONTEXT_LOADING,
+                            session: event.session,
+                            context: NO_CONTEXT,
+                        };
+                    }
+                    else {
+                        next = { status: AuthStateStatus.SIGNED_OUT, context: NO_CONTEXT };
+                    }
+                    break;
+                case AuthEventType.AUTH_INITIATED:
+                    next = { status: AuthStateStatus.AUTHENTICATING, context: NO_CONTEXT };
+                    break;
+                default:
+                    return invalidTransition(state, event);
+            }
+            break;
+        case AuthStateStatus.ERROR_CONTEXT:
+        case AuthStateStatus.ERROR_INITIALIZING:
+            switch (event.type) {
+                case AuthEventType.AUTH_CHANGED:
+                    if (event.session) {
+                        next = {
+                            status: AuthStateStatus.CONTEXT_LOADING,
+                            session: event.session,
+                            context: NO_CONTEXT,
+                        };
+                    }
+                    else {
+                        next = { status: AuthStateStatus.SIGNED_OUT, context: NO_CONTEXT };
+                    }
+                    break;
+                default:
+                    return invalidTransition(state, event);
+            }
+            break;
+        default: {
+            const _exhaustive = state;
+            throw new Error(`unknown state: ${state.status}`);
+        }
+    }
+    log.debug(`${state.status} + ${event.type} → ${next.status}`);
+    return next;
+}

package/dist/core/runtime.d.ts

@@ -0,0 +1,40 @@
+import type { Session } from "@supabase/supabase-js";
+import type { CoreState } from "./states";
+import type { AuthEvent } from "./events";
+import type { AppState, MapStateSnapshot } from "./types";
+import { type LogLevel } from "./logger";
+export interface RuntimeOptions<C, D> {
+    loadContext?: (session: Session) => Promise<C>;
+    mapState?: (snapshot: MapStateSnapshot<C>) => D;
+    initializeApp?: (snapshot: {
+        session: Session;
+        context: C;
+    }) => void | Promise<void>;
+    loadContextTimeoutMs?: number;
+    initializeAppTimeoutMs?: number;
+    authenticatingTimeoutMs?: number;
+    logLevel?: LogLevel;
+}
+export declare class SupamachineCore<C, D> {
+    private readonly options;
+    private state;
+    private sessionForLoading;
+    private authenticatingTimer;
+    private listeners;
+    private loadContextTimeoutMs;
+    private initializeAppTimeoutMs;
+    private authenticatingTimeoutMs;
+    private log;
+    constructor(options: RuntimeOptions<C, D>);
+    setLogLevel(level: LogLevel): void;
+    updateContext(updater: (current: C) => C | Promise<C>): Promise<void>;
+    beginAuth(): void;
+    cancelAuth(): 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;
+}