epic-2/story-2: Support Revenue Data and Tracking Payload Construction by usmanabbas7 · Pull Request #30 · convertcom/python-sdk

usmanabbas7 · 2026-06-07T12:43:57Z

Summary

Extends Story 2.1's tracking slice with revenue + conversion attributes and owns raw outbound payload assembly (tracking/payloads.py) matching the verbose JS-SDK wire contract. Stops before batching/dedup/queue/flush/network (Story 2.3/2.4 territory).

SDK-1 — extended ConversionEvent domain model (revenue, conversion_data, segments, bucketing attribution) + typed ConversionDataError for non-JSON-serializable conversion_data (AC feat(python-sdk): add api manager and event queue layer #3)
SDK-2 — Context.track_conversion(goal_key, revenue=None, conversion_data=None); attribution (segments + active variation assignments) computed at conversion time (AC feat(python-sdk): add deterministic bucketing and rule evaluation core #1, FR33/FR34)
SDK-3 — tracking/payloads.py: single owner of snake_case → verbose JS-SDK wire mapping. Envelope accountId/projectId/source/enrichData/visitors[].events[]; event data carries only goalId/goalData/bucketingData (AC feat(python-sdk): add in-memory config evaluation managers #2, FR35, NFR17/NFR21)
Review R1 fix — wire segments filtered to the JS VisitorSegments fixed-key allowlist so non-segment visitor traits don't leak into the payload (NFR21 parity)

Audit findings honored: F-001 (no goalKey/timestamp/conversionData in the wire event — ConversionEvent type per types.gen.ts:2502-2530), F-002 (enrichData computed from DataStore presence, not hardcoded; source: "js-sdk" fallback until python-sdk is confirmed in the backend allowlist).

Tests: 230 → 268 (+38), full suite green (uv run pytest).

Traceability

Part of sprint sprint/2026-04-06-convert-python-sdk — stacked on epic-2/story-1: Track Conversions from a Visitor Context #29 (story 2-1) → epic-1/story-3: Create and Reuse Visitor Contexts (gap-fill) #28 → epic-1/story-6: Deliver Quickstart and First-Run Examples #27 → epic-1/story-4: Run Local Experience Evaluations #26 → epic-1/story-2: Support sdkKey and Direct-Config Initialization #25 → Epic 1 Story 1: Scaffold the publishable SDK foundation #24
Beads: epic ai-driven-product-dev-q9p4; tasks -f05o (SDK-1), -se3u (SDK-2), -tg8a (SDK-3), -d2tg (R1 fix) — all closed
Conductor work dir: ai-driven-product-dev/work/2026-06-07-support-revenue-data-and-tracking-payload-construction/

Notes for reviewer

Readiness gate: PASS 9/10 with 4 auto-delegated questions (sprint mode): attribution computed on-demand from snapshot; source="js-sdk" fallback (F-002); computed enrichData (F-002); wire event field set per F-001. See conductor's readiness-assessment.md for details.
Code review: clean after round 2 (R1 found the VisitorSegments allowlist parity issue, fixed in 021044d).
Story file carries stale pre-audit prose (Task 3.3 goalKey/timestamp; Dev Notes source: python-sdk/enrichData: true) that contradicts the audit-patched AC feat(python-sdk): add in-memory config evaluation managers #2 / Task 3.2 — the patched text was followed.

🤖 Generated with Claude Code

gemini-code-assist

Code Review

This pull request implements Story 2.2 of the Convert Python SDK, extending the conversion tracking functionality to support optional revenue, custom conversion data, and visitor attribution context (active segments and variation assignments). It introduces the tracking/payloads.py module to map internal snake_case conversion events to the verbose JS-SDK wire contract, along with dedicated tracking error classes and comprehensive test coverage. The review feedback suggests several improvements: passing location_attributes through the conversion creation and bucketing evaluation pipeline to support location-targeted experiences, validating that conversion_data is a mapping to prevent potential AttributeErrors, and validating that revenue is a valid number (and not a boolean) to fail fast on programmer misuse.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

gemini-code-assist · 2026-06-07T12:45:32Z

        return create_conversion(
            self._snapshot,
            visitor_id=self._state.visitor_id,
            goal_key=goal_key,
+            revenue=revenue,
+            conversion_data=conversion_data,
+            visitor_attributes=self._state.visitor_attributes,
        )


To ensure that experiences with location-targeting rules are correctly evaluated and attributed at conversion time, the context's location_attributes should be passed to create_conversion.

Suggested change

return create_conversion(

self._snapshot,

visitor_id=self._state.visitor_id,

goal_key=goal_key,

revenue=revenue,

conversion_data=conversion_data,

visitor_attributes=self._state.visitor_attributes,

)

return create_conversion(

self._snapshot,

visitor_id=self._state.visitor_id,

goal_key=goal_key,

revenue=revenue,

conversion_data=conversion_data,

visitor_attributes=self._state.visitor_attributes,

location_attributes=self._location_attributes,

)

gemini-code-assist · 2026-06-07T12:45:32Z

+def _compute_bucketing_assignments(
+    snapshot: "ConfigSnapshot",
+    *,
+    visitor_id: str,
+    visitor_attributes: Optional[Mapping[str, Any]],
+) -> Dict[str, str]:


Add location_attributes to _compute_bucketing_assignments so that location-targeted experiences can be correctly evaluated.

def _compute_bucketing_assignments( snapshot: "ConfigSnapshot", *, visitor_id: str, visitor_attributes: Optional[Mapping[str, Any]], location_attributes: Optional[Mapping[str, Any]] = None, ) -> Dict[str, str]:

gemini-code-assist · 2026-06-07T12:45:32Z

+        result = select_experience(
+            str(key),
+            snapshot,
+            visitor_id=visitor_id,
+            visitor_attributes=visitor_attributes,
+        )


Pass location_attributes to select_experience to ensure location rules are evaluated during conversion-time bucketing attribution.

result = select_experience( str(key), snapshot, visitor_id=visitor_id, visitor_attributes=visitor_attributes, location_attributes=location_attributes, )

gemini-code-assist · 2026-06-07T12:45:32Z

 def create_conversion(
    snapshot: "ConfigSnapshot",
    *,
    visitor_id: str,
    goal_key: str,
+    revenue: Optional[float] = None,
+    conversion_data: Optional[Mapping[str, Any]] = None,
+    visitor_attributes: Optional[Mapping[str, Any]] = None,
 ) -> ConversionResult:


Add location_attributes to create_conversion signature to support passing location context from the visitor session.

def create_conversion( snapshot: "ConfigSnapshot", *, visitor_id: str, goal_key: str, revenue: Optional[float] = None, conversion_data: Optional[Mapping[str, Any]] = None, visitor_attributes: Optional[Mapping[str, Any]] = None, location_attributes: Optional[Mapping[str, Any]] = None, ) -> ConversionResult:

gemini-code-assist · 2026-06-07T12:45:32Z

+    bucketing_assignments = _compute_bucketing_assignments(
+        snapshot, visitor_id=visitor_id, visitor_attributes=visitor_attributes
+    )


Pass location_attributes to _compute_bucketing_assignments.

bucketing_assignments = _compute_bucketing_assignments( snapshot, visitor_id=visitor_id, visitor_attributes=visitor_attributes, location_attributes=location_attributes, )

gemini-code-assist · 2026-06-07T12:45:32Z

+    if not conversion_data:
+        return
+    for key, value in conversion_data.items():


Ensure conversion_data is a mapping before checking if it is empty or iterating over its items, to prevent unhandled AttributeError if a non-mapping (like a list or string) is passed.

Suggested change

if not conversion_data:

return

for key, value in conversion_data.items():

if conversion_data is None:

return

if not isinstance(conversion_data, Mapping):

raise ConversionDataError(

"conversion_data",

reason="value must be a dictionary/mapping",

)

if not conversion_data:

return

for key, value in conversion_data.items():

gemini-code-assist · 2026-06-07T12:45:32Z

+    # Fail fast on programmer misuse before any goal resolution (AC#3).
+    _validate_conversion_data(conversion_data)


Validate that revenue is a valid number (and not a boolean) to fail fast on programmer misuse, matching the documented behavior of ConversionDataError.

# Fail fast on programmer misuse before any goal resolution (AC#3). if revenue is not None and (not isinstance(revenue, (int, float)) or isinstance(revenue, bool)): raise ConversionDataError( "revenue", reason="value must be a number (int or float)", ) _validate_conversion_data(conversion_data)

Beads: ai-driven-product-dev-f05o Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

… implementation (GREEN) Beads: ai-driven-product-dev-f05o Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…tests (RED) Beads: ai-driven-product-dev-se3u Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…implementation (GREEN) Beads: ai-driven-product-dev-se3u Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Beads: ai-driven-product-dev-tg8a Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Beads: ai-driven-product-dev-d2tg Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

abbaseya · 2026-06-18T16:31:41Z

Superseded — all commits already in main (bc76b64). Closing without merge as part of post-sprint cleanup.

usmanabbas7 self-assigned this Jun 7, 2026

usmanabbas7 requested a review from clllaur June 7, 2026 12:43

gemini-code-assist Bot reviewed Jun 7, 2026

View reviewed changes

usmanabbas7 and others added 7 commits June 14, 2026 21:58

wf(rev22): [SDK-1] extended conversion domain + error — tests (RED)

b306058

Beads: ai-driven-product-dev-f05o Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

wf(rev22): [SDK-1] extended conversion domain + ConversionDataError —…

c8a02a3

… implementation (GREEN) Beads: ai-driven-product-dev-f05o Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

wf(rev22): [SDK-2] revenue + conversion_data + attribution service — …

8111826

…tests (RED) Beads: ai-driven-product-dev-se3u Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

wf(rev22): [SDK-2] revenue + conversion_data + attribution service — …

6a3b0c2

…implementation (GREEN) Beads: ai-driven-product-dev-se3u Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

wf(rev22): [SDK-3] outbound payload assembly — tests (RED)

4a3e155

Beads: ai-driven-product-dev-tg8a Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

wf(rev22): [SDK-3] outbound payload assembly — implementation (GREEN)

92405ea

Beads: ai-driven-product-dev-tg8a Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

wf(rev22): review R1 — filter wire segments to VisitorSegments allowlist

7cf6b2f

Beads: ai-driven-product-dev-d2tg Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

usmanabbas7 force-pushed the epic-2/story-1-track-conversions-from-a-visitor-context branch from e5af437 to 4c2b98b Compare June 14, 2026 16:58

usmanabbas7 force-pushed the epic-2/story-2-support-revenue-data-and-tracking-payload-construction branch from 021044d to 7cf6b2f Compare June 14, 2026 16:58

abbaseya closed this Jun 18, 2026

abbaseya deleted the epic-2/story-2-support-revenue-data-and-tracking-payload-construction branch June 18, 2026 16:31

Navigation Menu

Uh oh!

epic-2/story-2: Support Revenue Data and Tracking Payload Construction - #30

epic-2/story-2: Support Revenue Data and Tracking Payload Construction#30
usmanabbas7 wants to merge 7 commits into
epic-2/story-1-track-conversions-from-a-visitor-contextfrom
epic-2/story-2-support-revenue-data-and-tracking-payload-construction

usmanabbas7 commented Jun 7, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Jun 7, 2026

Uh oh!

gemini-code-assist Bot Jun 7, 2026

Uh oh!

gemini-code-assist Bot Jun 7, 2026

Uh oh!

gemini-code-assist Bot Jun 7, 2026

Uh oh!

gemini-code-assist Bot Jun 7, 2026

Uh oh!

gemini-code-assist Bot Jun 7, 2026

Uh oh!

gemini-code-assist Bot Jun 7, 2026

Uh oh!

abbaseya commented Jun 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

-    if not conversion_data:
-        return
-    for key, value in conversion_data.items():
+    if conversion_data is None:
+        return
+    if not isinstance(conversion_data, Mapping):
+        raise ConversionDataError(
+            "conversion_data",
+            reason="value must be a dictionary/mapping",
+        )
+    if not conversion_data:
+        return
+    for key, value in conversion_data.items():

		# Fail fast on programmer misuse before any goal resolution (AC#3).
		_validate_conversion_data(conversion_data)

Uh oh!

Conversation

usmanabbas7 commented Jun 7, 2026

Summary

Traceability

Notes for reviewer

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

abbaseya commented Jun 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants