feat(PER-9724): send priority on build create via PERCY_PRIORITY (internal)

[annukumari-bs]

What & why

PER-9724 — client side of the priority-queue feature. Lets internal product orchestration (e.g. Scanner / LCA) request the priority lane for a build.

@percy/client createBuild() now forwards an internal env signal as the build-create priority attribute:

let priority = process.env.PERCY_PRIORITY === 'true';
// data.attributes:
...(priority ? { priority: true } : {})

This mirrors the existing PERCY_ORIGINATED_SOURCE internal signal right beside it in createBuild.

Why an env var (internal, decoupled, safe)

• Internal-only: the Scanner/LCA orchestration sets PERCY_PRIORITY=true; the client just relays it. Not a customer-facing config.
• Not customer-controllable / no duplicated logic: percy-api is the authoritative gate — it only honors priority for eligible internal build types (visual_scanner, responsive_scanner, lca). A customer setting the env var on a normal build has no effect, and the CLI doesn't duplicate the eligibility allowlist.
• Zero impact when unset: the priority attribute is omitted entirely unless PERCY_PRIORITY=true, so existing build payloads are unchanged.

Companion PRs

• percy-api: percy/percy-api#6337 (accepts priority, gates by param && internal build type, routes jobs)
• infrastructure: percy/infrastructure#1288 (renderer priority queues + KEDA)
• percy-renderer: percy/percy-renderer#1903 (forward priority on the AfterRenderJob hop)

End-to-end: internal product sets PERCY_PRIORITY=true → client sends priority: true → percy-api honors it for eligible scanner/lca builds → jobs route to priority_* queues across api / renderer / image-processor.

Tests

Added to packages/client/test/client.test.js: priority sent when PERCY_PRIORITY set, and omitted when unset. Both pass; all existing createBuild tests pass. (Two unrelated proxy.test.js failures are pre-existing — a Node URL error-string difference, not part of this change.)

🤖 Generated with Claude Code

[annukumari-bs]

Claude Code PR Review

PR: #2329 • Head: a8512dd • Reviewers: fallback focused review (no in-scope specialist reviewers in percy/cli)

Summary

PER-9724: @percy/client createBuild forwards an internal PERCY_PRIORITY=true env signal as the build-create priority attribute (mirrors PERCY_ORIGINATED_SOURCE); omitted when unset.

Review Table

Priority	Category	Check	Status	Notes
High	Security	No hardcoded secrets or credentials	Pass	None.
High	Security	Authentication/authorization checks present	N/A	Client lib; auth handled elsewhere (token).
High	Security	Input validation and sanitization	Pass	=== 'true' strict check; only the literal enables. percy-api re-gates by build type, so not customer-controllable even if set.
High	Security	No IDOR — resource ownership validated	N/A	No resource lookup.
High	Security	No SQL injection (parameterized queries)	N/A	No queries.
High	Correctness	Logic is correct, handles edge cases	Pass	Attribute added only when env is exactly 'true'; omitted otherwise (no payload change for existing flows).
High	Correctness	Error handling is explicit, no swallowed exceptions	N/A	Pure env read; nothing to rescue.
High	Correctness	No race conditions or concurrency issues	N/A	—
Medium	Testing	New code has corresponding tests	Pass	Tests for set ('priority: true' sent) and unset (attribute undefined).
Medium	Testing	Error paths and edge cases tested	Pass	Unset/default path covered; env cleaned in beforeEach.
Medium	Testing	Existing tests still pass (no regressions)	Pass	All createBuild tests pass; default-attributes assertion unaffected (attribute omitted when unset). (2 unrelated proxy.test.js failures are pre-existing — Node URL error-string diff.)
Medium	Performance	No N+1 queries or unbounded data fetching	N/A	—
Medium	Performance	Long-running tasks use background jobs	N/A	—
Medium	Quality	Follows existing codebase patterns	Pass	Mirrors PERCY_ORIGINATED_SOURCE internal-signal pattern in the same method.
Medium	Quality	Changes are focused (single concern)	Pass	One concern.
Low	Quality	Meaningful names, no dead code	Pass	—
Low	Quality	Comments explain why, not what	Pass	4-line rationale; acceptable.
Low	Quality	No unnecessary dependencies added	Pass	None.

Findings

No HIGH/MEDIUM findings.

• File: packages/client/src/client.js:362
• Severity: Low
• Reviewer: focused review
• Issue: Priority is gated only by the PERCY_PRIORITY env signal on the client; the actual enforcement (eligible internal build type) lives in percy-api. This is intentional (single source of truth server-side) but means the client can request priority for any build type — harmless, since the API ignores it for ineligible types.
• Suggestion: None required — document that the API is the authoritative gate (already noted in the PR description). No code change.

---

Verdict: PASS