feat(scanner): pass user region through api_record_scan and api_submit_product (#923)

[ericsocrat]

Summary

Implements issue #923 — the third issue in epic #920 (Country-Aware Scanner).

Modifies api_record_scan and api_submit_product RPC functions to accept explicit country parameters, resolve country from user preferences when not provided, and return country information in their responses.

Depends on: PR #933 (issue #921) and PR #934 (issue #922) — both merged into this branch.

---

Changes

Migration: 20260320000300_country_aware_scanner_rpcs.sql

api_record_scan(p_ean text, p_scan_country text DEFAULT NULL)

Aspect	Before	After
Signature	(text) — 1 param	(text, text) — 2 params
Country input	None	p_scan_country DEFAULT NULL
Country resolution	None	COALESCE(p_scan_country, user_preferences.country)
scan_history INSERT	No country	Writes scan_country column
Found response	No country keys	Adds scan_country, product_country
Not-found response	No country keys	Adds scan_country

Country resolution order:

1. Explicit p_scan_country parameter (if provided)
2. user_preferences.country (if user is authenticated and has preferences)
3. NULL (anonymous users or no preference set)

api_submit_product(p_ean, p_product_name, p_brand, p_category, p_photo_url, p_notes, p_scan_country, p_suggested_country)

Aspect	Before	After
Signature	(text ×6) — 6 params	(text ×8) — 8 params
Country input	None	p_scan_country, p_suggested_country DEFAULT NULL
Country resolution	None	scan_country from param or prefs; suggested_country from param or defaults to resolved scan_country
INSERT	No country cols	Writes scan_country, suggested_country
Response	No country keys	Adds scan_country, suggested_country

Old function signatures are dropped via DROP FUNCTION IF EXISTS.

Tests

• scanner_functions.test.sql — plan 64 → 70 (+6 tests):

  • Section 2: scan_country and product_country keys exist in found response
  • Section 5: scan_country key exists in not-found response
  • Section 6b (new): explicit scan_country parameter returns correct value; backward compat (no param → NULL)

• schema_contracts.test.sql — plan 303 → 305 (+2 assertions):

  • has_function for api_record_scan(text, text) — 2-param signature
  • has_function for api_submit_product(text ×8) — 8-param signature

Documentation

• docs/API_CONTRACTS.md — new subsections under §8 (Barcode Scanner):
  • api_record_scan — PostgREST call, parameters table, country resolution, response examples (found/not-found/error)
  • api_submit_product — 8-param signature, parameters table, country resolution, response examples (success/error)

---

Backward Compatibility

All new parameters have DEFAULT NULL. Existing callers that pass only the original parameters continue to work identically — country fields return null when not provided and user has no preferences.

Response keys are additive only. No existing keys were removed or renamed.

---

Verification

supabase db reset                → All 3 migrations apply cleanly (000100 + 000200 + 000300)
pg_proc signature check          → api_record_scan(text,text) ✅, api_submit_product(text×8) ✅, old sigs GONE ✅

supabase test db:
  schema_contracts.test.sql      → 304/305 pass (1 pre-existing: test 294 trg_record_score_change)
  scanner_functions.test.sql     → 41/41 ran PASS (29 skipped: pre-existing trust trigger bug at section 10)
  All 6 new #923 tests           → PASS ✅

Direct function calls:
  api_record_scan('5901234123457', 'PL') → scan_country: "PL" ✅
  api_record_scan('5901234123457')       → scan_country: null  ✅ (backward compat)

.\RUN_QA.ps1:
  49 suites, 0 new failures ✅
  Pre-existing (post-reset, no pipeline data): suites 6, 16, 20, 21, 32

---

File Impact

4 files changed, +428 / -2 lines:

• 1 new DB migration (267 lines)
• 2 modified pgTAP test files (+8 assertions)
• 1 modified doc file (API_CONTRACTS.md, +153 lines)

---

Acceptance Criteria (from issue #923)

• api_record_scan(p_ean, p_scan_country DEFAULT NULL) — new signature
• api_submit_product(…, p_scan_country, p_suggested_country DEFAULT NULL) — new signature
• Country resolution: explicit param → user_preferences.country → NULL
• scan_history.scan_country populated on INSERT
• product_submissions.scan_country + suggested_country populated on INSERT
• Response contracts include scan_country (+ product_country for record_scan)
• Old function signatures dropped
• All new params DEFAULT NULL (backward compatible)
• pgTAP tests cover new params + backward compat
• Schema contracts updated for new signatures
• API_CONTRACTS.md updated
• No feat(frontend): pass scan country from frontend scan/submit flow to RPCs #924 frontend, feat(frontend): show country context in admin submission review UI #925 admin UI, feat(scanner): region-preferred product matching in api_record_scan #926 region-preferred matching scope creep

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
tryvit	Ready	Preview, Comment	Mar 17, 2026 11:02am

[Copilot]

Pull request overview

Adds country context capture to the scanner + submission RPCs by introducing optional country parameters, persisting resolved country into the new schema columns, and documenting/testing the updated contracts as part of the “Country-Aware Scanner” epic.

Changes:

• Add scan_country / suggested_country columns (with FKs + indexes) to scan_history and product_submissions.
• Update api_record_scan and api_submit_product RPCs to accept country params, resolve from user_preferences when absent, persist to tables, and return country keys in JSON responses.
• Expand pgTAP coverage and update API contracts documentation for the new signatures/response fields.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
supabase/migrations/20260320000100_scan_history_country.sql	Adds scan_history.scan_country (FK to country_ref) + partial index and column comment.
supabase/migrations/20260320000200_submissions_country.sql	Adds product_submissions.scan_country + suggested_country (FKs), partial indexes, and comments.
supabase/migrations/20260320000300_country_aware_scanner_rpcs.sql	Updates api_record_scan / api_submit_product signatures + response shape and persists resolved country values.
supabase/tests/schema_contracts.test.sql	Adds schema + function signature contract assertions and adjusts plan count.
supabase/tests/scanner_functions.test.sql	Adds tests for new scan_country / product_country response keys and explicit param behavior.
docs/API_CONTRACTS.md	Documents new RPC params, country resolution, and response examples.