Runtime configuration
Run the standalone Node 24 service on loopback for local development. Set HOST/PORT explicitly when needed. Account-backed runtime requires MARKET_DATA_DATABASE_URL; a generic DATABASE_URL is deliberately ignored. Hosted connections require verified TLS and a restricted runtime role. MARKET_DATA_DATABASE_CA can supply a trusted certificate authority. Use separate administrator credentials for migrations and key issuance. Standalone migrations create pokepos_market_api_runtime as a NOLOGIN privilege role; operators provision a private restricted login credential and its runtime URL. The merchant pokepos_market_reader role has a different scope and cannot authorize external API keys.
The POS connector requires MARKET_DATA_API_BASE_URL, MARKET_DATA_DATABASE_URL and POKEPOS_SCANNER_RELAY_KEY in server secret management, plus control migration 0010 for snapshot reservations. The relay secret must agree with the API runtime. It uses receipts rather than MARKET_DATA_INTERNAL_KEY. Never expose either database URL or relay secret to browsers.
NEXT_PUBLIC_MARKET_DATA_API_BASE_URL changes the documentation’s example origin only; NEXT_PUBLIC_API_CONTACT_EMAIL sets support links. These public settings are not secrets and do not configure the POS connector.
Processing budgets
The application total request deadline defaults to 30 seconds; upstream work has a 20-second budget including admission and retries. The hosted function duration is 40 seconds. Source concurrency is three, waiting admission is capped at 24 with 64 distinct in-flight source operations, serialized API responses are capped at 4,100,000 bytes, streamed source JSON is capped at 4 MiB and the per-process cache budget is 32 MiB.
Photo input: PNG/JPEG/WebP, 100–3,000,000 decoded bytes, at most 16 megapixels and 8,000 pixels per dimension; JSON bodies are capped at 4,100,000 bytes. OCR has four admitted jobs and a 15-second processing budget. Initialization that exceeds its deadline stays quarantined until cleanup settles; returning a timeout does not guarantee immediate worker recovery. Upload base64 overhead is included in the request limit. Uploaded image bytes are processed in memory; OCR model cache files may persist independently.
Health and readiness
GET /healthz reports process liveness. GET /readyz verifies account schema, required grants/predicates and relay capability when configured. It does not certify TCGplayer source availability, commercial rights, payment readiness or merchant acceptance. Monitor source errors and partial/stale rates separately.
Retention and replay
Run the administrator usage maintenance daily: minute counters retain two days, monthly counters and POS usage ledgers retain 15 months. Old receipts are retired by scrubbing input/path data and retaining the lookup/receipt identifiers as tombstones. Tombstones are not deleted or reopened, so an old lookup cannot become a new billable command.
Source-response caches are bounded and temporary per process. Financial records, merchant records, backups and any future durable source history have separate retention requirements. A provider agreement must explicitly determine source-data caching, exports, attribution and termination purge rules; this code does not invent a redistribution grant.