✨ Resolve screenshot SHAs before byte upload (#299)

## Why

Screenshot upload is one of Vizzly's hottest SDK paths. When a build
captures thousands of screenshots, sending image bytes for files we
already have in storage is wasted work for the CLI, API, and object
storage.

The paired Vizzly API change lets the screenshot create endpoint accept
`sha256` without `image_data`, resolve reusable storage server-side, and
only ask for bytes when the image is missing. This CLI change moves the
per-screenshot upload path to that contract.

## Approach

- Compute the screenshot SHA before upload and first call the screenshot
create endpoint with name, metadata, and SHA only.
- Skip the byte upload when the API returns `upload_required: false`,
preserving the existing skipped/fromExisting result shape for callers.
- Fall back to the normal byte upload path when SHA resolution is
unavailable, returns a server error, or talks to an older server that
still requires `image_data`.
- Continue surfacing auth and ownership failures instead of retrying
them as byte uploads, so the fallback does not hide real access-control
errors.
- Document that skipped uploads mean Vizzly reused existing storage, and
that `--upload-all` still forces screenshots through.

This keeps the CLI simple: no SDK-side batching, no client-side cache,
and no extra state to recover from. The API stays authoritative about
whether a screenshot can reuse existing storage.

## Confidence

The API payload helper now has a pure test proving SHA resolution omits
image bytes. The upload endpoint tests cover resolve misses, resolve
hits, old-server fallback, auth failure, and `--upload-all`. The full
CLI test suite and Biome lint pass locally.

## Related

- Coordinates with `vizzly-testing/vizzly#543`, which adds the
server-side create-with-SHA behavior.

Author: Robdel12

README.md

@@ -176,9 +176,11 @@ vizzly upload ./screenshots --threshold 2 --min-cluster-size 4 --batch-size 10 -
 `--upload-timeout` controls the upload client's timeout, including how long
 `--wait` polls for build processing.
 
-CI workflows can force every screenshot through even when the SHA cache says it
-already uploaded. Parallel jobs should use the same stable ID, then finalize
-that ID after every shard completes:
+When `vizzly run` sends screenshots to Vizzly, the CLI first asks the API to
+resolve each screenshot by SHA. If Vizzly already has the image bytes, the CLI
+creates the screenshot record without re-uploading the image. CI workflows can
+force every screenshot through with `--upload-all`. Parallel jobs should use the
+same stable ID, then finalize that ID after every shard completes:
 
 ```bash
 vizzly run "pnpm test" --upload-all --parallel-id "$GITHUB_RUN_ID"

docs/json-output.md

@@ -759,6 +759,10 @@ vizzly upload ./screenshots --json
 }
 ```
 
+`stats.skipped` counts screenshots that Vizzly resolved by SHA without sending
+image bytes. Use `--upload-all` when you need every screenshot uploaded
+regardless of existing storage.
+
 With `--wait`, the payload includes comparison results after Vizzly finishes
 processing the build:
 

src/api/core.js

@@ -70,9 +70,9 @@ export function buildRequestHeaders({
 // ============================================================================
 
 /**
- * Build payload for screenshot upload
+ * Build payload for screenshot upload or SHA resolution
  * @param {string} name - Screenshot name
- * @param {Buffer} buffer - Image data
+ * @param {Buffer|null} buffer - Image data, or null when resolving by SHA
  * @param {Object} metadata - Screenshot metadata (viewport, browser, etc.)
  * @param {string|null} sha256 - Pre-computed SHA256 hash (optional)
  * @returns {Object} Screenshot upload payload
@@ -85,17 +85,31 @@ export function buildScreenshotPayload(
 ) {
   let payload = {
     name,
-    image_data: buffer.toString('base64'),
     properties: metadata ?? {},
   };
 
+  if (buffer) {
+    payload.image_data = buffer.toString('base64');
+  }
+
   if (sha256) {
     payload.sha256 = sha256;
   }
 
   return payload;
 }
 
+/**
+ * Build payload for server-side screenshot resolution without sending image bytes
+ * @param {string} name - Screenshot name
+ * @param {Object} metadata - Screenshot metadata (viewport, browser, etc.)
+ * @param {string} sha256 - Pre-computed SHA256 hash
+ * @returns {Object} Screenshot resolution payload
+ */
+export function buildScreenshotResolvePayload(name, metadata = {}, sha256) {
+  return buildScreenshotPayload(name, null, metadata, sha256);
+}
+
 /**
  * Build payload for build creation
  * @param {Object} options - Build options

src/api/endpoints.js

@@ -11,12 +11,10 @@ import {
   buildBuildPayload,
   buildEndpointWithParams,
   buildQueryParams,
-  buildScreenshotCheckObject,
   buildScreenshotPayload,
+  buildScreenshotResolvePayload,
   buildShaCheckPayload,
   computeSha256,
-  findScreenshotBySha,
-  shaExists,
 } from './core.js';
 
 // ============================================================================
@@ -156,6 +154,18 @@ export async function checkShas(client, screenshots, buildId) {
   }
 }
 
+function canUploadBytesAfterShaResolveError(error) {
+  let status = error?.context?.status;
+
+  // Network failures, older servers, and server errors should degrade to the
+  // slower byte upload path. Auth and ownership errors must still surface.
+  if (!status) return true;
+  if (status >= 500) return true;
+  if (status === 400 && error.message?.includes('image_data')) return true;
+
+  return false;
+}
+
 /**
  * Upload a screenshot with SHA deduplication
  * @param {Object} client - API client
@@ -184,24 +194,39 @@ export async function uploadScreenshot(
     });
   }
 
-  // Normal flow with SHA deduplication
+  // Normal flow with server-side SHA resolution.
   let sha256 = computeSha256(buffer);
-  let checkObj = buildScreenshotCheckObject(sha256, name, metadata);
-  let checkResult = await checkShas(client, [checkObj], buildId);
-
-  if (shaExists(checkResult, sha256)) {
-    // File already exists, screenshot record was automatically created
-    let screenshot = findScreenshotBySha(checkResult, sha256);
-    return {
-      message: 'Screenshot already exists, skipped upload',
-      sha256,
-      skipped: true,
-      screenshot,
-      fromExisting: true,
-    };
+  let resolvePayload = buildScreenshotResolvePayload(name, metadata, sha256);
+  try {
+    let resolveResult = await client.request(
+      `/api/sdk/builds/${buildId}/screenshots`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(resolvePayload),
+      }
+    );
+
+    if (resolveResult?.upload_required === false) {
+      return {
+        message: 'Screenshot already exists, skipped upload',
+        sha256,
+        skipped: true,
+        screenshot: resolveResult,
+        fromExisting: true,
+      };
+    }
+  } catch (error) {
+    if (!canUploadBytesAfterShaResolveError(error)) {
+      throw error;
+    }
+
+    output.debug('sha-resolve', 'failed, uploading screenshot bytes', {
+      error: error.message,
+    });
   }
 
-  // File doesn't exist, proceed with upload
+  // File doesn't exist, or resolve failed; proceed with upload.
   let payload = buildScreenshotPayload(name, buffer, metadata, sha256);
   return client.request(`/api/sdk/builds/${buildId}/screenshots`, {
     method: 'POST',

src/api/index.js

@@ -22,6 +22,7 @@ export {
   buildRequestHeaders,
   buildScreenshotCheckObject,
   buildScreenshotPayload,
+  buildScreenshotResolvePayload,
   buildShaCheckPayload,
   buildUserAgent,
   computeSha256,

tests/api/core.test.js

@@ -15,6 +15,7 @@ import {
   buildRequestHeaders,
   buildScreenshotCheckObject,
   buildScreenshotPayload,
+  buildScreenshotResolvePayload,
   buildShaCheckPayload,
   buildUserAgent,
   computeSha256,
@@ -279,6 +280,21 @@ describe('api/core', () => {
 
       assert.deepStrictEqual(result.properties, {});
     });
+
+    it('builds SHA resolve payload without image bytes', () => {
+      let result = buildScreenshotResolvePayload(
+        'homepage',
+        { browser: 'firefox' },
+        'abc123'
+      );
+
+      assert.deepStrictEqual(result, {
+        name: 'homepage',
+        properties: { browser: 'firefox' },
+        sha256: 'abc123',
+      });
+      assert.strictEqual(result.image_data, undefined);
+    });
   });
 
   describe('buildBuildPayload', () => {

tests/api/endpoints.test.js

@@ -66,6 +66,21 @@ function createMockClient(responseOrHandler = {}) {
   };
 }
 
+function createSequencedClient(responses) {
+  let responseIndex = 0;
+
+  return createMockClient(() => {
+    let response = responses[responseIndex] ?? responses[responses.length - 1];
+    responseIndex++;
+
+    if (response instanceof Error) {
+      throw response;
+    }
+
+    return response;
+  });
+}
+
 describe('api/endpoints', () => {
   describe('getBuild', () => {
     it('requests correct endpoint', async () => {
@@ -337,13 +352,11 @@ describe('api/endpoints', () => {
   });
 
   describe('uploadScreenshot', () => {
-    it('uploads screenshot with deduplication', async () => {
-      let client = createMockClient(endpoint => {
-        if (endpoint === '/api/sdk/check-shas') {
-          return { existing: [], missing: ['someSha'], screenshots: [] };
-        }
-        return { id: 'screenshot-1' };
-      });
+    it('resolves SHA before uploading screenshot bytes', async () => {
+      let client = createSequencedClient([
+        { upload_required: true },
+        { id: 'screenshot-1' },
+      ]);
 
       let buffer = Buffer.from('fake png data');
       let result = await uploadScreenshot(
@@ -355,22 +368,38 @@ describe('api/endpoints', () => {
       );
 
       assert.ok(result);
-      // Should have called check-shas first, then upload
       let calls = client.getCalls();
       assert.strictEqual(calls.length, 2);
+      assert.strictEqual(
+        calls[0].endpoint,
+        '/api/sdk/builds/build-123/screenshots'
+      );
+      assert.strictEqual(
+        calls[1].endpoint,
+        '/api/sdk/builds/build-123/screenshots'
+      );
+      let resolveBody = JSON.parse(calls[0].options.body);
+      let uploadBody = JSON.parse(calls[1].options.body);
+      let expectedSha = createHash('sha256').update(buffer).digest('hex');
+
+      assert.strictEqual(resolveBody.name, 'test-screenshot');
+      assert.strictEqual(resolveBody.sha256, expectedSha);
+      assert.deepStrictEqual(resolveBody.properties, { viewport: '1920x1080' });
+      assert.ok(!resolveBody.image_data);
+      assert.strictEqual(uploadBody.sha256, expectedSha);
+      assert.ok(uploadBody.image_data);
     });
 
-    it('skips upload when SHA exists', async () => {
+    it('skips byte upload when screenshot create resolves reusable SHA', async () => {
       let buffer = Buffer.from('fake png data');
-      // Compute the actual SHA that will be generated
       let sha = createHash('sha256').update(buffer).digest('hex');
 
       let client = createMockClient(endpoint => {
-        if (endpoint === '/api/sdk/check-shas') {
+        if (endpoint === '/api/sdk/builds/build-123/screenshots') {
           return {
-            existing: [sha],
-            missing: [],
-            screenshots: [{ sha256: sha, id: 'existing-id' }],
+            id: 'existing-id',
+            sha256: sha,
+            upload_required: false,
           };
         }
         return { id: 'screenshot-1' };
@@ -385,9 +414,56 @@ describe('api/endpoints', () => {
 
       assert.strictEqual(result.skipped, true);
       assert.strictEqual(result.fromExisting, true);
-      // Should only call check-shas, not upload
       let calls = client.getCalls();
       assert.strictEqual(calls.length, 1);
+      assert.strictEqual(
+        calls[0].endpoint,
+        '/api/sdk/builds/build-123/screenshots'
+      );
+      let resolveBody = JSON.parse(calls[0].options.body);
+      assert.strictEqual(resolveBody.sha256, sha);
+      assert.ok(!resolveBody.image_data);
+    });
+
+    it('uploads bytes when SHA resolution is unavailable', async () => {
+      let client = createSequencedClient([
+        new Error('old server'),
+        { id: 'screenshot-1' },
+      ]);
+
+      let buffer = Buffer.from('fake png data');
+      let result = await uploadScreenshot(
+        client,
+        'build-123',
+        'test-screenshot',
+        buffer,
+        { viewport: '1920x1080' }
+      );
+
+      assert.deepStrictEqual(result, { id: 'screenshot-1' });
+      let calls = client.getCalls();
+      assert.strictEqual(calls.length, 2);
+      assert.ok(!JSON.parse(calls[0].options.body).image_data);
+      assert.ok(JSON.parse(calls[1].options.body).image_data);
+    });
+
+    it('does not retry byte upload when SHA resolution fails with auth errors', async () => {
+      let authError = new Error('Invalid or expired API token');
+      authError.context = { status: 401 };
+      let client = createMockClient(() => {
+        throw authError;
+      });
+
+      let buffer = Buffer.from('fake png data');
+
+      await assert.rejects(
+        () => uploadScreenshot(client, 'build-123', 'test-screenshot', buffer),
+        /Invalid or expired API token/
+      );
+
+      let calls = client.getCalls();
+      assert.strictEqual(calls.length, 1);
+      assert.ok(!JSON.parse(calls[0].options.body).image_data);
     });
 
     it('uploads directly when skipDedup is true', async () => {
@@ -404,7 +480,7 @@ describe('api/endpoints', () => {
       );
 
       let calls = client.getCalls();
-      // Should only have one call (upload), not checkShas
+      // Should only have one call (upload), not SHA resolve
       assert.strictEqual(calls.length, 1);
       assert.ok(calls[0].endpoint.includes('/screenshots'));
     });