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,265 @@
1
+ """LCP message builders used by the reference router."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from datetime import datetime, timedelta, timezone
6
+ import hashlib
7
+ import hmac
8
+ import json
9
+ from pathlib import Path
10
+ from typing import Any
11
+ from uuid import uuid4
12
+
13
+ from .auth import signature_for
14
+ from .storage import now_iso
15
+
16
+
17
+ def _envelope(
18
+ message_type: str,
19
+ sender_id: str,
20
+ receiver_id: str,
21
+ payload: dict[str, Any],
22
+ *,
23
+ correlation_id: str | None = None,
24
+ idempotency_key: str | None = None,
25
+ test: bool = False,
26
+ ) -> dict[str, Any]:
27
+ message_id = str(uuid4())
28
+ return {
29
+ "lcp": {
30
+ "version": "1.0.0",
31
+ "message": {
32
+ "id": message_id,
33
+ "type": message_type,
34
+ "timestamp": now_iso(),
35
+ "sender_id": sender_id,
36
+ "receiver_id": receiver_id,
37
+ "correlation_id": correlation_id,
38
+ "idempotency_key": idempotency_key or f"{sender_id}-{message_type}-{message_id}",
39
+ "test": test,
40
+ },
41
+ "payload": payload,
42
+ }
43
+ }
44
+
45
+
46
+ def build_ack(
47
+ original: dict[str, Any],
48
+ *,
49
+ sender_id: str,
50
+ status: str,
51
+ lead_id: str | None = None,
52
+ rejection_reason: str | None = None,
53
+ errors: list[dict[str, Any]] | None = None,
54
+ ) -> dict[str, Any]:
55
+ original_message = original["lcp"]["message"]
56
+ payload: dict[str, Any] = {
57
+ "original_message_id": original_message["id"],
58
+ "status": status,
59
+ }
60
+ if lead_id:
61
+ payload["lead_id"] = lead_id
62
+ if rejection_reason:
63
+ payload["rejection_reason"] = rejection_reason
64
+ if errors:
65
+ payload["errors"] = errors
66
+ return _envelope(
67
+ "ack",
68
+ sender_id,
69
+ original_message["sender_id"],
70
+ payload,
71
+ correlation_id=original_message["id"],
72
+ test=original_message.get("test", False),
73
+ )
74
+
75
+
76
+ def build_ping(
77
+ lead_envelope: dict[str, Any],
78
+ offer: dict[str, Any],
79
+ *,
80
+ platform_id: str,
81
+ buyer_secret: str,
82
+ ) -> tuple[dict[str, Any], str]:
83
+ lead_message = lead_envelope["lcp"]["message"]
84
+ lead = lead_envelope["lcp"]["payload"]
85
+ consumer = lead.get("consumer", {})
86
+ location = lead.get("location", {})
87
+ attributes = lead.get("attributes", {})
88
+ vertical = attributes.get("vertical", offer["vertical"])
89
+ phone = consumer.get("phone")
90
+ if phone:
91
+ phone_hash = hmac.new(
92
+ buyer_secret.encode(), phone.encode(), hashlib.sha256
93
+ ).hexdigest()
94
+ else:
95
+ phone_hash = consumer.get("phone_hash")
96
+ if not phone_hash:
97
+ raise ValueError("A routable lead must contain phone or phone_hash")
98
+
99
+ vertical_path = Path(__file__).resolve().parents[3] / "verticals" / f"{vertical}.json"
100
+ safe_attributes: dict[str, Any] = {}
101
+ if vertical_path.exists():
102
+ with vertical_path.open(encoding="utf-8") as handle:
103
+ vertical_schema = json.load(handle)
104
+ for name, definition in vertical_schema.get("properties", {}).items():
105
+ if name in {"vertical", "schema_version"}:
106
+ continue
107
+ if definition.get("ping_safe") is True and name in attributes:
108
+ safe_attributes[name] = attributes[name]
109
+
110
+ submitted_at = lead.get("submitted_at") or lead_message["timestamp"]
111
+ try:
112
+ submitted = datetime.fromisoformat(submitted_at.replace("Z", "+00:00"))
113
+ age_minutes = max(0, int((datetime.now(timezone.utc) - submitted).total_seconds() // 60))
114
+ except ValueError:
115
+ age_minutes = 0
116
+ expires_at = (
117
+ datetime.now(timezone.utc)
118
+ + timedelta(seconds=offer.get("ping_timeout_seconds", 30))
119
+ ).strftime("%Y-%m-%dT%H:%M:%SZ")
120
+ ping_id = f"ping_{uuid4().hex}"
121
+ reference = hashlib.sha256(
122
+ f"{lead['lead_id']}:{offer['offer_id']}".encode()
123
+ ).hexdigest()[:32]
124
+ payload: dict[str, Any] = {
125
+ "ping_id": ping_id,
126
+ "lead_reference": reference,
127
+ "publisher_id": lead_message["sender_id"],
128
+ "offer_id": offer["offer_id"],
129
+ "phone_hash": phone_hash,
130
+ "country_code": location["country_code"],
131
+ "vertical": vertical,
132
+ "lead_age_minutes": age_minutes,
133
+ "attributes": safe_attributes,
134
+ "compliance_flags": {
135
+ "consent": bool(lead.get("compliance", {}).get("consent_evidence")),
136
+ "otp_verified": bool(lead.get("compliance", {}).get("otp_verified")),
137
+ "dnc_checked": bool(lead.get("compliance", {}).get("dnc_checked")),
138
+ },
139
+ "quality_flags": {
140
+ "verified_phone": lead.get("lead_quality", {}).get("verified_phone", False),
141
+ "verified_email": lead.get("lead_quality", {}).get("verified_email", False),
142
+ "is_incentivized": lead.get("provenance", {}).get("is_incentivized", False),
143
+ "spam_risk_score": lead.get("lead_quality", {}).get("spam_risk_score", 100),
144
+ },
145
+ "floor_price_cents": offer["floor_price_cents"],
146
+ "currency": offer["currency"],
147
+ "exclusivity": lead.get("exclusivity", {}).get("exclusivity", "shared"),
148
+ "expires_at": expires_at,
149
+ }
150
+ if location.get("state_region"):
151
+ payload["state_region"] = location["state_region"]
152
+ if location.get("postal_code"):
153
+ payload["postal_code"] = location["postal_code"]
154
+ if lead.get("exclusivity", {}).get("max_buyers"):
155
+ payload["exclusivity"] = lead["exclusivity"]["exclusivity"]
156
+ return (
157
+ _envelope(
158
+ "ping",
159
+ platform_id,
160
+ offer["buyer_id"],
161
+ payload,
162
+ correlation_id=lead_message["id"],
163
+ idempotency_key=f"{platform_id}-ping-{ping_id}",
164
+ test=lead_message.get("test", False),
165
+ ),
166
+ expires_at,
167
+ )
168
+
169
+
170
+ def build_post(
171
+ lead_envelope: dict[str, Any],
172
+ offer: dict[str, Any],
173
+ *,
174
+ platform_id: str,
175
+ price_cents: int,
176
+ buyer_reference: str | None,
177
+ correlation_id: str,
178
+ ) -> dict[str, Any]:
179
+ lead = lead_envelope["lcp"]["payload"]
180
+ payload: dict[str, Any] = {
181
+ "lead_id": lead["lead_id"],
182
+ "delivered_at": now_iso(),
183
+ "submitted_at": lead.get("submitted_at", lead_envelope["lcp"]["message"]["timestamp"]),
184
+ "offer_id": offer["offer_id"],
185
+ "price_cents": price_cents,
186
+ "currency": offer["currency"],
187
+ "buyer_id": offer["buyer_id"],
188
+ "consumer": lead["consumer"],
189
+ "location": lead["location"],
190
+ "attributes": lead["attributes"],
191
+ }
192
+ for field in ("compliance", "provenance", "exclusivity", "attachments", "call"):
193
+ if field in lead:
194
+ payload[field] = lead[field]
195
+ if buyer_reference:
196
+ payload["buyer_reference"] = buyer_reference
197
+ payload["pricing"] = {
198
+ "floor_price_cents": offer["floor_price_cents"],
199
+ "final_price_cents": price_cents,
200
+ "price_guardrails": True,
201
+ "payable_definition": offer.get("payable_definition", "bilateral_definition"),
202
+ "payable_status": "pending",
203
+ }
204
+ payload["matched_preferences"] = {
205
+ "offer_id": offer["offer_id"],
206
+ "vertical": offer["vertical"],
207
+ "countries": offer["countries"],
208
+ }
209
+ return _envelope(
210
+ "post",
211
+ platform_id,
212
+ offer["buyer_id"],
213
+ payload,
214
+ correlation_id=correlation_id,
215
+ idempotency_key=f"{platform_id}-post-{lead['lead_id']}-{offer['offer_id']}",
216
+ test=lead_envelope["lcp"]["message"].get("test", False),
217
+ )
218
+
219
+
220
+ def build_event(
221
+ lead_id: str,
222
+ event_name: str,
223
+ *,
224
+ platform_id: str,
225
+ receiver_id: str,
226
+ correlation_id: str | None = None,
227
+ details: dict[str, Any] | None = None,
228
+ test: bool = False,
229
+ ) -> dict[str, Any]:
230
+ payload: dict[str, Any] = {
231
+ "lead_id": lead_id,
232
+ "event": event_name,
233
+ "timestamp": now_iso(),
234
+ }
235
+ if details:
236
+ payload["details"] = details
237
+ return _envelope(
238
+ "event",
239
+ platform_id,
240
+ receiver_id,
241
+ payload,
242
+ correlation_id=correlation_id,
243
+ test=test,
244
+ )
245
+
246
+
247
+ def webhook_headers(
248
+ envelope: dict[str, Any],
249
+ *,
250
+ secret: str,
251
+ timestamp: str | None = None,
252
+ ) -> tuple[bytes, dict[str, str]]:
253
+ body = json.dumps(envelope, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
254
+ message = envelope["lcp"]["message"]
255
+ timestamp = timestamp or now_iso()
256
+ idempotency_key = message["idempotency_key"]
257
+ return body, {
258
+ "Content-Type": "application/json",
259
+ "Accept": "application/json",
260
+ "X-LCP-Sender-Id": message["sender_id"],
261
+ "X-LCP-Timestamp": timestamp,
262
+ "X-LCP-Idempotency-Key": idempotency_key,
263
+ "X-LCP-Signature": signature_for(secret, timestamp, idempotency_key, body),
264
+ **({"X-LCP-Test": "true"} if message.get("test") else {}),
265
+ }
@@ -0,0 +1,235 @@
1
+ """Postgres backend for production deployments.
2
+
3
+ The platform deliberately keeps persistence behind the Store method boundary so
4
+ operators can use SQLite locally and Postgres in multi-node production.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from contextlib import contextmanager
10
+ from datetime import datetime, timedelta, timezone
11
+ import json
12
+ import sqlite3
13
+ from threading import RLock
14
+ from typing import Any, Iterator
15
+
16
+ from .crypto import EnvelopeCipher
17
+ from .storage import Store, now_iso
18
+
19
+
20
+ def _decode_text(value: Any) -> Any:
21
+ """Normalize psycopg binary text results across psycopg/libpq builds."""
22
+ if isinstance(value, memoryview):
23
+ value = value.tobytes()
24
+ if isinstance(value, bytes):
25
+ try:
26
+ return value.decode("utf-8")
27
+ except UnicodeDecodeError:
28
+ return value
29
+ return value
30
+
31
+
32
+ def _decoded_dict_row(cursor: Any):
33
+ if cursor.description is None:
34
+ return lambda values: values
35
+ names = [column.name for column in cursor.description]
36
+
37
+ def make_row(values: Any) -> dict[str, Any]:
38
+ return {name: _decode_text(value) for name, value in zip(names, values)}
39
+
40
+ return make_row
41
+
42
+
43
+ class _PostgresConnection:
44
+ def __init__(self, connection: Any):
45
+ self.raw = connection
46
+
47
+ @staticmethod
48
+ def _sql(sql: str) -> str:
49
+ return sql.replace("?", "%s")
50
+
51
+ def execute(self, sql: str, params: Any = None):
52
+ from psycopg.pq import TransactionStatus
53
+
54
+ statement = self._sql(sql)
55
+ # Reads execute in autocommit mode. Only create a savepoint when the
56
+ # caller is inside an explicit transaction; otherwise PostgreSQL
57
+ # rejects SAVEPOINT before the actual statement is run.
58
+ in_transaction = self.raw.info.transaction_status == TransactionStatus.INTRANS
59
+ if not in_transaction:
60
+ return self.raw.execute(statement, params or ())
61
+
62
+ # Savepoints keep a uniqueness error from poisoning the outer
63
+ # transaction, matching the SQLite store's IntegrityError behavior.
64
+ self.raw.execute("SAVEPOINT lcp_statement")
65
+ try:
66
+ cursor = self.raw.execute(statement, params or ())
67
+ except Exception as exc:
68
+ self.raw.execute("ROLLBACK TO SAVEPOINT lcp_statement")
69
+ self.raw.execute("RELEASE SAVEPOINT lcp_statement")
70
+ # Store methods intentionally catch sqlite3.IntegrityError for the
71
+ # SQLite backend. Translate only PostgreSQL unique violations;
72
+ # syntax, connection, and policy failures must remain visible.
73
+ if getattr(exc, "sqlstate", None) == "23505":
74
+ raise sqlite3.IntegrityError(str(exc)) from exc
75
+ raise
76
+ else:
77
+ self.raw.execute("RELEASE SAVEPOINT lcp_statement")
78
+ return cursor
79
+
80
+ def executescript(self, script: str) -> None:
81
+ for statement in script.split(";"):
82
+ statement = statement.strip()
83
+ if statement:
84
+ self.execute(statement)
85
+
86
+
87
+ class PostgresStore(Store):
88
+ """Postgres implementation of the platform Store contract.
89
+
90
+ A store instance is shared by the WSGI threads in one process and protects
91
+ its connection with a lock. Run multiple API processes and worker
92
+ processes, as shown in the Kubernetes example, for horizontal capacity.
93
+ """
94
+
95
+ def __init__(self, dsn: str, *, pii_encryption_key: str | bytes | None = None):
96
+ try:
97
+ import psycopg
98
+ except ImportError as exc:
99
+ raise RuntimeError(
100
+ "Postgres support requires the lcp-reference-platform[postgres] extra"
101
+ ) from exc
102
+ self.path = dsn
103
+ self._cipher = EnvelopeCipher(pii_encryption_key)
104
+ self._lock = RLock()
105
+ self._raw = psycopg.connect(dsn, row_factory=_decoded_dict_row)
106
+ # Store read methods use short implicit statements while write methods
107
+ # open explicit transactions. Autocommit prevents a standalone SELECT
108
+ # from poisoning the next explicit BEGIN on this shared connection.
109
+ self._raw.autocommit = True
110
+ self._connection = _PostgresConnection(self._raw)
111
+ self.initialize()
112
+
113
+ @contextmanager
114
+ def transaction(self) -> Iterator[_PostgresConnection]:
115
+ with self._lock:
116
+ # Use psycopg's transaction manager rather than issuing a bare
117
+ # BEGIN/COMMIT while autocommit is enabled. This keeps explicit
118
+ # transactions reliable after standalone read statements and
119
+ # preserves the savepoint behavior in _PostgresConnection.
120
+ with self._raw.transaction():
121
+ yield self._connection
122
+
123
+ def _migrate_sqlite_columns(self, db: _PostgresConnection) -> None:
124
+ db.execute(
125
+ "ALTER TABLE credentials ADD COLUMN IF NOT EXISTS tenant_id TEXT NOT NULL DEFAULT 'default'"
126
+ )
127
+ db.execute(
128
+ "ALTER TABLE credentials ADD COLUMN IF NOT EXISTS scopes_json TEXT NOT NULL DEFAULT '[\"*\"]'"
129
+ )
130
+ db.execute(
131
+ "ALTER TABLE leads ADD COLUMN IF NOT EXISTS tenant_id TEXT NOT NULL DEFAULT 'default'"
132
+ )
133
+ db.execute("ALTER TABLE deliveries ADD COLUMN IF NOT EXISTS lease_owner TEXT")
134
+ db.execute("ALTER TABLE deliveries ADD COLUMN IF NOT EXISTS lease_until TEXT")
135
+ db.execute("ALTER TABLE attachments ADD COLUMN IF NOT EXISTS residency TEXT NOT NULL DEFAULT 'TEST'")
136
+ db.execute("ALTER TABLE attachments ADD COLUMN IF NOT EXISTS scan_status TEXT NOT NULL DEFAULT 'not_scanned'")
137
+ db.execute("ALTER TABLE attachments ADD COLUMN IF NOT EXISTS scan_engine TEXT NOT NULL DEFAULT 'unknown'")
138
+ db.execute("ALTER TABLE attachments ADD COLUMN IF NOT EXISTS scanned_at TEXT NOT NULL DEFAULT ''")
139
+ db.execute("ALTER TABLE attachments ADD COLUMN IF NOT EXISTS encryption TEXT NOT NULL DEFAULT 'application_encrypted'")
140
+
141
+ def close(self) -> None:
142
+ with self._lock:
143
+ self._raw.close()
144
+
145
+ def list_offers(
146
+ self,
147
+ vertical: str | None = None,
148
+ *,
149
+ tenant_id: str | None = None,
150
+ active_only: bool = True,
151
+ ) -> list[dict[str, Any]]:
152
+ query = "SELECT offer_json FROM offers"
153
+ if active_only:
154
+ query += " WHERE active = 1"
155
+ query += " ORDER BY offer_id"
156
+ with self._lock:
157
+ rows = self._connection.execute(query, ()).fetchall()
158
+ offers = [json.loads(row["offer_json"]) for row in rows]
159
+ if vertical:
160
+ offers = [offer for offer in offers if offer.get("vertical") == vertical]
161
+ if tenant_id:
162
+ offers = [offer for offer in offers if offer.get("tenant_id") == tenant_id]
163
+ return offers
164
+
165
+ def claim_routing_jobs(
166
+ self,
167
+ worker_id: str,
168
+ *,
169
+ limit: int = 20,
170
+ lease_seconds: int = 60,
171
+ ) -> list[Any]:
172
+ current = datetime.now(timezone.utc)
173
+ now_value = current.strftime("%Y-%m-%dT%H:%M:%SZ")
174
+ lease_until = (current + timedelta(seconds=lease_seconds)).strftime(
175
+ "%Y-%m-%dT%H:%M:%SZ"
176
+ )
177
+ with self.transaction() as db:
178
+ rows = db.execute(
179
+ """
180
+ SELECT * FROM routing_jobs
181
+ WHERE status = 'PENDING'
182
+ OR (status = 'PROCESSING' AND lease_until <= ?)
183
+ ORDER BY created_at
184
+ LIMIT ?
185
+ FOR UPDATE SKIP LOCKED
186
+ """,
187
+ (now_value, limit),
188
+ ).fetchall()
189
+ for row in rows:
190
+ db.execute(
191
+ """
192
+ UPDATE routing_jobs
193
+ SET status = 'PROCESSING', attempts = attempts + 1,
194
+ lease_owner = ?, lease_until = ?, updated_at = ?
195
+ WHERE lead_id = ?
196
+ """,
197
+ (worker_id, lease_until, now_value, row["lead_id"]),
198
+ )
199
+ return rows
200
+
201
+ def claim_due_deliveries(
202
+ self,
203
+ worker_id: str,
204
+ *,
205
+ lease_seconds: int = 60,
206
+ at: str | None = None,
207
+ limit: int = 50,
208
+ ) -> list[Any]:
209
+ current = datetime.now(timezone.utc)
210
+ now_value = at or current.strftime("%Y-%m-%dT%H:%M:%SZ")
211
+ lease_until = (current + timedelta(seconds=lease_seconds)).strftime(
212
+ "%Y-%m-%dT%H:%M:%SZ"
213
+ )
214
+ with self.transaction() as db:
215
+ rows = db.execute(
216
+ """
217
+ SELECT * FROM deliveries
218
+ WHERE (status IN ('PENDING', 'RETRY') AND next_attempt_at <= ?)
219
+ OR (status = 'PROCESSING' AND lease_until <= ?)
220
+ ORDER BY next_attempt_at, created_at
221
+ LIMIT ?
222
+ FOR UPDATE SKIP LOCKED
223
+ """,
224
+ (now_value, now_value, limit),
225
+ ).fetchall()
226
+ for row in rows:
227
+ db.execute(
228
+ """
229
+ UPDATE deliveries
230
+ SET status = 'PROCESSING', lease_owner = ?, lease_until = ?, updated_at = ?
231
+ WHERE delivery_id = ?
232
+ """,
233
+ (worker_id, lease_until, now_value, row["delivery_id"]),
234
+ )
235
+ return rows