feat(conversions): offline conversion uploads + #43 fold (split 3/4 of #34)

[illia-sapryga]

Split 3/4 of #34 — conversion uploads (folds in #43)

Third of the split. Stacks on #51 (it extends the same conversion_actions.py module), so please merge after #51. Registers only its own two tools.

Tools

• draft_upload_call_conversions → UploadCallConversions
• draft_upload_enhanced_conversions_for_leads → UploadClickConversions with user_identifiers

Your six requirements — each implemented and verified

1. SHA-256 enforced on EC PII. The CSV carries raw Email/Phone/First/Last; the parser normalizes (email/name strip().lower(), phone → E.164) then SHA-256-hashes each field. The raw values are locals used only to compute the hash — the row that enters the plan holds only*_sha256 keys.
2. PII never in plan.changes / audit log. EC rows are hash-only. Call rows must keep the raw E.164 caller_id (Google requires it unhashed for call matching), so it lives in the plan for apply but is redacted at every audit boundary: _redact_changes_for_audit is applied at all three log_mutation call sites (dry-run/error/success) and in the dry-run response — call caller_id → +155***0142, and the EC hash blob is dropped from the audit trail entirely (only non-PII counters remain).
3. Apply uses previewed rows — no CSV re-read. Both _apply_* start from changes["rows"]; the CSV path is never stored in the plan.
4. Consent.consent={"ad_user_data","ad_personalization"} validated and mapped to ConsentStatusEnum on ClickConversion.consent / CallConversion.consent; absent → UNSPECIFIED.
5. _normalize_phone_e164 fixed — strips exactly one domestic trunk zero (not all), keeps Italy's leading zero (via the +-prefixed verbatim path), and maps 00… → +….
6. GAQL backslash-escaping — _gaql_escape applied in both _resolve_conversion_action_ids and _resolve_upload_clicks_action (so O'Brien Lead doesn't break the query). This is the fix you flagged in your feat(ads): asset extension tools + RSA update + conversion-action mgmt #34 notes; it lands here where the only by-name lookup lives.

#43 folded in (per your instruction)

• order_id dedup key (optional "Order ID" column → ClickConversion.order_id, backwards-compatible).
• success_count now counts only result rows with conversion_action populated — neutralizes the caller_id/user_identifiers echo-back that made the base always report ~100%. Applied to both call and EC paths.
• dedup_warnings[] carried verbatim, plus rows_with_order_id and sample_rows[].order_id.

Things I want your call on (flagging honestly)

1. This is a rewrite of the EC path, not a port. The base branch expected pre-hashed CSV columns and re-read the CSV at apply — both violate requirements Update commands and docs for campaign snapshots #1 and Add asset and customer_asset removal to remove_entity #3. I inverted it: raw PII in, hash at preview, apply from frozen rows. If any upstream export (e.g. a ServiceTitan export tool) emits pre-hashed columns, we'd need to reconcile the CSV contract.
2. Bare national EC phone edge. For call conversions Google rejects a non-E.164 caller_id as a per-row failure. For EC (hashed), a bare national number with no country code would hash to a value Google can't match — silently. The normalizer is conservative (only adds + when it can infer one) and documented; recommend the EC CSV require international/E.164 phones. Happy to add a per-row warning/skip if you'd prefer.
3. Duplicate helpers._normalize_phone_e164 and _gaql_escape now exist in both write.py (from split (a)) and conversion_actions.py (here). They have different signatures — worth consolidating to one shared helper when the splits land.
4. Plan store holds raw caller_id. Audit redaction covers the log, but the persistent plan store (hosted set_plan_store) would hold raw phone between draft and apply. If that store persists to disk/DB, it's a raw-PII-at-rest surface the audit redaction doesn't cover — flagging for the hosted deployment.

Tests & hygiene

• 513 passing (+63), including end-to-end dry-run assertions that raw email/phone are absent from the audit file, the redacted form is present, and success_count is realistic under 0%/partial/full match.
• PII scrubbed — fixtures use user@example.com, +15555550142, Test User.

Next: (d) RSA update, folding #42 with the corrected learning-reset warning.

https://claude.ai/code/session_01FKcPiYrtXWtg4b7dnW4o5s

[kLOsk]

Reviewed at last — sorry for the delay, and this is the most carefully built of the four.

Verified against the diff:

• SHA-256 enforced on the enhanced-conversion identifiers; normalization before hashing; the row entering the plan holds only *_sha256 keys.
• caller_id kept raw with the reason stated in the module docstring, plus _redact_caller_id for the audit and preview surfaces. That is the correct call: Google will not match a hashed caller ID, so the alternative is a tool that does not work.
• Apply uses the previewed rows rather than re-reading the CSV, as asked.
• 100 new tests, CI green, both tools carry toolset tags=.

Holding this one briefly, for a reason on my side rather than yours.

AdLoop Cloud deploys by cloning adloop@main, so anything merged here reaches the hosted runtime on its next deploy. In Cloud a pending plan persists to Postgres until it is applied or expires, which means raw E.164 phone numbers would start living in our database. Our data processing agreement enumerates what we store — tokens, account identifiers, audit entries, usage counters — and end-customer contact data is not on that list.

So merging this obliges a DPA update and a 30-day notice to customers before it can ship hosted. That is entirely our problem, caused by our deployment shape, not by anything in your code. It happens that we owe customers a terms notice anyway, so the fix is to fold the data-category change into that same notice rather than send a second one.

Concretely: #51 is merged, #52 stays open for about a week while that goes out, then it merges unchanged. Nothing for you to do, and nothing here needs rewriting.

Worth saying plainly: the fact that this is the PR with a legal consequence attached is a compliment to it. You built the hashing, the redaction and the consent handling carefully enough that the remaining question is about where our database sits, not about whether the data is handled properly.