managarten/apps-archived/maerchenzauber/@mana-auth-mobile/IMPLEMENTATION_GUIDE.md

Implementation Guide for @mana/auth-mobile

Overview

This package contains a reusable authentication system extracted from the Storyteller mobile app. It provides a complete authentication solution for Mana Core-powered React Native apps with full customization support.

Package Structure

@mana-auth-mobile/
├── src/
│   ├── services/           # Auth and token management services
│   │   ├── authService.ts         # Main authentication service
│   │   └── tokenManager.ts        # JWT token manager with auto-refresh
│   ├── components/         # UI components
│   │   ├── ManaLoginScreen.tsx    # Complete login/register flow
│   │   ├── GoogleSignInButton.tsx # Google OAuth button
│   │   └── AppleSignInButton.tsx  # Apple Sign In button
│   ├── contexts/           # React contexts
│   │   └── ManaAuthContext.tsx    # Authentication state management
│   ├── utils/              # Utility functions
│   │   ├── safeStorage.ts         # Secure storage wrapper
│   │   ├── logger.ts              # Logging utilities
│   │   ├── deviceManager.ts       # Device identification
│   │   └── networkErrorUtils.ts   # Network helpers
│   ├── types/              # TypeScript definitions
│   │   └── index.ts               # Auth-related types
│   ├── config/             # Configuration system
│   │   ├── types.ts               # Config type definitions
│   │   ├── defaults.ts            # Default configurations
│   │   └── ManaAuthConfigProvider.tsx  # Config provider
│   ├── hooks/              # React hooks
│   │   └── useManaAuth.ts         # Main auth hook
│   └── index.ts            # Package exports
├── package.json
├── tsconfig.json
├── README.md
└── IMPLEMENTATION_GUIDE.md

Core Components to Implement

1. Services (Already Structured)

The following services need to be copied from the storyteller codebase with minimal modifications:

• authService.ts: Copy from mobile/src/services/authService.ts

  • Replace hardcoded BACKEND_URL with config.environment.backendUrl
  • Replace storage keys with config.environment.storageKeys

• tokenManager.ts: Copy from mobile/src/services/tokenManager.ts

  • No configuration changes needed (works with authService)

2. Components

• ManaLoginScreen.tsx: Copy from mobile/app/login.tsx

  • Use useManaAuthConfig() hook to access theme/text configuration
  • Replace hardcoded colors with config.theme.colors.*
  • Replace hardcoded text with config.text.*
  • Replace background image with config.theme.backgroundImage

• GoogleSignInButton.tsx: Copy from mobile/components/molecules/GoogleSignInButton.tsx

  • Use config.environment.googleClientId
  • Use config.theme.colors.googleButton
  • Use config.text.loginWithGoogle

• AppleSignInButton.tsx: Copy from mobile/components/molecules/AppleSignInButton.tsx

  • Use config.environment.appleClientId
  • Use config.theme.colors.appleButton
  • Use config.text.loginWithApple

3. Context (ManaAuthContext.tsx)

Copy from mobile/src/contexts/AuthContext.tsx with these changes:

• Remove Supabase-specific code (or make it optional)
• Remove RevenueCat-specific code (or make it optional)
• Use configuration for analytics instead of hardcoded PostHog
• Export useManaAuth hook

4. Main Export (index.ts)

// Configuration
export { ManaAuthConfigProvider, useManaAuthConfig } from './config/ManaAuthConfigProvider';
export * from './config/types';

// Context & Hooks
export { ManaAuthProvider, useManaAuth } from './contexts/ManaAuthContext';

// Components
export { default as ManaLoginScreen } from './components/ManaLoginScreen';
export { GoogleSignInButton } from './components/GoogleSignInButton';
export { AppleSignInButton } from './components/AppleSignInButton';

// Services (for advanced usage)
export { authService } from './services/authService';
export { tokenManager } from './services/tokenManager';

// Types
export * from './types';

Usage in Storyteller (Example)

Step 1: Install the Package

# From the storyteller mobile directory
npm install ../../../@mana-auth-mobile

Step 2: Configure in App Root

// mobile/app/_layout.tsx
import { ManaAuthConfigProvider } from '@mana/auth-mobile';

export default function RootLayout() {
  return (
    <ManaAuthConfigProvider
      environment={{
        backendUrl: process.env.EXPO_PUBLIC_STORYTELLER_BACKEND_URL || 'http://localhost:3002',
        googleClientId: process.env.EXPO_PUBLIC_GOOGLE_CLIENT_ID,
        enableGoogleSignIn: true,
        enableAppleSignIn: true,
        devMode: __DEV__,
        devCredentials: {
          email: 'till.schneider@memoro.ai',
          password: 'Aa-12345678'
        },
      }}
      theme={{
        colors: {
          primary: '#FFCB00',
          buttonPrimary: '#FFCB00',
        },
        fonts: {
          header: 'Grandstander_700Bold',
        },
        backgroundImage: require('../assets/images/marchenzauber-dadgirl.jpg'),
      }}
      text={{
        appName: 'Märchenzauber',
        loginTitle: 'Märchenzauber',
        loginSubtitle: 'Erstelle ein Konto oder melde dich an.',
        manaLoginTitle: 'Mana Login',
        showManaLogin: true,
        relatedApps: [
          {
            name: 'Memoro',
            icon: require('../assets/images/Memoro-App-Icon.png'),
            description: 'Zeichne Gespräche auf...',
            appStoreUrl: 'https://apps.apple.com/app/memoro',
            websiteUrl: 'https://memoro.ai',
          },
        ],
      }}
    >
      <ManaAuthProvider>
        {/* Rest of your app */}
      </ManaAuthProvider>
    </ManaAuthConfigProvider>
  );
}

Step 3: Use in Screens

// mobile/app/login.tsx
import { ManaLoginScreen } from '@mana/auth-mobile';

export default function LoginScreen() {
  return <ManaLoginScreen />;
}

// mobile/app/(tabs)/index.tsx
import { useManaAuth } from '@mana/auth-mobile';

export default function HomeScreen() {
  const { user, signOut } = useManaAuth();

  return (
    <View>
      <Text>Welcome {user?.name}!</Text>
      <Button title="Sign Out" onPress={signOut} />
    </View>
  );
}

Configuration Examples

German Language

<ManaAuthConfigProvider
  text={{
    appName: 'Meine App',
    loginTitle: 'Anmelden',
    loginButton: 'Anmelden',
    registerTitle: 'Konto erstellen',
    registerButton: 'Registrieren',
    loginWithEmail: 'Mit E-Mail anmelden',
    loginWithGoogle: 'Mit Google anmelden',
    loginWithApple: 'Mit Apple anmelden',
    emailPlaceholder: 'E-Mail Adresse eingeben...',
    passwordPlaceholder: 'Passwort eingeben...',
    forgotPassword: 'Passwort vergessen?',
    emailInvalid: 'Bitte gib eine gültige E-Mail-Adresse ein',
    passwordTooShort: 'Das Passwort muss mindestens 8 Zeichen lang sein',
    loginError: 'Anmeldung fehlgeschlagen',
    backButton: 'Zurück',
  }}
/>

Custom Colors

<ManaAuthConfigProvider
  theme={{
    colors: {
      primary: '#FF6B6B',
      buttonPrimary: '#FF6B6B',
      background: 'rgba(30, 30, 40, 0.95)',
      inputBackground: 'rgba(50, 50, 70, 0.8)',
      text: '#FFFFFF',
      googleButton: '#4285F4',
      appleButton: '#000000',
    },
  }}
/>

Minimal Configuration

<ManaAuthConfigProvider
  environment={{
    backendUrl: 'https://api.myapp.com',
  }}
  text={{
    appName: 'My App',
  }}
/>

Migrating from Hardcoded Auth

Before (Storyteller)

// Hardcoded in login.tsx
const handleLogin = async () => {
	await authService.signIn(email, password);
};

// Hardcoded colors
const styles = StyleSheet.create({
	button: {
		backgroundColor: '#FFCB00', // Hardcoded
	},
});

After (Using Package)

import { ManaLoginScreen, useManaAuth } from '@mana/auth-mobile';

// Configuration-driven
<ManaLoginScreen /> // Uses configured colors/text

// Or custom implementation
const { signIn } = useManaAuth();
const { colors, text } = useManaAuthConfig();

const handleLogin = async () => {
  await signIn(email, password);
};

const styles = StyleSheet.create({
  button: {
    backgroundColor: colors.buttonPrimary, // From config
  },
});

Testing the Package

Local Testing (Before Publishing)

# In @mana-auth-mobile directory
npm link

# In your app directory
npm link @mana/auth-mobile

Publishing to npm

# In @mana-auth-mobile directory
npm run build
npm publish

Next Steps

1. Complete the missing service files (copy from storyteller with configuration updates)
2. Test locally with npm link
3. Publish to npm (or private registry)
4. Update storyteller to use the package
5. Update other Mana apps (Memoro) to use the same package

Benefits

• ✅ Single authentication codebase for all Mana apps
• ✅ Consistent UX across apps with app-specific branding
• ✅ Easy to maintain and update
• ✅ Type-safe configuration
• ✅ Reduced code duplication
• ✅ Faster development of new apps