SETUP_GUIDE.md

WoffuX Setup Guide

Complete step-by-step guide to configure WoffuX on your machine.

🔐 Credential Configuration

Swift has two main approaches for managing sensitive configuration like API keys and tokens:

Option 1: xcconfig Files (Recommended ⭐)

Similar to: .env files in Node.js, local.properties in Android

Pros:

• ✅ Clean separation of config from code
• ✅ Different configs for Debug/Release builds
• ✅ Easy to exclude from version control
• ✅ Industry standard for iOS/macOS projects

Setup Steps:

1. Create your config file:

   cp Config/Config.xcconfig.template Config.xcconfig

2. Edit Config.xcconfig:

   WOFFU_COMPANY = mycompany
   WOFFU_JWT_TOKEN = eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
   WOFFU_USERNAME = Xavi
   

3. Add to Xcode:

   • Open Xcode
   • Right-click on project root → "Add Files to WoffuX"
   • Select Config.xcconfig
   • ✅ Check "Copy items if needed"
   • ✅ Check your Watch App target

4. Set as Configuration File:

   • Select project in navigator
   • Select the PROJECT (not target)
   • Go to "Info" tab
   • Under "Configurations", expand "Debug" and "Release"
   • Set Config.xcconfig for both configurations

5. Add keys to Info.plist:

   • Open Info.plist (in Watch App target)
   • Add these three keys:

   <key>WoffuCompany</key>
   <string>$(WOFFU_COMPANY)</string>
   <key>WoffuJWTToken</key>
   <string>$(WOFFU_JWT_TOKEN)</string>
   <key>WoffuUsername</key>
   <string>$(WOFFU_USERNAME)</string>

6. Verify .gitignore:

   # Should already be there
   Config.xcconfig
   *.xcconfig
   !Config.xcconfig.template
   

7. Clean and rebuild:

   • Product → Clean Build Folder (⇧⌘K)
   • Product → Build (⌘B)

Option 2: Local Swift File (Simpler but less flexible)

Similar to: Hardcoded configs, but in a separate ignored file

Pros:

• ✅ Very simple
• ✅ No Xcode configuration needed
• ✅ Easy to understand

Cons:

• ❌ Can't have different configs for Debug/Release
• ❌ Less standard approach

Setup Steps:

1. Create WoffuConfig.local.swift:

   // WoffuConfig.local.swift
   // This file is git-ignored and contains your credentials
   
   extension WoffuConfig {
       static let company = "mycompany"
       static let jwtToken = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
       static let username = "Xavi"
   }

2. Add to Xcode:

   • Right-click on "Config" folder → "Add Files"
   • Select WoffuConfig.local.swift
   • ✅ Check your Watch App target

3. Verify .gitignore:

   WoffuConfig.local.swift
   

🔍 Getting Your JWT Token

You need to extract the JWT token from Woffu's web application.

Method 1: Browser DevTools

1. Open Woffu in browser:

   https://your-company.woffu.com
   

2. Open DevTools:

   • Chrome/Edge: F12 or Ctrl+Shift+I
   • Safari: Develop → Show Web Inspector
   • Firefox: F12

3. Go to Network tab

4. Perform any action (like clicking on a menu)

5. Find a request to /api/

6. Check Headers:

   • Look for Authorization header
   • Copy the value after Bearer
   • Example: Bearer eyJhbGciOiJIUzI1Ni...
   • Your token is the part AFTER "Bearer "

Method 2: Application Storage

1. Open DevTools → Application (Chrome) or Storage (Firefox)

2. Check these locations:

   • Local Storage → https://your-company.woffu.com
   • Look for keys like: token, authToken, jwt, access_token

3. Copy the token value

✅ Verification

Test your configuration:

// Add this to your app initialization
print("Company: \(WoffuConfig.company)")
print("Token exists: \(!WoffuConfig.jwtToken.isEmpty)")
print("Username: \(WoffuConfig.username)")

// Or use the validation
do {
    try WoffuConfig.validateOrThrow()
    print("✅ Configuration is valid")
} catch {
    print("❌ Configuration error: \(error)")
}

🚨 Common Issues

Issue: "Cannot find 'WoffuConfig' in scope"

Solution: Make sure WoffuConfig.swift is added to your Watch App target:

• Select the file
• Open File Inspector (right panel)
• Check "Target Membership"

Issue: xcconfig values not loading

Solution:

1. Clean build folder (⇧⌘K)
2. Verify xcconfig is set in Project → Info → Configurations
3. Verify Info.plist has the $(VARIABLE) syntax
4. Restart Xcode

Issue: "Config.xcconfig not found"

Solution:

• You need to create it from the template
• It's git-ignored by design (for security)
• Each developer needs their own Config.xcconfig

🔒 Security Best Practices

1. NEVER commit credentials:

   • ✅ Config.xcconfig is in .gitignore
   • ✅ WoffuConfig.local.swift is in .gitignore
   • ✅ Only commit .template files

2. Rotate tokens regularly:

   • JWT tokens should be refreshed periodically
   • Update your config file when needed

3. Different tokens for different environments:

   • Use different xcconfig files:
     • Config.Debug.xcconfig
     • Config.Release.xcconfig

4. Keep your repository clean:

   # Check what would be committed
   git status
   
   # Should NOT see:
   # - Config.xcconfig
   # - WoffuConfig.local.swift

📞 Need Help?

If you encounter issues:

1. Check the logs in Xcode Console
2. Verify your JWT token is still valid
3. Test the API with Postman first
4. Review the README.md for architecture details