@superfan-app/apple-music-auth

A modern Expo module for Apple Music authentication in React Native apps. This module provides seamless integration with MusicKit for Apple Music authentication and token management.

Features

🎵 Complete Apple Music authentication via MusicKit
🔑 Developer and User token management
📱 iOS 15.0+ support via native SDK
⚡️ Modern Expo development workflow
🛡️ Secure token caching
🔧 TypeScript support
📝 Comprehensive error handling

Installation

npx expo install @superfan-app/apple-music-auth

This module requires the Expo Development Client (not compatible with Expo Go):

npx expo install expo-dev-client

Configuration

Set up Apple Music capabilities in your Xcode project
Obtain your Apple Music developer token from the Apple Developer Portal
(Optional) Configure your app.json/app.config.js:

{
  "expo": {
    "plugins": [
      [
        "@superfan-app/apple-music-auth",
        {
          "usageDescription": "We need access to Apple Music to personalize your experience"
        }
      ]
    ]
  }
}

If no configuration is provided, the module will use default settings:

A default usage description message will be shown in the permission dialog
iOS settings will be configured automatically for MusicKit compatibility

Usage

Wrap your app with the provider:

import { AppleMusicAuthProvider } from '@superfan-app/apple-music-auth';

export default function App() {
  return (
    <AppleMusicAuthProvider developerToken="your-developer-token">
      <MainApp />
    </AppleMusicAuthProvider>
  );
}

Use the hook in your components:

import { useAppleMusicAuth } from '@superfan-app/apple-music-auth';

function MainScreen() {
  const { 
    authState,
    requestAuthorization,
    getUserToken,
    isAuthenticating,
    error
  } = useAppleMusicAuth();

  const handleAuth = async () => {
    try {
      const status = await requestAuthorization();
      if (status === 'authorized') {
        const userToken = await getUserToken();
        // Use the user token for API calls
      }
    } catch (err) {
      console.error('Authentication failed:', err);
    }
  };

  if (isAuthenticating) {
    return <ActivityIndicator />;
  }

  if (error) {
    return <Text>Error: {error.message}</Text>;
  }

  return (
    <View>
      <Text>Status: {authState.status}</Text>
      <Button onPress={handleAuth} title="Authenticate" />
    </View>
  );
}

API Reference

AppleMusicAuthProvider

Provider component that manages authentication state.

<AppleMusicAuthProvider developerToken?: string>
  {children}
</AppleMusicAuthProvider>

Props:

developerToken: Optional developer token to initialize the provider

useAppleMusicAuth()

Hook for accessing authentication state and methods.

Returns:

authState: { status: string, developerToken?: string, userToken?: string }
requestAuthorization(): Promise<string> - Request user authorization
setDeveloperToken(token: string): void - Set the developer token
getDeveloperToken(): Promise<string> - Get the developer token
getUserToken(): Promise<string> - Get the user token
isAuthenticating: boolean - Authentication in progress
error: AppleMusicAuthError | null - Last error

Authorization Status Types

Possible values for authState.status:

'authorized' - User has granted access
'denied' - User has denied access
'notDetermined' - User hasn't been asked for permission
'restricted' - Access is restricted
'unknown' - Status cannot be determined

Development Workflow

Clean installation:

npm install
npm run build

Clean build:

npx expo prebuild --clean

Run on iOS:

npx expo run:ios

Troubleshooting

Common Issues

"Cannot find native module 'AppleMusicAuth'":
```
npx expo prebuild --clean
npx expo run:ios
```

Build errors:

npm run clean
npm run build
npx expo prebuild --clean

Authentication errors:
- Verify your developer token
- Check Apple Music capabilities in Xcode
- Ensure proper entitlements
- Check iOS version (requires 15.0+)

Security

Tokens are cached in memory
Automatic token management
Proper error handling and recovery
Uses Apple's secure MusicKit framework

Requirements

Expo SDK 47+
iOS 15.0+
Node.js 14.0+
Expo Development Client