lcp-reference-platform 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,309 @@
1
+ """Declarative publisher form mapping and normalization.
2
+
3
+ Publisher systems are allowed to be messy; the LCP wire contract is not. This
4
+ module keeps source-specific mapping in versioned data rather than executable
5
+ callbacks. Only a small allowlisted transform set is supported so an operator
6
+ cannot accidentally turn a mapping file into an arbitrary code execution
7
+ surface.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from copy import deepcopy
13
+ from datetime import datetime, timezone
14
+ import hashlib
15
+ import json
16
+ import re
17
+ from typing import Any, Mapping
18
+
19
+ from .messages import _envelope
20
+ from .storage import now_iso
21
+
22
+
23
+ class MappingError(ValueError):
24
+ """Raised when a mapping cannot safely normalize a source record."""
25
+
26
+
27
+ _SUPPORTED_TRANSFORMS = {
28
+ "trim",
29
+ "lower",
30
+ "upper",
31
+ "string",
32
+ "integer",
33
+ "boolean",
34
+ "e164",
35
+ "date_time",
36
+ }
37
+ _COUNTRY_CALLING_CODES = {
38
+ "AU": "61",
39
+ "CA": "1",
40
+ "GB": "44",
41
+ "NZ": "64",
42
+ "US": "1",
43
+ }
44
+
45
+
46
+ def source_digest(source_record: Mapping[str, Any]) -> str:
47
+ """Return a stable audit digest without retaining the source payload."""
48
+ encoded = json.dumps(source_record, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
49
+ return hashlib.sha256(encoded.encode("utf-8")).hexdigest()
50
+
51
+
52
+ def _get_path(value: Mapping[str, Any], path: str) -> Any:
53
+ current: Any = value
54
+ for part in path.split("."):
55
+ if isinstance(current, Mapping) and part in current:
56
+ current = current[part]
57
+ elif isinstance(current, list) and part.isdigit() and int(part) < len(current):
58
+ current = current[int(part)]
59
+ else:
60
+ return None
61
+ return current
62
+
63
+
64
+ def _set_path(target: dict[str, Any], path: str, value: Any) -> None:
65
+ parts = path.removeprefix("payload.").split(".")
66
+ current = target
67
+ for part in parts[:-1]:
68
+ child = current.get(part)
69
+ if not isinstance(child, dict):
70
+ child = {}
71
+ current[part] = child
72
+ current = child
73
+ current[parts[-1]] = value
74
+
75
+
76
+ def _normalize_e164(value: Any, country_code: str | None) -> str:
77
+ if not isinstance(value, str):
78
+ raise MappingError("phone value must be a string")
79
+ raw = value.strip()
80
+ if raw.startswith("+"):
81
+ digits = "+" + re.sub(r"[^0-9]", "", raw[1:])
82
+ else:
83
+ digits = re.sub(r"[^0-9]", "", raw)
84
+ calling_code = _COUNTRY_CALLING_CODES.get(country_code or "")
85
+ if not calling_code:
86
+ raise MappingError("a country_code is required to normalize a non-E.164 phone")
87
+ digits = digits.removeprefix("0")
88
+ digits = "+" + calling_code + digits
89
+ if not re.fullmatch(r"\+[1-9]\d{1,14}", digits):
90
+ raise MappingError("phone could not be normalized to E.164")
91
+ return digits
92
+
93
+
94
+ def _normalize_value(value: Any, transform: str | None, *, country_code: str | None) -> Any:
95
+ if value is None or transform is None:
96
+ return value
97
+ if transform not in _SUPPORTED_TRANSFORMS:
98
+ raise MappingError(f"unsupported mapping transform: {transform}")
99
+ if transform == "trim":
100
+ return value.strip() if isinstance(value, str) else value
101
+ if transform == "lower":
102
+ return value.lower() if isinstance(value, str) else value
103
+ if transform == "upper":
104
+ return value.upper() if isinstance(value, str) else value
105
+ if transform == "string":
106
+ return str(value)
107
+ if transform == "integer":
108
+ try:
109
+ return int(value)
110
+ except (TypeError, ValueError) as exc:
111
+ raise MappingError(f"value {value!r} is not an integer") from exc
112
+ if transform == "boolean":
113
+ if isinstance(value, bool):
114
+ return value
115
+ if isinstance(value, str) and value.strip().lower() in {"true", "yes", "y", "1", "on"}:
116
+ return True
117
+ if isinstance(value, str) and value.strip().lower() in {"false", "no", "n", "0", "off"}:
118
+ return False
119
+ if isinstance(value, (int, float)) and value in {0, 1}:
120
+ return bool(value)
121
+ raise MappingError(f"value {value!r} is not a boolean")
122
+ if transform == "e164":
123
+ return _normalize_e164(value, country_code)
124
+ if transform == "date_time":
125
+ if not isinstance(value, str):
126
+ raise MappingError("date_time values must be strings")
127
+ try:
128
+ parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
129
+ except ValueError as exc:
130
+ raise MappingError(f"invalid date-time value: {value!r}") from exc
131
+ if parsed.tzinfo is None:
132
+ parsed = parsed.replace(tzinfo=timezone.utc)
133
+ return parsed.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
134
+ return value
135
+
136
+
137
+ class MappingRegistry:
138
+ """In-memory registry for versioned publisher/form mapping documents."""
139
+
140
+ def __init__(self, mappings: list[dict[str, Any]] | None = None):
141
+ self._mappings: dict[tuple[str, str, str], dict[str, Any]] = {}
142
+ for mapping in mappings or []:
143
+ self.register(mapping)
144
+
145
+ @classmethod
146
+ def from_json(cls, document: Mapping[str, Any] | list[Mapping[str, Any]]) -> "MappingRegistry":
147
+ if isinstance(document, list):
148
+ values = document
149
+ elif isinstance(document, Mapping) and isinstance(document.get("mappings"), list):
150
+ values = document["mappings"]
151
+ elif isinstance(document, Mapping):
152
+ values = [document]
153
+ else:
154
+ raise MappingError("mapping document must be an object or mappings array")
155
+ return cls([dict(value) for value in values])
156
+
157
+ def register(self, mapping: Mapping[str, Any]) -> None:
158
+ required = ("mapping_id", "publisher_id", "form_key", "version", "vertical", "channel")
159
+ missing = [field for field in required if not mapping.get(field)]
160
+ if missing:
161
+ raise MappingError(f"mapping is missing required fields: {', '.join(missing)}")
162
+ if mapping["channel"] not in {"form", "chat", "click", "api", "agent", "referral", "call"}:
163
+ raise MappingError("mapping channel is not supported")
164
+ field_map = mapping.get("field_map", {})
165
+ if not isinstance(field_map, Mapping):
166
+ raise MappingError("field_map must be an object")
167
+ transforms = mapping.get("transforms", {})
168
+ if not isinstance(transforms, Mapping):
169
+ raise MappingError("transforms must be an object")
170
+ for transform in transforms.values():
171
+ if transform not in _SUPPORTED_TRANSFORMS:
172
+ raise MappingError(f"unsupported mapping transform: {transform}")
173
+ key = (str(mapping["publisher_id"]), str(mapping["form_key"]), str(mapping["version"]))
174
+ self._mappings[key] = deepcopy(dict(mapping))
175
+
176
+ def resolve(self, publisher_id: str, form_key: str, version: str | None = None) -> dict[str, Any]:
177
+ candidates = [
178
+ mapping
179
+ for (publisher, form, mapping_version), mapping in self._mappings.items()
180
+ if publisher == publisher_id
181
+ and form == form_key
182
+ and (version is None or mapping_version == version)
183
+ and mapping.get("active", True) is True
184
+ ]
185
+ if not candidates:
186
+ raise MappingError(f"no active mapping for {publisher_id}/{form_key}")
187
+ candidates.sort(key=lambda mapping: str(mapping["version"]), reverse=True)
188
+ return deepcopy(candidates[0])
189
+
190
+ def all(self) -> list[dict[str, Any]]:
191
+ return [deepcopy(value) for value in self._mappings.values()]
192
+
193
+
194
+ class PublisherNormalizer:
195
+ """Apply one registry mapping to a source record and build an LCP envelope."""
196
+
197
+ def normalize(
198
+ self,
199
+ source_record: Mapping[str, Any],
200
+ mapping: Mapping[str, Any],
201
+ *,
202
+ receiver_id: str,
203
+ test: bool = False,
204
+ ) -> dict[str, Any]:
205
+ mapping = dict(mapping)
206
+ field_map = mapping.get("field_map", {})
207
+ transforms = mapping.get("transforms", {})
208
+ value_maps = mapping.get("value_maps", {})
209
+ payload: dict[str, Any] = {}
210
+
211
+ country_code = mapping.get("country_code")
212
+ country_path = field_map.get("location.country_code")
213
+ if country_path:
214
+ country_code = _get_path(source_record, str(country_path)) or country_code
215
+ country_code = str(country_code).upper() if country_code else None
216
+
217
+ for target, source_spec in field_map.items():
218
+ if isinstance(source_spec, Mapping):
219
+ source_path = source_spec.get("path")
220
+ transform = source_spec.get("transform")
221
+ else:
222
+ source_path = source_spec
223
+ transform = transforms.get(target)
224
+ if not isinstance(source_path, str) or not source_path:
225
+ raise MappingError(f"field_map entry {target!r} must name a source path")
226
+ value = _get_path(source_record, source_path)
227
+ if value is None:
228
+ continue
229
+ value = _normalize_value(value, transform, country_code=country_code)
230
+ choices = value_maps.get(target)
231
+ if choices is not None:
232
+ if not isinstance(choices, Mapping):
233
+ raise MappingError(f"value_maps.{target} must be an object")
234
+ if isinstance(value, list):
235
+ value = [choices.get(str(item), item) for item in value]
236
+ else:
237
+ value = choices.get(str(value), value)
238
+ _set_path(payload, target, value)
239
+
240
+ constants = mapping.get("constants", {})
241
+ if not isinstance(constants, Mapping):
242
+ raise MappingError("constants must be an object")
243
+ for target, value in constants.items():
244
+ _set_path(payload, str(target), deepcopy(value))
245
+
246
+ attributes = payload.setdefault("attributes", {})
247
+ attributes.setdefault("vertical", mapping["vertical"])
248
+ attributes.setdefault("schema_version", mapping.get("schema_version", "1.0.0"))
249
+ if "lead_id" not in payload:
250
+ source_lead_id = _get_path(source_record, "lead_id") or _get_path(source_record, "id")
251
+ if source_lead_id is not None:
252
+ payload["lead_id"] = source_lead_id
253
+ if "external_id" not in payload:
254
+ source_external_id = _get_path(source_record, "external_id") or _get_path(source_record, "id")
255
+ if source_external_id is not None:
256
+ payload["external_id"] = source_external_id
257
+ payload.setdefault("status", "NEW")
258
+ payload.setdefault("channel", mapping["channel"])
259
+ if not payload.get("lead_id"):
260
+ raise MappingError("mapping must produce a stable lead_id from the source record")
261
+ if "submitted_at" not in payload:
262
+ payload["submitted_at"] = now_iso()
263
+
264
+ provenance = payload.setdefault("provenance", {})
265
+ provenance.setdefault("source_type", "publisher")
266
+ provenance.setdefault("source_id", mapping["publisher_id"])
267
+ provenance.setdefault("brand_id", mapping.get("brand_id", mapping["publisher_id"]))
268
+ provenance.setdefault("form_id", mapping["form_key"])
269
+ provenance.setdefault("flow_key", mapping["form_key"])
270
+ provenance.setdefault("received_at", now_iso())
271
+
272
+ otp = mapping.get("otp", {})
273
+ if otp:
274
+ if not isinstance(otp, Mapping):
275
+ raise MappingError("otp mapping must be an object")
276
+ verified = _get_path(source_record, str(otp.get("verified_path", ""))) if otp.get("verified_path") else None
277
+ if verified is not None:
278
+ verified = _normalize_value(verified, "boolean", country_code=country_code)
279
+ compliance = payload.setdefault("compliance", {})
280
+ compliance["otp_verified"] = verified
281
+ if verified:
282
+ otp_payload: dict[str, Any] = {}
283
+ for output, source_key in (
284
+ ("channel", "channel_path"),
285
+ ("verified_at", "verified_at_path"),
286
+ ("verified_value_hash", "value_hash_path"),
287
+ ("attempts", "attempts_path"),
288
+ ):
289
+ if otp.get(source_key):
290
+ value = _get_path(source_record, str(otp[source_key]))
291
+ if value is not None:
292
+ otp_payload[output] = value
293
+ if otp_payload:
294
+ compliance["otp"] = otp_payload
295
+ quality = payload.setdefault("lead_quality", {})
296
+ quality["verified_phone"] = otp.get("verified_field", "phone") == "phone"
297
+ quality.setdefault("verification", {})["phone_method"] = otp.get("method", "otp")
298
+ if otp_payload.get("verified_at"):
299
+ quality["verification"]["phone_verified_at"] = otp_payload["verified_at"]
300
+
301
+ message_type = "call" if mapping["channel"] == "call" else "lead"
302
+ return _envelope(
303
+ message_type,
304
+ str(mapping["publisher_id"]),
305
+ receiver_id,
306
+ payload,
307
+ idempotency_key=f"{mapping['publisher_id']}-{payload['lead_id']}-{mapping['version']}",
308
+ test=test,
309
+ )
@@ -0,0 +1,147 @@
1
+ """Deterministic buyer-offer matching."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass, field
6
+ from datetime import datetime, timezone
7
+ from typing import Any
8
+ from zoneinfo import ZoneInfo
9
+
10
+
11
+ _COMPLETENESS = {"minimal": 1, "standard": 2, "rich": 3}
12
+
13
+
14
+ @dataclass(frozen=True)
15
+ class MatchResult:
16
+ matched: bool
17
+ reasons: tuple[str, ...] = field(default_factory=tuple)
18
+
19
+
20
+ def _scrub_status(payload: dict[str, Any], scrub_type: str) -> str | None:
21
+ for scrub in payload.get("compliance", {}).get("scrubs", []):
22
+ if scrub.get("type") == scrub_type:
23
+ return scrub.get("result")
24
+ return None
25
+
26
+
27
+ def _verified(payload: dict[str, Any], field: str) -> bool:
28
+ quality = payload.get("lead_quality", {})
29
+ if quality.get(field) is True:
30
+ return True
31
+ verification = quality.get("verification", {})
32
+ return bool(verification.get(f"{field.removeprefix('verified_')}_verified_at"))
33
+
34
+
35
+ def _in_window(window: dict[str, Any], now: datetime) -> bool:
36
+ try:
37
+ local = now.astimezone(ZoneInfo(window["timezone"]))
38
+ except (KeyError, ValueError):
39
+ return False
40
+ day = local.strftime("%a").lower()[:3]
41
+ if day not in window.get("days", []):
42
+ return False
43
+ current = local.strftime("%H:%M")
44
+ start = window["available_from"]
45
+ end = window["available_to"]
46
+ if start <= end:
47
+ return start <= current <= end
48
+ return current >= start or current <= end
49
+
50
+
51
+ def offer_is_available(offer: dict[str, Any], now: datetime | None = None) -> MatchResult:
52
+ """Check active status and configured delivery windows."""
53
+ reasons: list[str] = []
54
+ if offer.get("active", True) is not True:
55
+ reasons.append("offer_inactive")
56
+ windows = offer.get("delivery_windows", [])
57
+ if windows:
58
+ current = now or datetime.now(timezone.utc)
59
+ if not any(_in_window(window, current) for window in windows):
60
+ reasons.append("outside_delivery_window")
61
+ return MatchResult(not reasons, tuple(reasons))
62
+
63
+
64
+ def match_offer(
65
+ offer: dict[str, Any],
66
+ payload: dict[str, Any],
67
+ *,
68
+ now: datetime | None = None,
69
+ sender_id: str | None = None,
70
+ ) -> MatchResult:
71
+ """Evaluate all standard offer predicates against a lead payload."""
72
+ reasons: list[str] = []
73
+ attributes = payload.get("attributes", {})
74
+ location = payload.get("location", {})
75
+ provenance = payload.get("provenance", {})
76
+ compliance = payload.get("compliance", {})
77
+ quality = payload.get("lead_quality", {})
78
+
79
+ available = offer_is_available(offer, now)
80
+ reasons.extend(available.reasons)
81
+
82
+ if attributes.get("vertical") != offer.get("vertical"):
83
+ reasons.append("vertical_mismatch")
84
+ allowed_publishers = offer.get("allowed_publisher_ids", [])
85
+ if allowed_publishers and sender_id not in allowed_publishers:
86
+ reasons.append("publisher_not_allowed")
87
+ allowed_brands = offer.get("allowed_brand_ids", [])
88
+ if allowed_brands and provenance.get("brand_id") not in allowed_brands:
89
+ reasons.append("brand_not_allowed")
90
+ if location.get("country_code") not in offer.get("countries", []):
91
+ reasons.append("country_not_supported")
92
+ if offer.get("state_regions") and location.get("state_region") not in offer["state_regions"]:
93
+ reasons.append("state_region_not_supported")
94
+ if offer.get("postal_codes") and location.get("postal_code") not in offer["postal_codes"]:
95
+ reasons.append("postal_code_not_supported")
96
+ if offer.get("channels") and payload.get("channel") not in offer["channels"]:
97
+ reasons.append("channel_not_supported")
98
+
99
+ source_type = provenance.get("source_type")
100
+ if source_type in offer.get("excluded_source_types", []):
101
+ reasons.append("source_type_excluded")
102
+ acquisition_method = provenance.get("acquisition_method")
103
+ if acquisition_method in offer.get("excluded_acquisition_methods", []):
104
+ reasons.append("acquisition_method_excluded")
105
+ if offer.get("reject_incentivized") and provenance.get("is_incentivized") is not False:
106
+ reasons.append("incentivized_lead")
107
+ if provenance.get("incentive_type") in offer.get("excluded_incentive_types", []):
108
+ reasons.append("incentive_type_excluded")
109
+
110
+ if offer.get("require_verified_phone") and not _verified(payload, "verified_phone"):
111
+ reasons.append("phone_not_verified")
112
+ if offer.get("require_verified_email") and not _verified(payload, "verified_email"):
113
+ reasons.append("email_not_verified")
114
+
115
+ if "max_spam_risk_score" in offer:
116
+ score = quality.get("spam_risk_score")
117
+ if not isinstance(score, int) or score > offer["max_spam_risk_score"]:
118
+ reasons.append("spam_risk_too_high")
119
+ if "min_data_completeness" in offer:
120
+ completeness = quality.get("data_completeness")
121
+ if _COMPLETENESS.get(completeness, 0) < _COMPLETENESS[offer["min_data_completeness"]]:
122
+ reasons.append("data_completeness_too_low")
123
+
124
+ for field, expected in offer.get("attribute_equals", {}).items():
125
+ if attributes.get(field) != expected:
126
+ reasons.append(f"attribute_{field}_mismatch")
127
+ for field, allowed in offer.get("attribute_in", {}).items():
128
+ if attributes.get(field) not in allowed:
129
+ reasons.append(f"attribute_{field}_not_allowed")
130
+
131
+ if offer.get("require_consent_evidence") and not compliance.get("consent_evidence"):
132
+ reasons.append("consent_evidence_missing")
133
+ if offer.get("reject_dnc_flagged") and _scrub_status(payload, "dnc_national") != "clean":
134
+ reasons.append("dnc_not_clean")
135
+ if offer.get("reject_litigator_flagged") and _scrub_status(payload, "litigator") != "clean":
136
+ reasons.append("litigator_not_clean")
137
+ if offer.get("reject_blacklist_flagged") and _scrub_status(payload, "blacklist") != "clean":
138
+ reasons.append("blacklist_not_clean")
139
+
140
+ # Claim-language evidence is intentionally fail-closed. A deployment may
141
+ # provide a namespaced evidence block without putting copy/PII in a ping.
142
+ if offer.get("excluded_claim_language") and not payload.get("extensions", {}).get(
143
+ "lcp.platform.claim_language"
144
+ ):
145
+ reasons.append("claim_language_evidence_missing")
146
+
147
+ return MatchResult(not reasons, tuple(reasons))