feat(users): backfill destination email via a second PATCH when handle differs

[michael-richey]

Summary

v2 user creation (POST /api/v2/users) derives the destination handle from the create-time email and does not accept handle directly. When a source user's handle isn't itself their email address, this leaves no way to make the destination handle match the source handle.

This PR adds a two-call create path for that case:

1. POST /api/v2/users with the source handle passed as the create-time email, so the destination derives a handle matching the source handle.
2. PATCH /api/v2/users/{id} to set the real source email.

When the source handle already equals the source email, create is unchanged (a single POST).

Behavior

• Handle differs from email → POST (email=handle) then PATCH (email=real email).
• Handle equals email, or handle/email missing → single POST, no PATCH.
• If the email-restoring PATCH fails, the created user (with the handle as a placeholder email) is persisted to state so the next run's diff routes it through the update path instead of re-attempting a create that now 409s on the already-taken handle.

Test plan

• POST uses handle as email, PATCH restores the real email
• No second call when handle already equals email
• PATCH failure persists partial state and still raises
• Existing v2 create/update payload and handle-mapping-key tests unaffected
• Full unit suite (tox -e py311)

[Copilot]

Pull request overview

Adds a two-step v2 user creation flow to preserve the source handle when it differs from the source email, by creating the user with email=handle and then PATCHing the real email afterward.

Changes:

• Extend Users.create_resource() to optionally do a follow-up PATCH to restore the real email when handle != email.
• Persist partially-created user state when the email-restoring PATCH fails to avoid re-creates that would 409 on the already-taken handle.
• Add unit tests covering the two-call flow, the no-op case when handle == email, and persistence on PATCH failure.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
datadog_sync/model/users.py	Implements conditional “email backfill” logic via a second PATCH and persists state on PATCH failure.
tests/unit/test_users.py	Adds tests validating POST/PATCH behavior, no-backfill behavior, and failure-state persistence.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.