FindMy.py Upgrade Plan: 0.8.0 → 0.9.3

Executive Summary

Current State: FindMy.py 0.8.0 (stable, working in production) Target Version: FindMy.py 0.9.3 Estimated Effort: 1-2 days Risk Level: Medium-High Priority: Future enhancement (not urgent)

Why Upgrade?

Bug fixes: Empty HTTP response workarounds (relevant to our issues)
Performance improvements: Better key alignment efficiency
Future support: 0.8.0 may become unsupported
New features: Better AirTag support, local Anisette option

Why Not Urgent?

Current 0.8.0 implementation is stable and working
Upgrade requires significant code changes
No critical bugs blocking production use

Breaking Changes Analysis

Major Changes from 0.9.0 Release

1. New acsn API Migration (PR #144)

Impact: HIGH

The most significant change - Apple's backend API changed and FindMy.py was completely rewritten to use the new API.

What Changed:

API endpoints may have changed
Response structure is different
Request format is different
Internal processing flow redesigned

Our Code Impact:

fetch_reports() method signature may differ
Response processing needs review
Error handling may need updates

2. Account JSON Format Changes

Impact: MEDIUM

The account.json file format changed significantly.

Changes:

Files are now "self-contained"
Anisette server URL stored in file (if using remote)
Local Anisette data can be embedded
Old account.json files will not work

Our Code Impact:

AppleAccountManager initialization may need updates
Must re-authenticate after upgrade
Account file path handling may differ

3. FindMyAccessory Stateful Objects

Impact: LOW (we don't use accessories)

Accessories are now stateful and state changes after each fetch.

Our Code Impact: Minimal - we primarily track AirTags via KeyPair, not FindMyAccessory objects.

4. No Direct .plist Support

Impact: LOW (we don't use .plist files)

Cannot load .plist files directly anymore - need conversion script.

Our Code Impact: None - we use KeyPair objects directly.

Code Changes Required

1. Account Management Changes

File: services/tracker_fetcher/taskiq_service.py - AppleAccountManager class

Current Code (0.8.0)

def get_account(self) -> AsyncAppleAccount:
    if not self.anisette_server:
        raise ValueError("ANISETTE_SERVER not configured")

    if self.account_store_path.exists():
        account = AsyncAppleAccount.from_json(str(self.account_store_path))
    else:
        raise FileNotFoundError("No stored Apple account credentials found")

    return account

Likely Changes Needed (0.9.3)

Research the 0.9.3 documentation to determine:

Is AsyncAppleAccount.from_json() still the correct method?
Does initialization require passing Anisette provider?
How does the new account format work?

Action Items:

Review 0.9.3 documentation for AsyncAppleAccount initialization
Update get_account() method
Test account creation and restoration
Handle migration from old account.json format

2. Fetch Reports Changes

File: services/tracker_fetcher/taskiq_service.py - _make_batch_api_call method

Current Code (0.8.0)

batch_reports = await self.apple_account.fetch_reports(keys, date_from_utc, date_to_utc)

Potential Changes

The method signature might still be the same, but:

Return value structure may differ
Error handling may need updates
Response processing may differ

Action Items:

Verify fetch_reports() method signature in 0.9.3
Check return value structure
Test with single key
Test with multiple keys (batch)
Verify error handling

3. Location Report Processing

File: services/tracker_fetcher/taskiq_service.py - _process_tracker_reports method

What to Check

Report attributes - Verify these still exist:
report.timestamp
report.latitude
report.longitude
report.confidence
report.horizontal_accuracy
Decryption - Check if reports are:
Already decrypted by library
Need manual decryption
Have different encryption flow

Action Items:

Verify LocationReport object attributes
Test report decryption
Verify GPS coordinate extraction
Test database insertion

Detailed Upgrade Process

Phase 1: Preparation (30 minutes)

Create Feature Branch

git checkout main
git pull origin main
git checkout -b upgrade-findmy-0.9.3

Backup Current State

# Backup account.json
cp services/data/account.json services/data/account.json.0.8.0.backup

# Backup current pyproject.toml
cp pyproject.toml pyproject.toml.0.8.0.backup

Document Current Behavior

# Run a test fetch and save logs
docker compose logs tracker-fetcher-worker-dev > logs-0.8.0-baseline.txt

Phase 2: Library Update (15 minutes)

Update pyproject.toml

# Change from:
"findmy==0.8.0",

# To:
"findmy==0.9.3",

Update Dependencies

uv sync

Rebuild Docker Containers

docker compose build tracker-fetcher-worker-dev

Phase 3: Code Updates (4-6 hours)

Research 0.9.3 API Changes
Read FindMy.py 0.9.0 documentation
Review PR #144 changes
Check example scripts in 0.9.3 release
Update AppleAccountManager
Modify get_account() for new format
Test account loading
Handle initialization changes
Update Tracker Fetcher
Review fetch_reports() usage
Update response processing if needed
Test single tracker fetch
Test batch tracker fetch
Test Location Report Processing
Verify report attributes
Test GPS extraction
Test database insertion

Phase 4: Re-Authentication (15 minutes)

CRITICAL: Old account.json will not work!

Remove Old Account File

rm services/data/account.json

Re-Authenticate

docker compose run --rm dev python scripts/authenticate_findmy.py

Verify New Account File

# Check that new account.json was created
ls -lh services/data/account.json

# Optionally inspect structure (be careful with credentials!)
# jq '.' services/data/account.json

Phase 5: Testing (2-4 hours)

Use the testing checklist below.

Phase 6: Deployment (1 hour)

Commit Changes

git add .
git commit -m "Upgrade FindMy.py from 0.8.0 to 0.9.3"
git push origin upgrade-findmy-0.9.3

Create Pull Request
Document all changes made
Include test results
Note any breaking changes
Deploy to Staging First

# On staging server
git fetch origin
git checkout upgrade-findmy-0.9.3
docker compose build
docker compose up -d

Monitor Staging
Watch logs for 24 hours
Verify location reports being stored
Check for any errors
Deploy to Production
Only after successful staging verification
Deploy during low-traffic period
Monitor closely

Testing Checklist

Unit Tests

Test account initialization
Test account restoration from JSON
Test KeyPair creation
Test report fetching (mocked)

Integration Tests

End-to-End Test

Run full tracker fetch cycle
Verify reports stored in database
Check report count matches expected
Verify GPS coordinates on map
Check log output for errors

Performance Test

Measure fetch time for 50 trackers
Compare to 0.8.0 baseline
Check memory usage
Check CPU usage

Rollback Plan

If Issues Found During Testing

Switch Back to 0.8.0 Branch

git checkout revert-to-findmy-0.8.0
docker compose build tracker-fetcher-worker-dev
docker compose up -d tracker-fetcher-worker-dev

Restore Old Account File

cp services/data/account.json.0.8.0.backup services/data/account.json

Verify Working

docker compose logs -f tracker-fetcher-worker-dev
# Watch for successful location report storage

If Issues Found in Production

Immediate Rollback

git checkout revert-to-findmy-0.8.0
docker compose build
docker compose up -d

Restore Account File

cp services/data/account.json.0.8.0.backup services/data/account.json

Monitor Recovery
Check logs for successful operation
Verify reports being stored
Alert team when stable
Post-Mortem
Document what went wrong
Identify gaps in testing
Plan fixes before retry

Risk Mitigation

Pre-Upgrade Risks

Risk	Likelihood	Impact	Mitigation
Account JSON incompatibility	High	High	Backup account.json, have re-auth procedure ready
API changes break code	Medium	High	Thorough testing in dev, gradual rollout
Performance degradation	Low	Medium	Performance testing, monitoring
Data loss	Very Low	Critical	Database backups before deployment

During Upgrade Risks

Risk	Likelihood	Impact	Mitigation
Failed re-authentication	Medium	High	Have Apple account credentials ready
Incomplete code changes	Medium	High	Follow checklist, peer review
Test environment differs from prod	Low	Medium	Use staging environment

Post-Upgrade Risks

Risk	Likelihood	Impact	Mitigation
Delayed error discovery	Medium	Medium	Extended monitoring period
Production issues	Low	High	Quick rollback plan, team availability

Success Criteria

The upgrade is considered successful when:

✅ All tests pass
✅ Location reports being stored successfully
✅ GPS coordinates are accurate
✅ Performance is equal or better than 0.8.0
✅ No errors in logs for 24 hours
✅ Database queries return expected data
✅ Team confirms system stable

Resources

Documentation

Example Code

Check the examples directory in FindMy.py 0.9.3 for updated usage patterns.

Support

FindMy.py GitHub Issues
FindMy.py Discord Server

Timeline Estimate

Phase	Duration	Dependencies
Preparation	30 min	None
Library Update	15 min	Preparation complete
Code Research	2 hours	Library updated
Code Changes	4-6 hours	Research complete
Re-authentication	15 min	Code changes complete
Testing	2-4 hours	All changes complete
Staging Deployment	1 hour	Tests passing
Staging Monitoring	24 hours	Deployed to staging
Production Deployment	1 hour	Staging verified
Total	1-2 days	-

Next Steps

Review this document with the team
Schedule upgrade when team has 1-2 days available
Prepare staging environment if not already available
Ensure backups are in place
Have rollback plan ready
Begin Phase 1 when ready

Notes

This is a living document - update as you learn more during the upgrade
Keep the 0.8.0 branch available indefinitely as a safety net
Document any surprises or gotchas encountered during upgrade
Share learnings with the team

Document Version: 1.0 Last Updated: 2025-10-28 Owner: Development Team Status: Planning