oauth-masterclass-swift / SETUP_GUIDE.md

# Quick Setup Guide

## Step 1: Create Xcode Project

1. Open Xcode
2. Select "Create a new Xcode project"
3. Choose "iOS" → "App"
4. Configure:
   - Product Name: **ATProtoOAuthDemo**
   - Team: Your team
   - Organization Identifier: **me.ngerakines** (or your own)
   - Interface: **SwiftUI**
   - Language: **Swift**
   - Deployment Target: **iOS 14.0+**

## Step 2: Add Source Files to Xcode

### Method A: Drag and Drop (Recommended)

1. In Finder, navigate to the `oauth-ios/ATProtoOAuthDemo` folder
2. Drag these folders into your Xcode project:
   - Authentication/
   - Models/
   - Networking/
   - Utilities/
   - Views/
3. Drag these individual files:
   - ATProtoOAuthDemoApp.swift
   - Info.plist

4. When prompted, check:
   - ✅ Copy items if needed
   - ✅ Create groups
   - ✅ Add to target: ATProtoOAuthDemo

### Method B: Manual Import

For each Swift file:
1. Right-click project in Xcode
2. Select "Add Files to [Project]..."
3. Navigate to the file
4. Click "Add"

## Step 3: Configure Info.plist

### Option A: Replace Xcode's Info.plist
1. Delete the default Info.plist in Xcode
2. Add the provided Info.plist file

### Option B: Merge manually
1. Open your project's Info.plist
2. Add the URL Scheme configuration:

```xml
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>me.ngerakines.atprotodemo.oauth</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>me.ngerakines.atprotodemo</string>
        </array>
    </dict>
</array>
```

## Step 4: Update Constants (If Needed)

If you used a different bundle identifier:

1. Open `Utilities/Constants.swift`
2. Update:
   ```swift
   static let urlScheme = "YOUR-BUNDLE-ID"
   ```
3. Ensure this matches the URL scheme in Info.plist

## Step 5: Build and Run

1. Select a simulator (e.g., iPhone 15 Pro)
2. Press **⌘R** or click the Run button
3. Wait for build to complete

## Step 6: Test Authentication

1. Enter a Bluesky handle: `yourname.bsky.social`
2. Tap "Sign In with OAuth"
3. Authorize in the web view
4. You'll be redirected back to the app

## Verification Checklist

- [ ] All Swift files imported and compile successfully
- [ ] Info.plist contains URL scheme configuration
- [ ] Constants.swift URL scheme matches Info.plist
- [ ] App builds without errors
- [ ] App launches and shows login screen
- [ ] OAuth redirect works (after authentication)

## Common Build Issues

### "No such module 'CryptoKit'"
- **Solution**: Ensure deployment target is iOS 14.0+

### "Cannot find 'AppConstants' in scope"
- **Solution**: Ensure Constants.swift is added to target

### URL Scheme Not Working
- **Solution**: Check Info.plist URL scheme matches Constants.swift exactly

### Missing Files in Target
1. Select the file in Xcode
2. Open File Inspector (⌘⌥1)
3. Under "Target Membership", check your app target

## Testing with a Real Account

1. Create a Bluesky account at https://bsky.app (free)
2. Use your handle in the app (e.g., `alice.bsky.social`)
3. After authentication, test creating a post
4. Verify the post appears on Bluesky

## Next Steps

After successful setup:
- Review the architecture in README.md
- Explore the OAuth flow in `OAuthClient.swift`
- Customize the UI in the Views folder
- Add more XRPC methods to `XRPCClient.swift`

## Getting Help

If you encounter issues:
1. Check the Xcode console for error messages
2. Review the README.md troubleshooting section
3. Verify all files are properly added to the target
4. Ensure deployment target is iOS 14.0+

## File Count Verification

Your project should contain:
- **17 files** total (16 Swift files + 1 plist)
- **6 directories** (Authentication, Models, Networking, Utilities, Views, root)

Run this to verify:
```bash
find ATProtoOAuthDemo -type f | wc -l
```
Should return: 17