@edcalderon/auth 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [1.0.0] - 2026-03-01
+
+### Initial Release
+
+- ✨ Provider-agnostic `AuthClient` interface
+- 🔌 Built-in Supabase adapter (`SupabaseClient`)
+- 🔌 Built-in Firebase adapter (`FirebaseClient`)
+- 🔌 Hybrid adapter for Firebase→Supabase federated flows (`HybridClient`)
+- ⚛️ React `AuthProvider` and `useAuth` hook
+- 🛡️ Unified `User` type across all providers
+- 📦 Published as `@edcalderon/auth` on NPM

package/README.md

@@ -0,0 +1,514 @@
+# @edcalderon/auth
+
+[![npm version](https://img.shields.io/npm/v/@edcalderon/auth?style=flat-square&color=0ea5e9)](https://www.npmjs.com/package/@edcalderon/auth)
+[![npm downloads](https://img.shields.io/npm/dm/@edcalderon/auth?style=flat-square&color=10b981)](https://www.npmjs.com/package/@edcalderon/auth)
+[![GitHub](https://img.shields.io/badge/GitHub-Repository-181717?style=flat-square&logo=github)](https://github.com/edcalderon/my-second-brain/tree/main/packages/auth)
+
+A universal, **provider-agnostic** authentication orchestration package for React applications. Swap between Supabase, Firebase, Directus, Google OAuth, or any custom provider without changing a single line of component code.
+
+---
+
+## 📋 Latest Changes (v1.0.0)
+
+### Initial Release
+
+- ✨ Provider-agnostic `AuthClient` interface
+- 🔌 Built-in adapters: **Supabase**, **Firebase**, **Hybrid** (Firebase→Supabase)
+- ⚛️ React `AuthProvider` context and `useAuth` hook
+- 🛡️ Unified `User` type across all providers
+- 🔑 Session token access via `getSessionToken()`
+
+For full version history, see [CHANGELOG.md](./CHANGELOG.md) and [GitHub releases](https://github.com/edcalderon/my-second-brain/releases)
+
+---
+
+## 🏗️ Architecture
+
+The package follows a **Single Source of Truth** model with a **Federated OAuth Strategy**:
+
+- **Principal Database (Source of Truth)**: Supabase anchors user identities, metadata, roles, and RLS policies in PostgreSQL (`auth.users`, `auth.identities`).
+- **OAuth / Identity Providers**: External services (Firebase, Directus, native Google OAuth, Auth0, etc.) handle frontend login bridges or federated SSO flows.
+- **The Orchestrator (`@edcalderon/auth`)**: A thin bridge layer that exposes generic interfaces (`User`, `AuthClient`). Applications consume a unified context without coupling to any specific vendor.
+
+```mermaid
+graph TD
+    UI[Frontend Applications] -->|useAuth| EdAuth["@edcalderon/auth"]
+    EdAuth -->|Direct Session| Supabase(Supabase)
+    EdAuth -->|Federated Bridge| Firebase(Firebase OAuth)
+    EdAuth -->|Custom Adapter| Directus(Directus SSO)
+    EdAuth -->|Custom Adapter| Custom(Auth0 / Custom)
+
+    Firebase -->|Sync Session| Supabase
+    Directus -->|Sync Session| Supabase
+
+    Supabase -->|Roles & Scopes| DB[(PostgreSQL)]
+```
+
+---
+
+## Features
+
+- 🎯 **Provider-Agnostic** — one interface, any backend
+- ⚛️ **React-First** — `AuthProvider` + `useAuth` hook with full TypeScript types
+- 🔌 **Extensible Adapter System** — implement `AuthClient` to add any provider
+- 🔀 **Hybrid Flows** — Firebase popup → Supabase session bridging out of the box
+- 🛡️ **Unified User Model** — `User` type normalizes identities across providers
+- 🔑 **Session Token Access** — `getSessionToken()` for API calls regardless of provider
+- 📦 **Tree-Shakeable** — import only the adapters you need
+- 🏗️ **Zero Lock-In** — swap providers by changing one line of dependency injection
+
+---
+
+## Installation
+
+### From NPM (public)
+
+```bash
+npm install @edcalderon/auth
+# or
+pnpm add @edcalderon/auth
+# or
+yarn add @edcalderon/auth
+```
+
+### From Monorepo (internal workspace)
+
+```bash
+pnpm --filter <your-app> add @edcalderon/auth@workspace:*
+```
+
+### Peer Dependencies
+
+Install the peer dependencies for your chosen provider(s):
+
+```bash
+# For Supabase
+pnpm add @supabase/supabase-js
+
+# For Firebase
+pnpm add firebase
+
+# For Hybrid (Firebase + Supabase)
+pnpm add @supabase/supabase-js firebase
+```
+
+> **Note:** `react` and `react-dom` (v18+ or v19+) are required peer dependencies.
+
+---
+
+## Quick Start
+
+### 1. Choose Your Provider
+
+| Provider | Class | Peer Dependency | Use Case |
+|----------|-------|-----------------|----------|
+| Supabase | `SupabaseClient` | `@supabase/supabase-js` | Direct Supabase Auth |
+| Firebase | `FirebaseClient` | `firebase` | Firebase-only applications |
+| Hybrid | `HybridClient` | Both | Firebase popup → Supabase session |
+| Custom | Implement `AuthClient` | Your choice | Directus, Auth0, Keycloak, etc. |
+
+### 2. Create the Provider Wrapper
+
+#### Supabase (Direct)
+
+```tsx
+// components/auth/AuthProvider.tsx
+"use client";
+
+import { AuthProvider as UniversalAuthProvider, SupabaseClient, useAuth as useUniversalAuth } from "@edcalderon/auth";
+import { supabase } from "@/lib/supabase";
+import { useMemo, type ReactNode } from "react";
+
+export function AuthProvider({ children }: { children: ReactNode }) {
+    const client = useMemo(() => new SupabaseClient(supabase), []);
+    return <UniversalAuthProvider client={client}>{children}</UniversalAuthProvider>;
+}
+
+export const useAuth = useUniversalAuth;
+```
+
+#### Hybrid (Firebase → Supabase)
+
+```tsx
+"use client";
+
+import { AuthProvider as UniversalAuthProvider, HybridClient, useAuth as useUniversalAuth } from "@edcalderon/auth";
+import { supabase } from "@/lib/supabase";
+import { auth, googleProvider, signInWithPopup, signOut, GoogleAuthProvider } from "@/lib/firebase";
+import { useMemo, type ReactNode } from "react";
+
+export function AuthProvider({ children }: { children: ReactNode }) {
+    const client = useMemo(() => new HybridClient({
+        supabase,
+        firebaseAuth: auth,
+        firebaseMethods: {
+            signInWithPopup,
+            signOut,
+            credentialFromResult: GoogleAuthProvider.credentialFromResult,
+        },
+        googleProvider,
+    }), []);
+
+    return <UniversalAuthProvider client={client}>{children}</UniversalAuthProvider>;
+}
+
+export const useAuth = useUniversalAuth;
+```
+
+### 3. Use in Components
+
+Every component consumes **identical signatures** regardless of which provider is active:
+
+```tsx
+import { useAuth } from "@/components/auth/AuthProvider";
+
+export default function Dashboard() {
+    const { user, loading, error, signInWithGoogle, signOutUser } = useAuth();
+
+    if (loading) return <Spinner />;
+    if (error) return <p>Error: {error}</p>;
+    if (!user) return <button onClick={() => signInWithGoogle()}>Sign In with Google</button>;
+
+    return (
+        <div>
+            <p>Welcome, {user.email} (via {user.provider})</p>
+            <button onClick={signOutUser}>Sign Out</button>
+        </div>
+    );
+}
+```
+
+---
+
+## 🔌 Extensibility — Custom Adapters
+
+The core strength of `@edcalderon/auth` is that **any authentication provider** can be integrated by implementing the `AuthClient` interface. No changes to your React components are required.
+
+### The `AuthClient` Interface
+
+```typescript
+export interface AuthClient {
+    getUser(): Promise<User | null>;
+    signInWithEmail(email: string, password: string): Promise<User>;
+    signInWithGoogle(redirectTo?: string): Promise<void>;
+    signOut(): Promise<void>;
+    onAuthStateChange(callback: (user: User | null) => void): () => void;
+    getSessionToken(): Promise<string | null>;
+}
+```
+
+### The `User` Type
+
+```typescript
+export interface User {
+    id: string;
+    email?: string;
+    avatarUrl?: string;
+    provider?: string;
+    metadata?: Record<string, any>;
+}
+```
+
+### Example: Directus Adapter
+
+A custom Directus adapter that uses Directus SSO (e.g., Google OAuth through Directus) and optionally syncs sessions back to Supabase:
+
+```typescript
+import type { AuthClient, User } from "@edcalderon/auth";
+
+interface DirectusClientOptions {
+    directusUrl: string;
+    supabase?: any; // Optional: sync to Supabase as source of truth
+}
+
+export class DirectusClient implements AuthClient {
+    private directusUrl: string;
+    private supabase: any;
+    private currentUser: User | null = null;
+    private listeners: Set<(user: User | null) => void> = new Set();
+
+    constructor(options: DirectusClientOptions) {
+        this.directusUrl = options.directusUrl;
+        this.supabase = options.supabase;
+    }
+
+    private mapUser(directusUser: any): User | null {
+        if (!directusUser) return null;
+        return {
+            id: directusUser.id,
+            email: directusUser.email,
+            avatarUrl: directusUser.avatar
+                ? `${this.directusUrl}/assets/${directusUser.avatar}`
+                : undefined,
+            provider: "directus",
+            metadata: {
+                firstName: directusUser.first_name,
+                lastName: directusUser.last_name,
+                role: directusUser.role,
+            },
+        };
+    }
+
+    async getUser(): Promise<User | null> {
+        try {
+            const res = await fetch(`${this.directusUrl}/users/me`, {
+                credentials: "include",
+            });
+            if (!res.ok) return null;
+            const { data } = await res.json();
+            this.currentUser = this.mapUser(data);
+            return this.currentUser;
+        } catch {
+            return null;
+        }
+    }
+
+    async signInWithEmail(email: string, password: string): Promise<User> {
+        const res = await fetch(`${this.directusUrl}/auth/login`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            credentials: "include",
+            body: JSON.stringify({ email, password }),
+        });
+        if (!res.ok) throw new Error("Directus login failed");
+        const user = await this.getUser();
+        if (!user) throw new Error("No user after login");
+        this.notifyListeners(user);
+
+        // Optional: sync to Supabase
+        if (this.supabase) {
+            await this.syncToSupabase(user);
+        }
+        return user;
+    }
+
+    async signInWithGoogle(redirectTo?: string): Promise<void> {
+        // Directus SSO — redirect to Directus Google OAuth endpoint
+        const callback = redirectTo || window.location.origin + "/auth/callback";
+        window.location.href =
+            `${this.directusUrl}/auth/login/google?redirect=${encodeURIComponent(callback)}`;
+    }
+
+    async signOut(): Promise<void> {
+        await fetch(`${this.directusUrl}/auth/logout`, {
+            method: "POST",
+            credentials: "include",
+        });
+        this.currentUser = null;
+        this.notifyListeners(null);
+    }
+
+    onAuthStateChange(callback: (user: User | null) => void): () => void {
+        this.listeners.add(callback);
+        return () => { this.listeners.delete(callback); };
+    }
+
+    async getSessionToken(): Promise<string | null> {
+        try {
+            const res = await fetch(`${this.directusUrl}/auth/refresh`, {
+                method: "POST",
+                credentials: "include",
+            });
+            if (!res.ok) return null;
+            const { data } = await res.json();
+            return data?.access_token ?? null;
+        } catch {
+            return null;
+        }
+    }
+
+    private notifyListeners(user: User | null) {
+        this.listeners.forEach((cb) => cb(user));
+    }
+
+    private async syncToSupabase(user: User) {
+        // Sync user identity to Supabase as source of truth
+        // Implementation depends on your Supabase setup
+    }
+}
+```
+
+**Usage:**
+
+```tsx
+import { AuthProvider as UniversalAuthProvider } from "@edcalderon/auth";
+import { DirectusClient } from "./adapters/DirectusClient";
+
+const client = new DirectusClient({
+    directusUrl: "https://directus.example.com",
+    supabase: supabaseInstance, // optional sync
+});
+
+<UniversalAuthProvider client={client}>
+    <App />
+</UniversalAuthProvider>
+```
+
+### Example: Auth0 Adapter (Skeleton)
+
+```typescript
+import type { AuthClient, User } from "@edcalderon/auth";
+
+export class Auth0Client implements AuthClient {
+    constructor(private auth0: any) {}
+
+    async getUser(): Promise<User | null> { /* ... */ }
+    async signInWithEmail(email: string, password: string): Promise<User> { /* ... */ }
+    async signInWithGoogle(redirectTo?: string): Promise<void> { /* ... */ }
+    async signOut(): Promise<void> { /* ... */ }
+    onAuthStateChange(callback: (user: User | null) => void): () => void { /* ... */ }
+    async getSessionToken(): Promise<string | null> { /* ... */ }
+}
+```
+
+By implementing the `AuthClient` interface, any provider fits into the same `<AuthProvider>` and `useAuth()` workflow — **zero changes** to your component tree.
+
+---
+
+## Built-in Adapters
+
+### `SupabaseClient`
+
+Direct Supabase Auth adapter. Uses `@supabase/supabase-js` for session management, OAuth, and email/password.
+
+```typescript
+import { SupabaseClient } from "@edcalderon/auth";
+import { createClient } from "@supabase/supabase-js";
+
+const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);
+const client = new SupabaseClient(supabase);
+```
+
+**Features:**
+- Email/password sign-in (`signInWithPassword`)
+- Google OAuth (`signInWithOAuth`)
+- Session token via `getSession().access_token`
+- Real-time auth state changes via `onAuthStateChange`
+
+### `FirebaseClient`
+
+Firebase-only adapter. Uses Firebase Auth methods via dependency injection (tree-shaking friendly).
+
+```typescript
+import { FirebaseClient } from "@edcalderon/auth";
+import { getAuth, GoogleAuthProvider, signInWithEmailAndPassword, signInWithPopup, signOut, onAuthStateChanged } from "firebase/auth";
+
+const auth = getAuth(app);
+const client = new FirebaseClient(auth, {
+    signInWithEmailAndPassword,
+    signInWithPopup,
+    signOut,
+    onAuthStateChanged,
+}, new GoogleAuthProvider());
+```
+
+**Features:**
+- Email/password sign-in
+- Google popup sign-in
+- Firebase ID token via `getIdToken()`
+- Real-time auth state changes
+
+### `HybridClient`
+
+Bridges Firebase Google popup → Supabase `signInWithIdToken`. Perfect for apps that need Firebase's popup UX but Supabase as the data backend.
+
+```typescript
+import { HybridClient } from "@edcalderon/auth";
+
+const client = new HybridClient({
+    supabase,
+    firebaseAuth: auth,
+    firebaseMethods: { signInWithPopup, signOut, credentialFromResult: GoogleAuthProvider.credentialFromResult },
+    googleProvider: new GoogleAuthProvider(),
+});
+```
+
+**Features:**
+- Firebase popup → extracts Google OIDC ID token → passes to Supabase `signInWithIdToken`
+- Graceful fallback to Supabase native OAuth when Firebase is not configured
+- Dual sign-out (Firebase + Supabase)
+- Auth state tracked via Supabase session
+
+---
+
+## API Reference
+
+### `<AuthProvider>`
+
+React context provider that wraps your app with authentication state.
+
+```tsx
+<AuthProvider client={authClient}>
+    {children}
+</AuthProvider>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `client` | `AuthClient` | The authentication adapter instance |
+| `children` | `ReactNode` | Child components |
+
+### `useAuth()`
+
+React hook that returns the current authentication state and actions.
+
+```typescript
+const {
+    user,              // User | null
+    loading,           // boolean
+    error,             // string | null
+    client,            // AuthClient (direct access)
+    signInWithEmail,   // (email: string, password: string) => Promise<User>
+    signInWithGoogle,  // (redirectTo?: string) => Promise<void>
+    signOutUser,       // () => Promise<void>
+} = useAuth();
+```
+
+> **Note:** `useAuth()` must be called within an `<AuthProvider>`. It will throw if used outside the provider tree.
+
+---
+
+## Publishing & Releases
+
+### Automated NPM Publishing
+
+This package uses GitHub Actions for automated publishing to NPM when version tags are created.
+
+#### Release Process
+
+1. **Update Version**: Bump the version in `package.json`
+   ```bash
+   cd packages/auth
+   npm version patch  # or minor, major
+   ```
+
+2. **Create Git Tag**: Create and push an `auth-v*` tag
+   ```bash
+   git add packages/auth/package.json
+   git commit -m "chore(auth): bump version to X.Y.Z"
+   git tag auth-vX.Y.Z
+   git push && git push --tags
+   ```
+
+3. **Automated Publishing**: GitHub Actions will automatically build and publish to NPM
+
+#### NPM Token Setup
+
+To enable automated publishing:
+
+1. Go to [NPM](https://www.npmjs.com/) → Access Tokens → Generate New Token
+2. Create a token with **Automation** scope
+3. Add to GitHub repository secrets as `NPM_TOKEN`
+
+---
+
+## Documentation
+
+- **[CHANGELOG](CHANGELOG.md)** — Version history and changes
+- **[GitHub Releases](https://github.com/edcalderon/my-second-brain/releases)** — Tagged releases
+
+---
+
+## License
+
+MIT © Edward

package/dist/AuthProvider.d.ts

@@ -0,0 +1,17 @@
+import { ReactNode } from "react";
+import { AuthClient, User } from "./types";
+interface AuthContextValue {
+    user: User | null;
+    loading: boolean;
+    error: string | null;
+    client: AuthClient;
+    signInWithEmail: (email: string, password: string) => Promise<User>;
+    signInWithGoogle: (redirectTo?: string) => Promise<void>;
+    signOutUser: () => Promise<void>;
+}
+export declare function AuthProvider({ client, children }: {
+    client: AuthClient;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useAuth(): AuthContextValue;
+export {};

package/dist/AuthProvider.js

@@ -0,0 +1,83 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useState, useMemo } from "react";
+const AuthContext = createContext(undefined);
+export function AuthProvider({ client, children }) {
+    const [user, setUser] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        let mounted = true;
+        async function initializeAuth() {
+            try {
+                const u = await client.getUser();
+                if (mounted) {
+                    setUser(u);
+                    setLoading(false);
+                }
+            }
+            catch (err) {
+                if (mounted) {
+                    setError(err.message || "Failed to initialize auth");
+                    setLoading(false);
+                }
+            }
+        }
+        initializeAuth();
+        const unsubscribe = client.onAuthStateChange((newUser) => {
+            if (mounted) {
+                setUser(newUser);
+                setLoading(false);
+            }
+        });
+        return () => {
+            mounted = false;
+            unsubscribe();
+        };
+    }, [client]);
+    const value = useMemo(() => ({
+        user,
+        loading,
+        error,
+        client,
+        signInWithEmail: async (email, password) => {
+            setError(null);
+            try {
+                return await client.signInWithEmail(email, password);
+            }
+            catch (err) {
+                setError(err.message);
+                throw err;
+            }
+        },
+        signInWithGoogle: async (redirectTo) => {
+            setError(null);
+            try {
+                await client.signInWithGoogle(redirectTo);
+            }
+            catch (err) {
+                setError(err.message);
+                throw err;
+            }
+        },
+        signOutUser: async () => {
+            setError(null);
+            try {
+                await client.signOut();
+            }
+            catch (err) {
+                setError(err.message);
+                throw err;
+            }
+        },
+    }), [user, loading, error, client]);
+    return _jsx(AuthContext.Provider, { value: value, children: children });
+}
+export function useAuth() {
+    const context = useContext(AuthContext);
+    if (!context) {
+        throw new Error("useAuth must be used within AuthProvider");
+    }
+    return context;
+}
+//# sourceMappingURL=AuthProvider.js.map

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./providers/SupabaseClient";
+export * from "./providers/FirebaseClient";
+export * from "./providers/HybridClient";
+export * from "./AuthProvider";

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./types";
+export * from "./providers/SupabaseClient";
+export * from "./providers/FirebaseClient";
+export * from "./providers/HybridClient";
+export * from "./AuthProvider";
+//# sourceMappingURL=index.js.map

package/dist/providers/FirebaseClient.d.ts

@@ -0,0 +1,22 @@
+import type { Auth } from "firebase/auth";
+import type { GoogleAuthProvider as GoogleAuthProviderType } from "firebase/auth";
+import { AuthClient, User } from "../types";
+export interface FirebaseMethods {
+    signInWithEmailAndPassword: any;
+    signInWithPopup: any;
+    signOut: any;
+    onAuthStateChanged: any;
+}
+export declare class FirebaseClient implements AuthClient {
+    private auth;
+    private methods;
+    private googleProvider;
+    constructor(auth: Auth, methods: FirebaseMethods, googleProvider: GoogleAuthProviderType);
+    private mapUser;
+    getUser(): Promise<User | null>;
+    signInWithEmail(email: string, password: string): Promise<User>;
+    signInWithGoogle(redirectTo?: string): Promise<void>;
+    signOut(): Promise<void>;
+    onAuthStateChange(callback: (user: User | null) => void): () => void;
+    getSessionToken(): Promise<string | null>;
+}

package/dist/providers/FirebaseClient.js

@@ -0,0 +1,57 @@
+export class FirebaseClient {
+    auth;
+    methods;
+    googleProvider;
+    constructor(auth, methods, googleProvider) {
+        this.auth = auth;
+        this.methods = methods;
+        this.googleProvider = googleProvider;
+    }
+    mapUser(user) {
+        if (!user)
+            return null;
+        return {
+            id: user.uid,
+            email: user.email || undefined,
+            avatarUrl: user.photoURL || undefined,
+            metadata: { displayName: user.displayName },
+        };
+    }
+    async getUser() {
+        if (this.auth.currentUser)
+            return this.mapUser(this.auth.currentUser);
+        return new Promise((resolve) => {
+            const unsubscribe = this.methods.onAuthStateChanged(this.auth, (user) => {
+                unsubscribe();
+                resolve(this.mapUser(user));
+            });
+        });
+    }
+    async signInWithEmail(email, password) {
+        const userCredential = await this.methods.signInWithEmailAndPassword(this.auth, email, password);
+        return this.mapUser(userCredential.user);
+    }
+    async signInWithGoogle(redirectTo) {
+        await this.methods.signInWithPopup(this.auth, this.googleProvider);
+    }
+    async signOut() {
+        await this.methods.signOut(this.auth);
+    }
+    onAuthStateChange(callback) {
+        const unsubscribe = this.methods.onAuthStateChanged(this.auth, (user) => {
+            callback(this.mapUser(user));
+        });
+        return () => unsubscribe();
+    }
+    async getSessionToken() {
+        if (!this.auth.currentUser)
+            return null;
+        try {
+            return await this.auth.currentUser.getIdToken();
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=FirebaseClient.js.map

package/dist/providers/HybridClient.d.ts

@@ -0,0 +1,29 @@
+import type { SupabaseClient as SupabaseClientType } from "@supabase/supabase-js";
+import type { Auth } from "firebase/auth";
+import type { GoogleAuthProvider as GoogleAuthProviderType } from "firebase/auth";
+import { AuthClient, User } from "../types";
+export interface HybridFirebaseMethods {
+    signInWithPopup: any;
+    signOut: any;
+    credentialFromResult: any;
+}
+export interface HybridClientOptions {
+    supabase: SupabaseClientType;
+    firebaseAuth: Auth | null;
+    firebaseMethods: HybridFirebaseMethods | null;
+    googleProvider: GoogleAuthProviderType | null;
+}
+export declare class HybridClient implements AuthClient {
+    private supabase;
+    private firebaseAuth;
+    private methods;
+    private googleProvider;
+    constructor(options: HybridClientOptions);
+    private mapUser;
+    getUser(): Promise<User | null>;
+    signInWithEmail(email: string, password: string): Promise<User>;
+    signInWithGoogle(redirectTo?: string): Promise<void>;
+    signOut(): Promise<void>;
+    onAuthStateChange(callback: (user: User | null) => void): () => void;
+    getSessionToken(): Promise<string | null>;
+}

package/dist/providers/HybridClient.js

@@ -0,0 +1,108 @@
+export class HybridClient {
+    supabase;
+    firebaseAuth;
+    methods;
+    googleProvider;
+    constructor(options) {
+        this.supabase = options.supabase;
+        this.firebaseAuth = options.firebaseAuth;
+        this.methods = options.firebaseMethods;
+        this.googleProvider = options.googleProvider;
+    }
+    mapUser(user) {
+        if (!user)
+            return null;
+        return {
+            id: user.id,
+            email: user.email,
+            avatarUrl: user.user_metadata?.avatar_url || user.user_metadata?.picture,
+            provider: user.app_metadata?.provider || 'supabase',
+            metadata: user.user_metadata,
+        };
+    }
+    async getUser() {
+        const { data: { user }, error } = await this.supabase.auth.getUser();
+        if (error && error.message.includes("session"))
+            return null; // Safe fallback for unauthenticated
+        if (error)
+            throw error;
+        return this.mapUser(user);
+    }
+    async signInWithEmail(email, password) {
+        const { data, error } = await this.supabase.auth.signInWithPassword({
+            email,
+            password,
+        });
+        if (error)
+            throw error;
+        if (!data.user)
+            throw new Error("No user returned");
+        return this.mapUser(data.user);
+    }
+    async signInWithGoogle(redirectTo) {
+        if (!this.firebaseAuth || !this.methods || !this.googleProvider) {
+            console.warn("Firebase not configured, falling back to Supabase native OAuth");
+            const { error } = await this.supabase.auth.signInWithOAuth({
+                provider: "google",
+                options: {
+                    redirectTo: redirectTo || (typeof window !== "undefined" ? window.location.origin : undefined),
+                },
+            });
+            if (error)
+                throw error;
+            return;
+        }
+        try {
+            // Firebase Google Popup
+            const userCredential = await this.methods.signInWithPopup(this.firebaseAuth, this.googleProvider);
+            // Generate Google OIDC ID token
+            const credential = this.methods.credentialFromResult(userCredential);
+            const idToken = credential?.idToken;
+            if (!idToken)
+                throw new Error("No Google ID Token found in credential");
+            // Pass parallel ID Token directly into Supabase
+            const { error: supaError } = await this.supabase.auth.signInWithIdToken({
+                provider: 'google',
+                token: idToken,
+            });
+            if (supaError)
+                throw supaError;
+        }
+        catch (error) {
+            // Ensure if anything fails, we clean up the floating firebase session
+            if (this.firebaseAuth && this.methods) {
+                await this.methods.signOut(this.firebaseAuth).catch(() => { });
+            }
+            throw error;
+        }
+    }
+    async signOut() {
+        // Break both sessions parallel safely
+        if (this.firebaseAuth && this.methods) {
+            try {
+                await this.methods.signOut(this.firebaseAuth);
+            }
+            catch (e) {
+                console.error("Firebase signout error:", e);
+            }
+        }
+        const { error } = await this.supabase.auth.signOut();
+        if (error)
+            throw error;
+    }
+    onAuthStateChange(callback) {
+        const { data: { subscription } } = this.supabase.auth.onAuthStateChange((_event, session) => {
+            callback(this.mapUser(session?.user));
+        });
+        return () => {
+            subscription.unsubscribe();
+        };
+    }
+    async getSessionToken() {
+        const { data: { session }, error } = await this.supabase.auth.getSession();
+        if (error || !session)
+            return null;
+        return session.access_token;
+    }
+}
+//# sourceMappingURL=HybridClient.js.map

package/dist/providers/SupabaseClient.d.ts

@@ -0,0 +1,13 @@
+import type { SupabaseClient as SupabaseClientType } from "@supabase/supabase-js";
+import { AuthClient, User } from "../types";
+export declare class SupabaseClient implements AuthClient {
+    private supabase;
+    constructor(supabase: SupabaseClientType);
+    private mapUser;
+    getUser(): Promise<User | null>;
+    signInWithEmail(email: string, password: string): Promise<User>;
+    signInWithGoogle(redirectTo?: string): Promise<void>;
+    signOut(): Promise<void>;
+    onAuthStateChange(callback: (user: User | null) => void): () => void;
+    getSessionToken(): Promise<string | null>;
+}

package/dist/providers/SupabaseClient.js

@@ -0,0 +1,64 @@
+export class SupabaseClient {
+    supabase;
+    constructor(supabase) {
+        this.supabase = supabase;
+    }
+    mapUser(user) {
+        if (!user)
+            return null;
+        return {
+            id: user.id,
+            email: user.email,
+            avatarUrl: user.user_metadata?.avatar_url,
+            provider: user.app_metadata?.provider,
+            metadata: user.user_metadata,
+        };
+    }
+    async getUser() {
+        const { data: { user }, error } = await this.supabase.auth.getUser();
+        if (error)
+            throw error;
+        return this.mapUser(user);
+    }
+    async signInWithEmail(email, password) {
+        const { data, error } = await this.supabase.auth.signInWithPassword({
+            email,
+            password,
+        });
+        if (error)
+            throw error;
+        if (!data.user)
+            throw new Error("No user returned");
+        return this.mapUser(data.user);
+    }
+    async signInWithGoogle(redirectTo) {
+        const { error } = await this.supabase.auth.signInWithOAuth({
+            provider: "google",
+            options: {
+                redirectTo: redirectTo || (typeof window !== "undefined" ? window.location.origin : undefined),
+            },
+        });
+        if (error)
+            throw error;
+    }
+    async signOut() {
+        const { error } = await this.supabase.auth.signOut();
+        if (error)
+            throw error;
+    }
+    onAuthStateChange(callback) {
+        const { data: { subscription } } = this.supabase.auth.onAuthStateChange((_event, session) => {
+            callback(this.mapUser(session?.user));
+        });
+        return () => {
+            subscription.unsubscribe();
+        };
+    }
+    async getSessionToken() {
+        const { data: { session }, error } = await this.supabase.auth.getSession();
+        if (error || !session)
+            return null;
+        return session.access_token;
+    }
+}
+//# sourceMappingURL=SupabaseClient.js.map

package/dist/types.d.ts

@@ -0,0 +1,15 @@
+export interface User {
+    id: string;
+    email?: string;
+    avatarUrl?: string;
+    provider?: string;
+    metadata?: Record<string, any>;
+}
+export interface AuthClient {
+    getUser(): Promise<User | null>;
+    signInWithEmail(email: string, password: string): Promise<User>;
+    signInWithGoogle(redirectTo?: string): Promise<void>;
+    signOut(): Promise<void>;
+    onAuthStateChange(callback: (user: User | null) => void): () => void;
+    getSessionToken(): Promise<string | null>;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@edcalderon/auth",
+  "version": "1.0.0",
+  "description": "A universal, provider-agnostic authentication orchestration package with extensible adapters for Supabase, Firebase, Directus, and custom OAuth providers",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "auth",
+    "authentication",
+    "oauth",
+    "supabase",
+    "firebase",
+    "directus",
+    "provider-agnostic",
+    "react",
+    "sso"
+  ],
+  "author": "Edward",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/edcalderon/my-second-brain.git",
+    "directory": "packages/auth"
+  },
+  "peerDependencies": {
+    "@supabase/supabase-js": "^2.0.0",
+    "firebase": "^10.0.0 || ^11.0.0 || ^12.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@supabase/supabase-js": {
+      "optional": true
+    },
+    "firebase": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.7",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}