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,1300 @@
1
+ """SQLite persistence for the reference LCP platform."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from contextlib import contextmanager
6
+ from datetime import datetime, timedelta, timezone
7
+ import hashlib
8
+ import json
9
+ from pathlib import Path
10
+ import sqlite3
11
+ from threading import RLock
12
+ from typing import Any, Iterator
13
+ from uuid import uuid4
14
+
15
+ from .api_keys import hash_api_key, verify_api_key
16
+ from .crypto import EnvelopeCipher
17
+
18
+
19
+ def now_iso() -> str:
20
+ return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
21
+
22
+
23
+ class Store:
24
+ """Thread-safe SQLite store with explicit transaction boundaries."""
25
+
26
+ def __init__(self, path: str | Path, *, pii_encryption_key: str | bytes | None = None):
27
+ self.path = Path(path)
28
+ self._cipher = EnvelopeCipher(pii_encryption_key)
29
+ if str(self.path) != ":memory:":
30
+ self.path.parent.mkdir(parents=True, exist_ok=True)
31
+ self._lock = RLock()
32
+ self._connection = sqlite3.connect(
33
+ str(self.path), check_same_thread=False, isolation_level=None
34
+ )
35
+ self._connection.row_factory = sqlite3.Row
36
+ self.initialize()
37
+
38
+ def close(self) -> None:
39
+ with self._lock:
40
+ self._connection.close()
41
+
42
+ def healthcheck(self) -> None:
43
+ with self._lock:
44
+ self._connection.execute("SELECT 1").fetchone()
45
+
46
+ def encode_envelope(self, envelope: dict[str, Any]) -> str:
47
+ return self._cipher.encode(envelope)
48
+
49
+ def decode_envelope(self, stored: str) -> dict[str, Any]:
50
+ return self._cipher.decode(stored)
51
+
52
+ @contextmanager
53
+ def transaction(self) -> Iterator[sqlite3.Connection]:
54
+ with self._lock:
55
+ self._connection.execute("BEGIN IMMEDIATE")
56
+ try:
57
+ yield self._connection
58
+ except Exception:
59
+ self._connection.rollback()
60
+ raise
61
+ else:
62
+ self._connection.commit()
63
+
64
+ def initialize(self) -> None:
65
+ with self.transaction() as db:
66
+ db.executescript(
67
+ """
68
+ CREATE TABLE IF NOT EXISTS credentials (
69
+ sender_id TEXT PRIMARY KEY,
70
+ tenant_id TEXT NOT NULL DEFAULT 'default',
71
+ scopes_json TEXT NOT NULL DEFAULT '["*"]',
72
+ hmac_secret TEXT,
73
+ previous_hmac_secret TEXT,
74
+ api_key_hash TEXT,
75
+ api_key_salt TEXT,
76
+ active INTEGER NOT NULL DEFAULT 1,
77
+ created_at TEXT NOT NULL,
78
+ updated_at TEXT NOT NULL
79
+ );
80
+ CREATE TABLE IF NOT EXISTS leads (
81
+ lead_id TEXT PRIMARY KEY,
82
+ tenant_id TEXT NOT NULL DEFAULT 'default',
83
+ message_id TEXT NOT NULL UNIQUE,
84
+ idempotency_key TEXT NOT NULL,
85
+ sender_id TEXT NOT NULL,
86
+ receiver_id TEXT NOT NULL,
87
+ message_type TEXT NOT NULL,
88
+ status TEXT NOT NULL,
89
+ test INTEGER NOT NULL DEFAULT 0,
90
+ vertical TEXT,
91
+ country_code TEXT,
92
+ envelope_json TEXT NOT NULL,
93
+ created_at TEXT NOT NULL,
94
+ updated_at TEXT NOT NULL,
95
+ UNIQUE(sender_id, idempotency_key)
96
+ );
97
+ CREATE TABLE IF NOT EXISTS offers (
98
+ offer_id TEXT PRIMARY KEY,
99
+ buyer_id TEXT NOT NULL,
100
+ active INTEGER NOT NULL DEFAULT 1,
101
+ offer_json TEXT NOT NULL,
102
+ created_at TEXT NOT NULL,
103
+ updated_at TEXT NOT NULL
104
+ );
105
+ CREATE TABLE IF NOT EXISTS publisher_mappings (
106
+ mapping_id TEXT NOT NULL,
107
+ publisher_id TEXT NOT NULL,
108
+ form_key TEXT NOT NULL,
109
+ version TEXT NOT NULL,
110
+ active INTEGER NOT NULL DEFAULT 1,
111
+ mapping_json TEXT NOT NULL,
112
+ created_at TEXT NOT NULL,
113
+ updated_at TEXT NOT NULL,
114
+ PRIMARY KEY (publisher_id, form_key, version)
115
+ );
116
+ CREATE TABLE IF NOT EXISTS mapping_applications (
117
+ application_id TEXT PRIMARY KEY,
118
+ mapping_id TEXT NOT NULL,
119
+ publisher_id TEXT NOT NULL,
120
+ form_key TEXT NOT NULL,
121
+ version TEXT NOT NULL,
122
+ source_record_id_hash TEXT,
123
+ lead_id TEXT NOT NULL,
124
+ source_digest TEXT NOT NULL,
125
+ created_at TEXT NOT NULL
126
+ );
127
+ CREATE TABLE IF NOT EXISTS attachments (
128
+ attachment_id TEXT PRIMARY KEY,
129
+ lead_id TEXT NOT NULL,
130
+ owner_id TEXT NOT NULL,
131
+ idempotency_key TEXT NOT NULL,
132
+ purpose TEXT NOT NULL,
133
+ filename TEXT NOT NULL,
134
+ content_type TEXT NOT NULL,
135
+ size_bytes INTEGER NOT NULL,
136
+ sha256 TEXT NOT NULL,
137
+ storage_ref TEXT NOT NULL,
138
+ status TEXT NOT NULL DEFAULT 'AVAILABLE',
139
+ residency TEXT NOT NULL DEFAULT 'TEST',
140
+ scan_status TEXT NOT NULL DEFAULT 'not_scanned',
141
+ scan_engine TEXT NOT NULL DEFAULT 'unknown',
142
+ scanned_at TEXT NOT NULL DEFAULT '',
143
+ encryption TEXT NOT NULL DEFAULT 'application_encrypted',
144
+ created_at TEXT NOT NULL,
145
+ updated_at TEXT NOT NULL,
146
+ UNIQUE(owner_id, idempotency_key)
147
+ );
148
+ CREATE TABLE IF NOT EXISTS payable_records (
149
+ payable_id TEXT PRIMARY KEY,
150
+ offer_id TEXT NOT NULL,
151
+ lead_id TEXT NOT NULL,
152
+ buyer_id TEXT NOT NULL,
153
+ month_key TEXT NOT NULL,
154
+ channel TEXT NOT NULL,
155
+ status TEXT NOT NULL,
156
+ price_cents INTEGER NOT NULL DEFAULT 0,
157
+ currency TEXT NOT NULL DEFAULT '',
158
+ reason TEXT,
159
+ call_seconds INTEGER,
160
+ created_at TEXT NOT NULL,
161
+ updated_at TEXT NOT NULL,
162
+ UNIQUE(offer_id, lead_id)
163
+ );
164
+ CREATE TABLE IF NOT EXISTS match_decisions (
165
+ decision_id TEXT PRIMARY KEY,
166
+ lead_id TEXT NOT NULL,
167
+ offer_id TEXT NOT NULL,
168
+ buyer_id TEXT NOT NULL,
169
+ matched INTEGER NOT NULL,
170
+ reasons_json TEXT NOT NULL,
171
+ created_at TEXT NOT NULL
172
+ );
173
+ CREATE TABLE IF NOT EXISTS pings (
174
+ ping_id TEXT PRIMARY KEY,
175
+ lead_id TEXT NOT NULL,
176
+ offer_id TEXT NOT NULL,
177
+ buyer_id TEXT NOT NULL,
178
+ message_id TEXT NOT NULL UNIQUE,
179
+ expires_at TEXT NOT NULL,
180
+ status TEXT NOT NULL,
181
+ envelope_json TEXT NOT NULL,
182
+ created_at TEXT NOT NULL,
183
+ updated_at TEXT NOT NULL
184
+ );
185
+ CREATE TABLE IF NOT EXISTS bids (
186
+ bid_id TEXT PRIMARY KEY,
187
+ ping_id TEXT NOT NULL,
188
+ lead_id TEXT NOT NULL,
189
+ offer_id TEXT NOT NULL,
190
+ buyer_id TEXT NOT NULL,
191
+ message_id TEXT NOT NULL UNIQUE,
192
+ decision TEXT NOT NULL,
193
+ bid_price_cents INTEGER NOT NULL,
194
+ currency TEXT NOT NULL,
195
+ estimated_contact_seconds INTEGER,
196
+ received_at TEXT NOT NULL,
197
+ envelope_json TEXT NOT NULL,
198
+ UNIQUE(ping_id, buyer_id)
199
+ );
200
+ CREATE TABLE IF NOT EXISTS deliveries (
201
+ delivery_id TEXT PRIMARY KEY,
202
+ lead_id TEXT NOT NULL,
203
+ ping_id TEXT,
204
+ offer_id TEXT NOT NULL,
205
+ buyer_id TEXT NOT NULL,
206
+ kind TEXT NOT NULL,
207
+ message_id TEXT NOT NULL UNIQUE,
208
+ idempotency_key TEXT NOT NULL,
209
+ webhook_url TEXT NOT NULL,
210
+ envelope_json TEXT NOT NULL,
211
+ status TEXT NOT NULL,
212
+ attempts INTEGER NOT NULL DEFAULT 0,
213
+ next_attempt_at TEXT NOT NULL,
214
+ last_error TEXT,
215
+ lease_owner TEXT,
216
+ lease_until TEXT,
217
+ created_at TEXT NOT NULL,
218
+ updated_at TEXT NOT NULL
219
+ );
220
+ CREATE TABLE IF NOT EXISTS lifecycle_events (
221
+ event_id TEXT PRIMARY KEY,
222
+ lead_id TEXT NOT NULL,
223
+ event_name TEXT NOT NULL,
224
+ timestamp TEXT NOT NULL,
225
+ envelope_json TEXT NOT NULL
226
+ );
227
+ CREATE TABLE IF NOT EXISTS routing_jobs (
228
+ lead_id TEXT PRIMARY KEY,
229
+ status TEXT NOT NULL DEFAULT 'PENDING',
230
+ attempts INTEGER NOT NULL DEFAULT 0,
231
+ lease_owner TEXT,
232
+ lease_until TEXT,
233
+ last_error TEXT,
234
+ created_at TEXT NOT NULL,
235
+ updated_at TEXT NOT NULL
236
+ );
237
+ CREATE TABLE IF NOT EXISTS rate_limits (
238
+ sender_id TEXT NOT NULL,
239
+ window_start TEXT NOT NULL,
240
+ request_count INTEGER NOT NULL,
241
+ PRIMARY KEY(sender_id, window_start)
242
+ );
243
+ CREATE TABLE IF NOT EXISTS audit_events (
244
+ audit_id TEXT PRIMARY KEY,
245
+ tenant_id TEXT NOT NULL,
246
+ actor_id TEXT NOT NULL,
247
+ action TEXT NOT NULL,
248
+ resource_type TEXT NOT NULL,
249
+ resource_id TEXT NOT NULL,
250
+ metadata_json TEXT NOT NULL,
251
+ created_at TEXT NOT NULL
252
+ );
253
+ CREATE INDEX IF NOT EXISTS idx_audit_resource
254
+ ON audit_events(resource_type, resource_id, created_at);
255
+ CREATE INDEX IF NOT EXISTS idx_match_decisions_lead
256
+ ON match_decisions(lead_id, created_at);
257
+ CREATE INDEX IF NOT EXISTS idx_deliveries_due
258
+ ON deliveries(status, next_attempt_at);
259
+ CREATE INDEX IF NOT EXISTS idx_pings_expiry
260
+ ON pings(status, expires_at);
261
+ CREATE INDEX IF NOT EXISTS idx_events_lead
262
+ ON lifecycle_events(lead_id, timestamp);
263
+ CREATE INDEX IF NOT EXISTS idx_mapping_applications_lead
264
+ ON mapping_applications(lead_id, created_at);
265
+ CREATE INDEX IF NOT EXISTS idx_attachments_lead
266
+ ON attachments(lead_id, created_at);
267
+ CREATE INDEX IF NOT EXISTS idx_payable_offer_month
268
+ ON payable_records(offer_id, month_key, status);
269
+ """
270
+ )
271
+ self._migrate_sqlite_columns(db)
272
+
273
+ def _migrate_sqlite_columns(self, db: sqlite3.Connection) -> None:
274
+ columns = {
275
+ row[1] for row in db.execute("PRAGMA table_info(credentials)").fetchall()
276
+ }
277
+ if "tenant_id" not in columns:
278
+ db.execute("ALTER TABLE credentials ADD COLUMN tenant_id TEXT NOT NULL DEFAULT 'default'")
279
+ if "scopes_json" not in columns:
280
+ db.execute("ALTER TABLE credentials ADD COLUMN scopes_json TEXT NOT NULL DEFAULT '[\"*\"]'")
281
+ if "api_key_salt" not in columns:
282
+ db.execute("ALTER TABLE credentials ADD COLUMN api_key_salt TEXT")
283
+ lead_columns = {
284
+ row[1] for row in db.execute("PRAGMA table_info(leads)").fetchall()
285
+ }
286
+ if "tenant_id" not in lead_columns:
287
+ db.execute("ALTER TABLE leads ADD COLUMN tenant_id TEXT NOT NULL DEFAULT 'default'")
288
+ delivery_columns = {
289
+ row[1] for row in db.execute("PRAGMA table_info(deliveries)").fetchall()
290
+ }
291
+ if "lease_owner" not in delivery_columns:
292
+ db.execute("ALTER TABLE deliveries ADD COLUMN lease_owner TEXT")
293
+ if "lease_until" not in delivery_columns:
294
+ db.execute("ALTER TABLE deliveries ADD COLUMN lease_until TEXT")
295
+ attachment_columns = {
296
+ row[1] for row in db.execute("PRAGMA table_info(attachments)").fetchall()
297
+ }
298
+ if "residency" not in attachment_columns:
299
+ db.execute("ALTER TABLE attachments ADD COLUMN residency TEXT NOT NULL DEFAULT 'TEST'")
300
+ if "scan_status" not in attachment_columns:
301
+ db.execute("ALTER TABLE attachments ADD COLUMN scan_status TEXT NOT NULL DEFAULT 'not_scanned'")
302
+ if "scan_engine" not in attachment_columns:
303
+ db.execute("ALTER TABLE attachments ADD COLUMN scan_engine TEXT NOT NULL DEFAULT 'unknown'")
304
+ if "scanned_at" not in attachment_columns:
305
+ db.execute("ALTER TABLE attachments ADD COLUMN scanned_at TEXT NOT NULL DEFAULT ''")
306
+ if "encryption" not in attachment_columns:
307
+ db.execute("ALTER TABLE attachments ADD COLUMN encryption TEXT NOT NULL DEFAULT 'application_encrypted'")
308
+
309
+ # ─── Credentials ──────────────────────────────────────────────────────
310
+
311
+ def upsert_credential(
312
+ self,
313
+ sender_id: str,
314
+ *,
315
+ tenant_id: str = "default",
316
+ scopes: list[str] | None = None,
317
+ hmac_secret: str | None = None,
318
+ previous_hmac_secret: str | None = None,
319
+ api_key: str | None = None,
320
+ active: bool = True,
321
+ ) -> None:
322
+ timestamp = now_iso()
323
+ api_key_hash = api_key_salt = None
324
+ if api_key:
325
+ api_key_salt, api_key_hash = hash_api_key(api_key)
326
+ with self.transaction() as db:
327
+ db.execute(
328
+ """
329
+ INSERT INTO credentials
330
+ (sender_id, tenant_id, scopes_json, hmac_secret, previous_hmac_secret, api_key_hash,
331
+ api_key_salt, active, created_at, updated_at)
332
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
333
+ ON CONFLICT(sender_id) DO UPDATE SET
334
+ tenant_id=excluded.tenant_id,
335
+ scopes_json=excluded.scopes_json,
336
+ hmac_secret=excluded.hmac_secret,
337
+ previous_hmac_secret=excluded.previous_hmac_secret,
338
+ api_key_hash=excluded.api_key_hash,
339
+ api_key_salt=excluded.api_key_salt,
340
+ active=excluded.active,
341
+ updated_at=excluded.updated_at
342
+ """,
343
+ (
344
+ sender_id,
345
+ tenant_id,
346
+ json.dumps(scopes if scopes is not None else ["*"]),
347
+ hmac_secret,
348
+ previous_hmac_secret,
349
+ api_key_hash,
350
+ api_key_salt,
351
+ int(active),
352
+ timestamp,
353
+ timestamp,
354
+ ),
355
+ )
356
+
357
+ def get_credential(self, sender_id: str) -> sqlite3.Row | None:
358
+ with self._lock:
359
+ return self._connection.execute(
360
+ "SELECT * FROM credentials WHERE sender_id = ? AND active = 1",
361
+ (sender_id,),
362
+ ).fetchone()
363
+
364
+ def find_sender_for_api_key(self, api_key: str) -> str | None:
365
+ # Every credential has its own random salt, so the digest cannot be
366
+ # matched with an indexed equality query; the credentials table is
367
+ # small in the reference platform and each candidate is verified with
368
+ # a constant-time comparison.
369
+ with self._lock:
370
+ rows = self._connection.execute(
371
+ "SELECT sender_id, api_key_hash, api_key_salt FROM credentials WHERE active = 1"
372
+ ).fetchall()
373
+ for row in rows:
374
+ if verify_api_key(api_key, row["api_key_salt"], row["api_key_hash"]):
375
+ return row["sender_id"]
376
+ return None
377
+
378
+ # ─── Audit ──────────────────────────────────────────────────────────────
379
+
380
+ def insert_audit(
381
+ self,
382
+ *,
383
+ tenant_id: str,
384
+ actor_id: str,
385
+ action: str,
386
+ resource_type: str,
387
+ resource_id: str,
388
+ metadata: dict[str, Any] | None = None,
389
+ ) -> None:
390
+ """Persist an audit record without storing consumer payloads or secrets."""
391
+ with self.transaction() as db:
392
+ db.execute(
393
+ """
394
+ INSERT INTO audit_events
395
+ (audit_id, tenant_id, actor_id, action, resource_type,
396
+ resource_id, metadata_json, created_at)
397
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?)
398
+ """,
399
+ (
400
+ f"audit_{uuid4().hex}",
401
+ tenant_id,
402
+ actor_id,
403
+ action,
404
+ resource_type,
405
+ resource_id,
406
+ json.dumps(metadata or {}, separators=(",", ":"), ensure_ascii=False),
407
+ now_iso(),
408
+ ),
409
+ )
410
+
411
+ def list_audit_events(self, resource_type: str, resource_id: str) -> list[dict[str, Any]]:
412
+ with self._lock:
413
+ rows = self._connection.execute(
414
+ """
415
+ SELECT * FROM audit_events
416
+ WHERE resource_type = ? AND resource_id = ?
417
+ ORDER BY created_at, audit_id
418
+ """,
419
+ (resource_type, resource_id),
420
+ ).fetchall()
421
+ return [
422
+ {
423
+ "tenant_id": row["tenant_id"],
424
+ "actor_id": row["actor_id"],
425
+ "action": row["action"],
426
+ "resource_type": row["resource_type"],
427
+ "resource_id": row["resource_id"],
428
+ "metadata": json.loads(row["metadata_json"]),
429
+ "created_at": row["created_at"],
430
+ }
431
+ for row in rows
432
+ ]
433
+
434
+ # ─── Publisher mappings ────────────────────────────────────────────────
435
+
436
+ def upsert_mapping(self, mapping: dict[str, Any]) -> None:
437
+ timestamp = now_iso()
438
+ with self.transaction() as db:
439
+ db.execute(
440
+ """
441
+ INSERT INTO publisher_mappings
442
+ (mapping_id, publisher_id, form_key, version, active, mapping_json, created_at, updated_at)
443
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?)
444
+ ON CONFLICT(publisher_id, form_key, version) DO UPDATE SET
445
+ mapping_id=excluded.mapping_id,
446
+ active=excluded.active,
447
+ mapping_json=excluded.mapping_json,
448
+ updated_at=excluded.updated_at
449
+ """,
450
+ (
451
+ mapping["mapping_id"], mapping["publisher_id"], mapping["form_key"],
452
+ mapping["version"], int(mapping.get("active", True)),
453
+ json.dumps(mapping, separators=(",", ":"), ensure_ascii=False), timestamp, timestamp,
454
+ ),
455
+ )
456
+
457
+ def list_mappings(self, publisher_id: str | None = None, *, active_only: bool = False) -> list[dict[str, Any]]:
458
+ query = "SELECT mapping_json FROM publisher_mappings"
459
+ clauses: list[str] = []
460
+ values: list[Any] = []
461
+ if publisher_id:
462
+ clauses.append("publisher_id = ?")
463
+ values.append(publisher_id)
464
+ if active_only:
465
+ clauses.append("active = 1")
466
+ if clauses:
467
+ query += " WHERE " + " AND ".join(clauses)
468
+ query += " ORDER BY publisher_id, form_key, version DESC"
469
+ with self._lock:
470
+ rows = self._connection.execute(query, values).fetchall()
471
+ return [json.loads(row["mapping_json"]) for row in rows]
472
+
473
+ def insert_mapping_application(
474
+ self,
475
+ *,
476
+ mapping: dict[str, Any],
477
+ source_record_id: str | None,
478
+ lead_id: str,
479
+ source_digest: str,
480
+ ) -> None:
481
+ with self.transaction() as db:
482
+ db.execute(
483
+ """
484
+ INSERT INTO mapping_applications
485
+ (application_id, mapping_id, publisher_id, form_key, version,
486
+ source_record_id_hash, lead_id, source_digest, created_at)
487
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
488
+ """,
489
+ (
490
+ f"mapapp_{uuid4().hex}", mapping["mapping_id"], mapping["publisher_id"],
491
+ mapping["form_key"], mapping["version"],
492
+ hashlib.sha256(source_record_id.encode("utf-8")).hexdigest() if source_record_id else None,
493
+ lead_id, source_digest, now_iso(),
494
+ ),
495
+ )
496
+
497
+ def list_mapping_applications(self, lead_id: str) -> list[dict[str, Any]]:
498
+ with self._lock:
499
+ rows = self._connection.execute(
500
+ "SELECT * FROM mapping_applications WHERE lead_id = ? ORDER BY created_at",
501
+ (lead_id,),
502
+ ).fetchall()
503
+ return [dict(row) for row in rows]
504
+
505
+ # ─── Rate limiting ─────────────────────────────────────────────────────
506
+
507
+ def consume_rate_limit(self, sender_id: str, *, limit: int, now: datetime | None = None) -> bool:
508
+ current = now or datetime.now(timezone.utc)
509
+ window_start = current.strftime("%Y-%m-%dT%H:%M:00Z")
510
+ with self.transaction() as db:
511
+ row = db.execute(
512
+ "SELECT request_count FROM rate_limits WHERE sender_id = ? AND window_start = ?",
513
+ (sender_id, window_start),
514
+ ).fetchone()
515
+ count = int(row["request_count"]) if row else 0
516
+ if count >= limit:
517
+ return False
518
+ if row:
519
+ db.execute(
520
+ "UPDATE rate_limits SET request_count = request_count + 1 WHERE sender_id = ? AND window_start = ?",
521
+ (sender_id, window_start),
522
+ )
523
+ else:
524
+ db.execute(
525
+ "INSERT INTO rate_limits(sender_id, window_start, request_count) VALUES (?, ?, 1)",
526
+ (sender_id, window_start),
527
+ )
528
+ return True
529
+
530
+ # ─── Attachments ──────────────────────────────────────────────────────
531
+
532
+ def get_attachment(self, attachment_id: str) -> sqlite3.Row | None:
533
+ with self._lock:
534
+ return self._connection.execute(
535
+ "SELECT * FROM attachments WHERE attachment_id = ?", (attachment_id,)
536
+ ).fetchone()
537
+
538
+ def get_attachment_by_idempotency(self, owner_id: str, idempotency_key: str) -> sqlite3.Row | None:
539
+ with self._lock:
540
+ return self._connection.execute(
541
+ "SELECT * FROM attachments WHERE owner_id = ? AND idempotency_key = ?",
542
+ (owner_id, idempotency_key),
543
+ ).fetchone()
544
+
545
+ def insert_attachment(self, metadata: dict[str, Any]) -> bool:
546
+ timestamp = now_iso()
547
+ with self.transaction() as db:
548
+ try:
549
+ db.execute(
550
+ """
551
+ INSERT INTO attachments
552
+ (attachment_id, lead_id, owner_id, idempotency_key, purpose,
553
+ filename, content_type, size_bytes, sha256, storage_ref,
554
+ status, residency, scan_status, scan_engine, scanned_at, encryption,
555
+ created_at, updated_at)
556
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'AVAILABLE', ?, ?, ?, ?, ?, ?, ?)
557
+ """,
558
+ (
559
+ metadata["attachment_id"], metadata["lead_id"], metadata["owner_id"],
560
+ metadata["idempotency_key"], metadata["purpose"], metadata["filename"],
561
+ metadata["content_type"], metadata["size_bytes"], metadata["sha256"],
562
+ metadata["storage_ref"], metadata.get("residency", "TEST"),
563
+ metadata.get("scan_status", "not_scanned"), metadata.get("scan_engine", "unknown"),
564
+ metadata.get("scanned_at", timestamp), metadata.get("encryption", "application_encrypted"),
565
+ timestamp, timestamp,
566
+ ),
567
+ )
568
+ except sqlite3.IntegrityError:
569
+ return False
570
+ return True
571
+
572
+ def list_attachments(self, lead_id: str) -> list[sqlite3.Row]:
573
+ with self._lock:
574
+ return self._connection.execute(
575
+ "SELECT * FROM attachments WHERE lead_id = ? ORDER BY created_at, attachment_id",
576
+ (lead_id,),
577
+ ).fetchall()
578
+
579
+ def mark_attachment_redacted(self, attachment_id: str) -> None:
580
+ with self.transaction() as db:
581
+ db.execute(
582
+ "UPDATE attachments SET status = 'REDACTED', updated_at = ? WHERE attachment_id = ?",
583
+ (now_iso(), attachment_id),
584
+ )
585
+
586
+ # ─── Leads ─────────────────────────────────────────────────────────────
587
+
588
+ def get_lead(self, lead_id: str) -> sqlite3.Row | None:
589
+ with self._lock:
590
+ return self._connection.execute(
591
+ "SELECT * FROM leads WHERE lead_id = ?", (lead_id,)
592
+ ).fetchone()
593
+
594
+ def get_lead_by_idempotency(self, sender_id: str, idempotency_key: str) -> sqlite3.Row | None:
595
+ with self._lock:
596
+ return self._connection.execute(
597
+ "SELECT * FROM leads WHERE sender_id = ? AND idempotency_key = ?",
598
+ (sender_id, idempotency_key),
599
+ ).fetchone()
600
+
601
+ def insert_lead(self, envelope: dict[str, Any], *, status: str, tenant_id: str = "default") -> bool:
602
+ message = envelope["lcp"]["message"]
603
+ payload = envelope["lcp"]["payload"]
604
+ lead_id = payload["lead_id"]
605
+ timestamp = now_iso()
606
+ with self.transaction() as db:
607
+ try:
608
+ db.execute(
609
+ """
610
+ INSERT INTO leads
611
+ (lead_id, tenant_id, message_id, idempotency_key, sender_id, receiver_id,
612
+ message_type, status, test, vertical, country_code,
613
+ envelope_json, created_at, updated_at)
614
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
615
+ """,
616
+ (
617
+ lead_id,
618
+ tenant_id,
619
+ message["id"],
620
+ message["idempotency_key"],
621
+ message["sender_id"],
622
+ message["receiver_id"],
623
+ message["type"],
624
+ status,
625
+ int(message.get("test", False)),
626
+ payload.get("attributes", {}).get("vertical"),
627
+ payload.get("location", {}).get("country_code"),
628
+ self.encode_envelope(envelope),
629
+ timestamp,
630
+ timestamp,
631
+ ),
632
+ )
633
+ db.execute(
634
+ """
635
+ INSERT INTO routing_jobs(lead_id, status, attempts, created_at, updated_at)
636
+ VALUES (?, 'PENDING', 0, ?, ?)
637
+ ON CONFLICT(lead_id) DO NOTHING
638
+ """,
639
+ (lead_id, timestamp, timestamp),
640
+ )
641
+ except sqlite3.IntegrityError:
642
+ return False
643
+ return True
644
+
645
+ def update_lead_status(self, lead_id: str, status: str) -> None:
646
+ with self.transaction() as db:
647
+ db.execute(
648
+ "UPDATE leads SET status = ?, updated_at = ? WHERE lead_id = ?",
649
+ (status, now_iso(), lead_id),
650
+ )
651
+
652
+ def routing_job_pending(self, lead_id: str) -> bool:
653
+ with self._lock:
654
+ row = self._connection.execute(
655
+ "SELECT status FROM routing_jobs WHERE lead_id = ?", (lead_id,)
656
+ ).fetchone()
657
+ return bool(row and row["status"] != "DONE")
658
+
659
+ def complete_routing_job(self, lead_id: str, worker_id: str | None = None) -> None:
660
+ with self.transaction() as db:
661
+ if worker_id:
662
+ db.execute(
663
+ """
664
+ UPDATE routing_jobs
665
+ SET status = 'DONE', updated_at = ?, lease_owner = NULL, lease_until = NULL
666
+ WHERE lead_id = ? AND lease_owner = ?
667
+ """,
668
+ (now_iso(), lead_id, worker_id),
669
+ )
670
+ else:
671
+ db.execute(
672
+ "UPDATE routing_jobs SET status = 'DONE', updated_at = ?, lease_owner = NULL, lease_until = NULL WHERE lead_id = ?",
673
+ (now_iso(), lead_id),
674
+ )
675
+
676
+ def claim_routing_jobs(self, worker_id: str, *, limit: int = 20, lease_seconds: int = 60) -> list[sqlite3.Row]:
677
+ current = datetime.now(timezone.utc)
678
+ now_value = current.strftime("%Y-%m-%dT%H:%M:%SZ")
679
+ lease_until = (current + timedelta(seconds=lease_seconds)).strftime("%Y-%m-%dT%H:%M:%SZ")
680
+ with self.transaction() as db:
681
+ rows = db.execute(
682
+ """
683
+ SELECT * FROM routing_jobs
684
+ WHERE (status = 'PENDING') OR (status = 'PROCESSING' AND lease_until <= ?)
685
+ ORDER BY created_at
686
+ LIMIT ?
687
+ """,
688
+ (now_value, limit),
689
+ ).fetchall()
690
+ for row in rows:
691
+ db.execute(
692
+ "UPDATE routing_jobs SET status = 'PROCESSING', attempts = attempts + 1, lease_owner = ?, lease_until = ?, updated_at = ? WHERE lead_id = ?",
693
+ (worker_id, lease_until, now_value, row["lead_id"]),
694
+ )
695
+ return rows
696
+
697
+ def release_routing_job(
698
+ self, lead_id: str, error: str, worker_id: str | None = None
699
+ ) -> None:
700
+ with self.transaction() as db:
701
+ if worker_id:
702
+ db.execute(
703
+ """
704
+ UPDATE routing_jobs
705
+ SET status = 'PENDING', last_error = ?, lease_owner = NULL,
706
+ lease_until = NULL, updated_at = ?
707
+ WHERE lead_id = ? AND lease_owner = ?
708
+ """,
709
+ (error[:500], now_iso(), lead_id, worker_id),
710
+ )
711
+ else:
712
+ db.execute(
713
+ "UPDATE routing_jobs SET status = 'PENDING', last_error = ?, lease_owner = NULL, lease_until = NULL, updated_at = ? WHERE lead_id = ?",
714
+ (error[:500], now_iso(), lead_id),
715
+ )
716
+
717
+ # ─── Offers ────────────────────────────────────────────────────────────
718
+
719
+ def upsert_offer(self, offer: dict[str, Any]) -> None:
720
+ timestamp = now_iso()
721
+ with self.transaction() as db:
722
+ db.execute(
723
+ """
724
+ INSERT INTO offers (offer_id, buyer_id, active, offer_json, created_at, updated_at)
725
+ VALUES (?, ?, ?, ?, ?, ?)
726
+ ON CONFLICT(offer_id) DO UPDATE SET
727
+ buyer_id=excluded.buyer_id,
728
+ active=excluded.active,
729
+ offer_json=excluded.offer_json,
730
+ updated_at=excluded.updated_at
731
+ """,
732
+ (
733
+ offer["offer_id"],
734
+ offer["buyer_id"],
735
+ int(offer.get("active", True)),
736
+ json.dumps(offer, separators=(",", ":"), ensure_ascii=False),
737
+ timestamp,
738
+ timestamp,
739
+ ),
740
+ )
741
+
742
+ def list_offers(
743
+ self,
744
+ vertical: str | None = None,
745
+ *,
746
+ tenant_id: str | None = None,
747
+ active_only: bool = True,
748
+ ) -> list[dict[str, Any]]:
749
+ query = "SELECT offer_json FROM offers"
750
+ clauses: list[str] = []
751
+ values: list[Any] = []
752
+ if active_only:
753
+ clauses.append("active = 1")
754
+ if vertical:
755
+ clauses.append("json_extract(offer_json, '$.vertical') = ?")
756
+ values.append(vertical)
757
+ if tenant_id:
758
+ clauses.append("json_extract(offer_json, '$.tenant_id') = ?")
759
+ values.append(tenant_id)
760
+ if clauses:
761
+ query += " WHERE " + " AND ".join(clauses)
762
+ query += " ORDER BY offer_id"
763
+ with self._lock:
764
+ rows = self._connection.execute(query, values).fetchall()
765
+ return [json.loads(row["offer_json"]) for row in rows]
766
+
767
+ def get_offer(self, offer_id: str) -> dict[str, Any] | None:
768
+ with self._lock:
769
+ row = self._connection.execute(
770
+ "SELECT offer_json FROM offers WHERE offer_id = ?", (offer_id,)
771
+ ).fetchone()
772
+ return json.loads(row["offer_json"]) if row else None
773
+
774
+ # ─── Match audit ───────────────────────────────────────────────────────
775
+
776
+ def insert_match_decision(
777
+ self,
778
+ *,
779
+ lead_id: str,
780
+ offer_id: str,
781
+ buyer_id: str,
782
+ matched: bool,
783
+ reasons: list[str] | tuple[str, ...],
784
+ ) -> None:
785
+ with self.transaction() as db:
786
+ db.execute(
787
+ """
788
+ INSERT INTO match_decisions
789
+ (decision_id, lead_id, offer_id, buyer_id, matched, reasons_json, created_at)
790
+ VALUES (?, ?, ?, ?, ?, ?, ?)
791
+ ON CONFLICT(decision_id) DO UPDATE SET
792
+ matched=excluded.matched,
793
+ reasons_json=excluded.reasons_json,
794
+ created_at=excluded.created_at
795
+ """,
796
+ (
797
+ f"{lead_id}:{offer_id}",
798
+ lead_id,
799
+ offer_id,
800
+ buyer_id,
801
+ int(matched),
802
+ json.dumps(list(reasons), separators=(",", ":")),
803
+ now_iso(),
804
+ ),
805
+ )
806
+
807
+ def list_match_decisions(self, lead_id: str) -> list[dict[str, Any]]:
808
+ with self._lock:
809
+ rows = self._connection.execute(
810
+ "SELECT * FROM match_decisions WHERE lead_id = ? ORDER BY created_at, offer_id",
811
+ (lead_id,),
812
+ ).fetchall()
813
+ return [
814
+ {
815
+ "offer_id": row["offer_id"],
816
+ "buyer_id": row["buyer_id"],
817
+ "matched": bool(row["matched"]),
818
+ "reasons": json.loads(row["reasons_json"]),
819
+ }
820
+ for row in rows
821
+ ]
822
+
823
+ # ─── Pings and bids ────────────────────────────────────────────────────
824
+
825
+ def has_ping_for_offer(self, lead_id: str, offer_id: str) -> bool:
826
+ with self._lock:
827
+ row = self._connection.execute(
828
+ "SELECT 1 FROM pings WHERE lead_id = ? AND offer_id = ? LIMIT 1",
829
+ (lead_id, offer_id),
830
+ ).fetchone()
831
+ return row is not None
832
+
833
+ def insert_ping(self, ping: dict[str, Any], *, lead_id: str, offer_id: str, buyer_id: str, expires_at: str) -> bool:
834
+ message = ping["lcp"]["message"]
835
+ ping_id = ping["lcp"]["payload"]["ping_id"]
836
+ timestamp = now_iso()
837
+ with self.transaction() as db:
838
+ cursor = db.execute(
839
+ """
840
+ INSERT INTO pings
841
+ (ping_id, lead_id, offer_id, buyer_id, message_id, expires_at,
842
+ status, envelope_json, created_at, updated_at)
843
+ VALUES (?, ?, ?, ?, ?, ?, 'OPEN', ?, ?, ?)
844
+ ON CONFLICT(message_id) DO NOTHING
845
+ """,
846
+ (
847
+ ping_id,
848
+ lead_id,
849
+ offer_id,
850
+ buyer_id,
851
+ message["id"],
852
+ expires_at,
853
+ self.encode_envelope(ping),
854
+ timestamp,
855
+ timestamp,
856
+ ),
857
+ )
858
+ return cursor.rowcount == 1
859
+
860
+ def get_ping(self, ping_id: str) -> sqlite3.Row | None:
861
+ with self._lock:
862
+ return self._connection.execute(
863
+ "SELECT * FROM pings WHERE ping_id = ?", (ping_id,)
864
+ ).fetchone()
865
+
866
+ def list_open_pings(self, lead_id: str) -> list[sqlite3.Row]:
867
+ with self._lock:
868
+ return self._connection.execute(
869
+ "SELECT * FROM pings WHERE lead_id = ? AND status = 'OPEN' ORDER BY ping_id",
870
+ (lead_id,),
871
+ ).fetchall()
872
+
873
+ def list_pings(self, lead_id: str) -> list[sqlite3.Row]:
874
+ with self._lock:
875
+ return self._connection.execute(
876
+ "SELECT * FROM pings WHERE lead_id = ? ORDER BY created_at, ping_id",
877
+ (lead_id,),
878
+ ).fetchall()
879
+
880
+ def list_expired_open_pings(self, at: str | None = None) -> list[sqlite3.Row]:
881
+ with self._lock:
882
+ return self._connection.execute(
883
+ """
884
+ SELECT * FROM pings
885
+ WHERE status = 'OPEN' AND expires_at <= ?
886
+ ORDER BY expires_at, ping_id
887
+ """,
888
+ (at or now_iso(),),
889
+ ).fetchall()
890
+
891
+ def count_offer_deliveries(self, offer_id: str, *, since: str | None = None) -> int:
892
+ query = "SELECT COUNT(*) AS count FROM deliveries WHERE offer_id = ? AND kind = 'post' AND status NOT IN ('FAILED', 'REDACTED')"
893
+ values: list[Any] = [offer_id]
894
+ if since:
895
+ query += " AND created_at >= ?"
896
+ values.append(since)
897
+ with self._lock:
898
+ row = self._connection.execute(query, values).fetchone()
899
+ return int(row["count"])
900
+
901
+ def expire_ping(self, ping_id: str) -> None:
902
+ with self.transaction() as db:
903
+ db.execute(
904
+ "UPDATE pings SET status = 'EXPIRED', updated_at = ? WHERE ping_id = ? AND status = 'OPEN'",
905
+ (now_iso(), ping_id),
906
+ )
907
+
908
+ def mark_ping_won(self, ping_id: str) -> None:
909
+ with self.transaction() as db:
910
+ db.execute(
911
+ "UPDATE pings SET status = 'WON', updated_at = ? WHERE ping_id = ?",
912
+ (now_iso(), ping_id),
913
+ )
914
+
915
+ def insert_bid(self, envelope: dict[str, Any], ping: sqlite3.Row) -> bool:
916
+ message = envelope["lcp"]["message"]
917
+ payload = envelope["lcp"]["payload"]
918
+ timestamp = now_iso()
919
+ with self.transaction() as db:
920
+ try:
921
+ db.execute(
922
+ """
923
+ INSERT INTO bids
924
+ (bid_id, ping_id, lead_id, offer_id, buyer_id, message_id,
925
+ decision, bid_price_cents, currency, estimated_contact_seconds,
926
+ received_at, envelope_json)
927
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
928
+ """,
929
+ (
930
+ message["id"],
931
+ payload["ping_id"],
932
+ ping["lead_id"],
933
+ ping["offer_id"],
934
+ message["sender_id"],
935
+ message["id"],
936
+ payload["decision"],
937
+ payload.get("bid_price_cents", 0),
938
+ payload.get("currency", ""),
939
+ payload.get("estimated_contact_seconds"),
940
+ timestamp,
941
+ self.encode_envelope(envelope),
942
+ ),
943
+ )
944
+ except sqlite3.IntegrityError:
945
+ return False
946
+ return True
947
+
948
+ def list_bids_for_lead(self, lead_id: str) -> list[sqlite3.Row]:
949
+ with self._lock:
950
+ return self._connection.execute(
951
+ "SELECT * FROM bids WHERE lead_id = ? ORDER BY received_at, buyer_id",
952
+ (lead_id,),
953
+ ).fetchall()
954
+
955
+ # ─── Payable outcomes and quota ───────────────────────────────────────
956
+
957
+ def record_payable(
958
+ self,
959
+ *,
960
+ offer_id: str,
961
+ lead_id: str,
962
+ buyer_id: str,
963
+ month_key: str,
964
+ channel: str,
965
+ status: str,
966
+ price_cents: int = 0,
967
+ currency: str = "",
968
+ reason: str | None = None,
969
+ call_seconds: int | None = None,
970
+ ) -> None:
971
+ timestamp = now_iso()
972
+ with self.transaction() as db:
973
+ db.execute(
974
+ """
975
+ INSERT INTO payable_records
976
+ (payable_id, offer_id, lead_id, buyer_id, month_key, channel,
977
+ status, price_cents, currency, reason, call_seconds, created_at, updated_at)
978
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
979
+ ON CONFLICT(offer_id, lead_id) DO UPDATE SET
980
+ month_key=excluded.month_key,
981
+ status=excluded.status,
982
+ price_cents=excluded.price_cents,
983
+ currency=excluded.currency,
984
+ reason=excluded.reason,
985
+ call_seconds=excluded.call_seconds,
986
+ updated_at=excluded.updated_at
987
+ """,
988
+ (
989
+ f"pay_{offer_id}_{lead_id}", offer_id, lead_id, buyer_id, month_key, channel,
990
+ status, price_cents, currency, reason, call_seconds, timestamp, timestamp,
991
+ ),
992
+ )
993
+
994
+ def payable_for_lead(self, lead_id: str) -> list[dict[str, Any]]:
995
+ with self._lock:
996
+ rows = self._connection.execute(
997
+ "SELECT * FROM payable_records WHERE lead_id = ? ORDER BY offer_id",
998
+ (lead_id,),
999
+ ).fetchall()
1000
+ return [dict(row) for row in rows]
1001
+
1002
+ def payable_summary(self, offer_id: str, month_key: str) -> dict[str, int]:
1003
+ with self._lock:
1004
+ rows = self._connection.execute(
1005
+ "SELECT status, COUNT(*) AS count FROM payable_records WHERE offer_id = ? AND month_key = ? GROUP BY status",
1006
+ (offer_id, month_key),
1007
+ ).fetchall()
1008
+ summary = {"pending": 0, "payable": 0, "not_payable": 0, "disputed": 0, "refunded": 0}
1009
+ for row in rows:
1010
+ summary[str(row["status"])] = int(row["count"])
1011
+ summary["total"] = sum(summary.values())
1012
+ return summary
1013
+
1014
+ def deliveries_for_lead(self, lead_id: str) -> list[sqlite3.Row]:
1015
+ with self._lock:
1016
+ return self._connection.execute(
1017
+ "SELECT * FROM deliveries WHERE lead_id = ? ORDER BY created_at, delivery_id",
1018
+ (lead_id,),
1019
+ ).fetchall()
1020
+
1021
+ # ─── Delivery queue ────────────────────────────────────────────────────
1022
+
1023
+ def insert_delivery(
1024
+ self,
1025
+ *,
1026
+ lead_id: str,
1027
+ ping_id: str | None,
1028
+ offer_id: str,
1029
+ buyer_id: str,
1030
+ kind: str,
1031
+ envelope: dict[str, Any],
1032
+ webhook_url: str,
1033
+ ) -> bool:
1034
+ message = envelope["lcp"]["message"]
1035
+ timestamp = now_iso()
1036
+ with self.transaction() as db:
1037
+ cursor = db.execute(
1038
+ """
1039
+ INSERT INTO deliveries
1040
+ (delivery_id, lead_id, ping_id, offer_id, buyer_id, kind,
1041
+ message_id, idempotency_key, webhook_url, envelope_json,
1042
+ status, attempts, next_attempt_at, created_at, updated_at)
1043
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'PENDING', 0, ?, ?, ?)
1044
+ ON CONFLICT(message_id) DO NOTHING
1045
+ """,
1046
+ (
1047
+ message["id"],
1048
+ lead_id,
1049
+ ping_id,
1050
+ offer_id,
1051
+ buyer_id,
1052
+ kind,
1053
+ message["id"],
1054
+ message["idempotency_key"],
1055
+ webhook_url,
1056
+ self.encode_envelope(envelope),
1057
+ timestamp,
1058
+ timestamp,
1059
+ timestamp,
1060
+ ),
1061
+ )
1062
+ return cursor.rowcount == 1
1063
+
1064
+ def list_due_deliveries(self, at: str | None = None) -> list[sqlite3.Row]:
1065
+ with self._lock:
1066
+ return self._connection.execute(
1067
+ """
1068
+ SELECT * FROM deliveries
1069
+ WHERE (status IN ('PENDING', 'RETRY') AND next_attempt_at <= ?)
1070
+ OR (status = 'PROCESSING' AND lease_until <= ?)
1071
+ ORDER BY next_attempt_at, created_at
1072
+ """,
1073
+ (at or now_iso(), at or now_iso()),
1074
+ ).fetchall()
1075
+
1076
+ def claim_due_deliveries(
1077
+ self,
1078
+ worker_id: str,
1079
+ *,
1080
+ lease_seconds: int = 60,
1081
+ at: str | None = None,
1082
+ limit: int = 50,
1083
+ ) -> list[sqlite3.Row]:
1084
+ current = datetime.now(timezone.utc)
1085
+ now_value = at or current.strftime("%Y-%m-%dT%H:%M:%SZ")
1086
+ lease_until = (current + timedelta(seconds=lease_seconds)).strftime(
1087
+ "%Y-%m-%dT%H:%M:%SZ"
1088
+ )
1089
+ with self.transaction() as db:
1090
+ rows = db.execute(
1091
+ """
1092
+ SELECT * FROM deliveries
1093
+ WHERE (status IN ('PENDING', 'RETRY') AND next_attempt_at <= ?)
1094
+ OR (status = 'PROCESSING' AND lease_until <= ?)
1095
+ ORDER BY next_attempt_at, created_at
1096
+ LIMIT ?
1097
+ """,
1098
+ (now_value, now_value, limit),
1099
+ ).fetchall()
1100
+ for row in rows:
1101
+ db.execute(
1102
+ """
1103
+ UPDATE deliveries
1104
+ SET status = 'PROCESSING', lease_owner = ?, lease_until = ?, updated_at = ?
1105
+ WHERE delivery_id = ?
1106
+ """,
1107
+ (worker_id, lease_until, now_value, row["delivery_id"]),
1108
+ )
1109
+ return rows
1110
+
1111
+ def mark_delivery(
1112
+ self,
1113
+ delivery_id: str,
1114
+ *,
1115
+ status: str,
1116
+ attempts: int,
1117
+ next_attempt_at: str,
1118
+ last_error: str | None = None,
1119
+ worker_id: str | None = None,
1120
+ ) -> None:
1121
+ with self.transaction() as db:
1122
+ if worker_id:
1123
+ db.execute(
1124
+ """
1125
+ UPDATE deliveries
1126
+ SET status = ?, attempts = ?, next_attempt_at = ?, last_error = ?,
1127
+ lease_owner = NULL, lease_until = NULL, updated_at = ?
1128
+ WHERE delivery_id = ? AND lease_owner = ?
1129
+ """,
1130
+ (status, attempts, next_attempt_at, last_error, now_iso(), delivery_id, worker_id),
1131
+ )
1132
+ else:
1133
+ db.execute(
1134
+ """
1135
+ UPDATE deliveries
1136
+ SET status = ?, attempts = ?, next_attempt_at = ?, last_error = ?, lease_owner = NULL, lease_until = NULL, updated_at = ?
1137
+ WHERE delivery_id = ?
1138
+ """,
1139
+ (status, attempts, next_attempt_at, last_error, now_iso(), delivery_id),
1140
+ )
1141
+
1142
+ def has_delivery_for_offer(self, lead_id: str, offer_id: str, kind: str) -> bool:
1143
+ with self._lock:
1144
+ row = self._connection.execute(
1145
+ "SELECT 1 FROM deliveries WHERE lead_id = ? AND offer_id = ? AND kind = ? LIMIT 1",
1146
+ (lead_id, offer_id, kind),
1147
+ ).fetchone()
1148
+ return row is not None
1149
+
1150
+ def has_delivery_for_buyer(self, lead_id: str, buyer_id: str) -> bool:
1151
+ with self._lock:
1152
+ row = self._connection.execute(
1153
+ "SELECT 1 FROM deliveries WHERE lead_id = ? AND buyer_id = ? LIMIT 1",
1154
+ (lead_id, buyer_id),
1155
+ ).fetchone()
1156
+ return row is not None
1157
+
1158
+ # ─── Lifecycle ─────────────────────────────────────────────────────────
1159
+
1160
+ def insert_event(self, lead_id: str, event_name: str, envelope: dict[str, Any]) -> None:
1161
+ payload = envelope["lcp"]["payload"]
1162
+ with self.transaction() as db:
1163
+ db.execute(
1164
+ """
1165
+ INSERT INTO lifecycle_events
1166
+ (event_id, lead_id, event_name, timestamp, envelope_json)
1167
+ VALUES (?, ?, ?, ?, ?)
1168
+ ON CONFLICT(event_id) DO NOTHING
1169
+ """,
1170
+ (
1171
+ envelope["lcp"]["message"]["id"],
1172
+ lead_id,
1173
+ event_name,
1174
+ payload["timestamp"],
1175
+ self.encode_envelope(envelope),
1176
+ ),
1177
+ )
1178
+
1179
+ def list_events(self, lead_id: str) -> list[dict[str, Any]]:
1180
+ with self._lock:
1181
+ rows = self._connection.execute(
1182
+ "SELECT envelope_json FROM lifecycle_events WHERE lead_id = ? ORDER BY timestamp",
1183
+ (lead_id,),
1184
+ ).fetchall()
1185
+ return [self.decode_envelope(row["envelope_json"]) for row in rows]
1186
+
1187
+ def erase_lead(self, lead_id: str, *, actor_id: str = "operator") -> bool:
1188
+ """Redact consumer data and cancel undelivered payloads for a lead.
1189
+
1190
+ Immutable routing/audit identifiers remain so operators can prove that
1191
+ an erasure occurred without retaining the consumer payload.
1192
+ """
1193
+ with self.transaction() as db:
1194
+ row = db.execute(
1195
+ "SELECT tenant_id, envelope_json FROM leads WHERE lead_id = ?",
1196
+ (lead_id,),
1197
+ ).fetchone()
1198
+ if not row:
1199
+ return False
1200
+ redacted_lead = self._redact_envelope(row["envelope_json"])
1201
+ timestamp = now_iso()
1202
+ db.execute(
1203
+ """
1204
+ UPDATE leads
1205
+ SET envelope_json = ?, status = 'ERASED', updated_at = ?
1206
+ WHERE lead_id = ?
1207
+ """,
1208
+ (redacted_lead, timestamp, lead_id),
1209
+ )
1210
+ child_keys = {
1211
+ "pings": "ping_id",
1212
+ "bids": "bid_id",
1213
+ "deliveries": "delivery_id",
1214
+ "lifecycle_events": "event_id",
1215
+ }
1216
+ for table, child_key in child_keys.items():
1217
+ rows = db.execute(
1218
+ f"SELECT {child_key}, envelope_json FROM {table} WHERE lead_id = ?",
1219
+ (lead_id,),
1220
+ ).fetchall()
1221
+ for child in rows:
1222
+ redacted = self._redact_envelope(child["envelope_json"])
1223
+ if table == "deliveries":
1224
+ db.execute(
1225
+ """
1226
+ UPDATE deliveries
1227
+ SET envelope_json = ?, status = 'REDACTED',
1228
+ lease_owner = NULL, lease_until = NULL,
1229
+ last_error = 'Lead erased', updated_at = ?
1230
+ WHERE delivery_id = ?
1231
+ """,
1232
+ (redacted, timestamp, child[child_key]),
1233
+ )
1234
+ elif table == "pings":
1235
+ db.execute(
1236
+ """
1237
+ UPDATE pings
1238
+ SET envelope_json = ?, status = 'REDACTED', updated_at = ?
1239
+ WHERE ping_id = ?
1240
+ """,
1241
+ (redacted, timestamp, child[child_key]),
1242
+ )
1243
+ else:
1244
+ db.execute(
1245
+ f"UPDATE {table} SET envelope_json = ? WHERE {child_key} = ?",
1246
+ (redacted, child[child_key]),
1247
+ )
1248
+ db.execute(
1249
+ "UPDATE routing_jobs SET status = 'DONE', lease_owner = NULL, lease_until = NULL, updated_at = ? WHERE lead_id = ?",
1250
+ (timestamp, lead_id),
1251
+ )
1252
+ db.execute(
1253
+ """
1254
+ INSERT INTO audit_events
1255
+ (audit_id, tenant_id, actor_id, action, resource_type,
1256
+ resource_id, metadata_json, created_at)
1257
+ VALUES (?, ?, ?, 'lead.erased', 'lead', ?, ?, ?)
1258
+ """,
1259
+ (
1260
+ f"audit_{uuid4().hex}",
1261
+ row["tenant_id"],
1262
+ actor_id,
1263
+ lead_id,
1264
+ json.dumps({"retained_identifiers": True}, separators=(",", ":")),
1265
+ timestamp,
1266
+ ),
1267
+ )
1268
+ return True
1269
+
1270
+ def _redact_envelope(self, stored: str) -> str:
1271
+ envelope = self.decode_envelope(stored)
1272
+ message = dict(envelope["lcp"]["message"])
1273
+ message.pop("security", None)
1274
+ message_type = message.get("type")
1275
+ original_payload = envelope["lcp"].get("payload", {})
1276
+ if message_type in {"lead", "call", "post", "ping"}:
1277
+ payload = {
1278
+ key: original_payload[key]
1279
+ for key in ("lead_id", "ping_id", "event", "timestamp")
1280
+ if key in original_payload
1281
+ }
1282
+ elif message_type == "event":
1283
+ payload = {
1284
+ key: original_payload[key]
1285
+ for key in ("lead_id", "event", "timestamp")
1286
+ if key in original_payload
1287
+ }
1288
+ else:
1289
+ payload = {}
1290
+ return self.encode_envelope(
1291
+ {"lcp": {"version": envelope["lcp"]["version"], "message": message, "payload": payload}}
1292
+ )
1293
+
1294
+ def all_pings_terminal(self, lead_id: str) -> bool:
1295
+ with self._lock:
1296
+ row = self._connection.execute(
1297
+ "SELECT COUNT(*) AS count FROM pings WHERE lead_id = ? AND status = 'OPEN'",
1298
+ (lead_id,),
1299
+ ).fetchone()
1300
+ return row["count"] == 0