@pixeyedev/core 0.4.4 → 0.4.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pixeye (pixeye.dev)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/ci.d.ts

@@ -5,6 +5,18 @@ export interface CIEnvironment {
     baseBranch?: string;
     prNumber?: number;
     repository?: string;
+    /** What triggered the run — recorded on the build so "which CI run made
+     *  this build, started by whom" is answerable from the admin without
+     *  opening the provider. All optional: providers differ in what they expose. */
+    trigger?: CITrigger;
+}
+export interface CITrigger {
+    runId?: string;
+    runAttempt?: string;
+    actor?: string;
+    workflow?: string;
+    eventName?: string;
+    runUrl?: string;
 }
 /**
  * Try to detect the base branch using git merge-base.

package/dist/ci.js

@@ -1,33 +1,57 @@
 import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+/** GITHUB_EVENT_PATH is the run's event payload; absent or unreadable means
+ *  the env vars alone describe the run. */
+const readGitHubEvent = () => {
+    const path = process.env.GITHUB_EVENT_PATH;
+    if (!path) {
+        return null;
+    }
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (err) {
+        console.warn(`pixeye: could not read the GitHub event payload at ${path}: ${String(err)}`);
+        return null;
+    }
+};
 const detectGitHubActions = () => {
     if (!process.env.GITHUB_ACTIONS) {
         return null;
     }
-    const commit = process.env.GITHUB_SHA;
-    const branch = process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME;
+    // On a pull_request run GITHUB_SHA is GitHub's throwaway merge commit, one
+    // per push to the base: the build must carry the PR's own head commit.
+    const event = readGitHubEvent();
+    const eventPr = event?.pull_request ?? event?.workflow_run?.pull_requests?.[0];
+    const commit = event?.pull_request?.head?.sha ?? event?.workflow_run?.head_sha ?? process.env.GITHUB_SHA;
+    const branch = process.env.GITHUB_HEAD_REF || event?.workflow_run?.head_branch || process.env.GITHUB_REF_NAME;
     const runId = process.env.GITHUB_RUN_ID;
     if (!commit || !branch || !runId) {
         return null;
     }
-    // PR number: explicit env > GITHUB_REF on pull_request events (refs/pull/123/merge)
+    // PR number: explicit env, else the event payload.
     const prRaw = process.env.PIXEYE_PR;
-    let prNumber = prRaw ? parseInt(prRaw, 10) : undefined;
-    if (!prNumber) {
-        const ref = process.env.GITHUB_REF ?? '';
-        const prMatch = ref.match(/^refs\/pull\/(\d+)\//);
-        if (prMatch) {
-            prNumber = parseInt(prMatch[1], 10);
-        }
-    }
-    // PR target branch: GITHUB_BASE_REF is set on pull_request events
-    const baseBranch = process.env.GITHUB_BASE_REF || undefined;
+    const prNumber = prRaw ? parseInt(prRaw, 10) : eventPr?.number;
+    // PR target branch: GITHUB_BASE_REF is set on pull_request events; the
+    // payload carries it for workflow_run too.
+    const baseBranch = process.env.GITHUB_BASE_REF || eventPr?.base?.ref || undefined;
+    const repository = process.env.GITHUB_REPOSITORY;
+    const serverUrl = process.env.GITHUB_SERVER_URL;
     return {
         provider: 'github-actions',
         commit,
         branch,
         baseBranch,
         prNumber: prNumber && !isNaN(prNumber) ? prNumber : undefined,
-        repository: process.env.GITHUB_REPOSITORY
+        repository,
+        trigger: {
+            runId,
+            runAttempt: process.env.GITHUB_RUN_ATTEMPT || undefined,
+            actor: process.env.GITHUB_ACTOR || undefined,
+            workflow: process.env.GITHUB_WORKFLOW || undefined,
+            eventName: process.env.GITHUB_EVENT_NAME || undefined,
+            runUrl: serverUrl && repository ? `${serverUrl}/${repository}/actions/runs/${runId}` : undefined
+        }
     };
 };
 const detectGitLabCI = () => {
@@ -47,7 +71,14 @@ const detectGitLabCI = () => {
         branch,
         baseBranch: process.env.CI_MERGE_REQUEST_TARGET_BRANCH_NAME || undefined,
         prNumber: mrIid ? parseInt(mrIid, 10) : undefined,
-        repository: undefined
+        repository: process.env.CI_PROJECT_PATH || undefined,
+        trigger: {
+            runId: pipelineId,
+            actor: process.env.GITLAB_USER_LOGIN || undefined,
+            workflow: process.env.CI_JOB_NAME || undefined,
+            eventName: process.env.CI_PIPELINE_SOURCE || undefined,
+            runUrl: process.env.CI_PIPELINE_URL || undefined
+        }
     };
 };
 /**

package/dist/client.d.ts

@@ -1,9 +1,25 @@
-import type { CreateBuildResponse, ListBuildsResponse, PipelineFinalizeResponse, PresignUploadResponse, ScreenshotManifestEntry, SubmitShardResponse } from '@pixeyedev/shared';
+import type { CreateBuildResponse, ListBuildsResponse, PipelineFinalizeResponse, PresignUploadResponse, ScreenshotFormat, ScreenshotManifestEntry, SubmitShardResponse } from '@pixeyedev/shared';
 export declare class PixeyeError extends Error {
     status: number;
     path: string;
     body: string;
-    constructor(status: number, path: string, body: string);
+    /**
+     * Where the failure came from. `'api'` = the Pixeye control-plane (a 4xx
+     * here can be a customer misconfig — token/plan/permissions). `'r2'` = a
+     * data-plane PUT to R2 via a presigned URL (a 403/404 here is a Pixeye-side
+     * fault — expired URL, bucket/credential, clock skew — NEVER the customer's).
+     * Used by `isUploadMisconfig` so an R2 outage can't fail a customer's CI.
+     */
+    origin: 'api' | 'r2';
+    constructor(status: number, path: string, body: string, 
+    /**
+     * Where the failure came from. `'api'` = the Pixeye control-plane (a 4xx
+     * here can be a customer misconfig — token/plan/permissions). `'r2'` = a
+     * data-plane PUT to R2 via a presigned URL (a 403/404 here is a Pixeye-side
+     * fault — expired URL, bucket/credential, clock skew — NEVER the customer's).
+     * Used by `isUploadMisconfig` so an R2 outage can't fail a customer's CI.
+     */
+    origin?: 'api' | 'r2');
 }
 export interface PixeyeClientOptions {
     serverUrl: string;
@@ -30,7 +46,7 @@ export declare class PixeyeClient {
     presignUpload(opts: {
         buildId: string;
         hashes: string[];
-        formats?: Record<string, 'png' | 'webp'>;
+        formats?: Record<string, ScreenshotFormat>;
     }): Promise<PresignUploadResponse>;
     uploadFile(presignedUrl: string, buffer: Buffer, contentType: string): Promise<void>;
     submitShard(opts: {
@@ -43,6 +59,12 @@ export declare class PixeyeClient {
         branch: string;
     }): Promise<ListBuildsResponse>;
     finalizePipeline(pipelineId: string): Promise<PipelineFinalizeResponse>;
-    checkFileExists(hash: string): Promise<boolean>;
-    uploadLegacy(buffer: Buffer, hash: string, filename: string): Promise<void>;
+    /** `format` is the SNIFFED format of the bytes we would upload, and it
+     *  scopes the probe to that exact key: the same hash stored under another
+     *  extension by an older CLI is not this file. */
+    checkFileExists(hash: string, format?: ScreenshotFormat): Promise<boolean>;
+    /** `format` decides the stored key's extension server-side, so it must be
+     *  the same sniffed value the shard manifest carries. Older servers ignore
+     *  the field and keep storing under `.png`. */
+    uploadLegacy(buffer: Buffer, hash: string, filename: string, format?: ScreenshotFormat): Promise<void>;
 }

package/dist/client.js

@@ -1,17 +1,32 @@
-import { CreateBuildResponseSchema, ListBuildsResponseSchema, PipelineFinalizeResponseSchema, PresignUploadResponseSchema, SubmitShardResponseSchema } from '@pixeyedev/shared';
+import { createRequire } from 'node:module';
+import { CONTENT_TYPE_BY_FORMAT, CreateBuildResponseSchema, ListBuildsResponseSchema, PipelineFinalizeResponseSchema, PresignUploadResponseSchema, SubmitShardResponseSchema } from '@pixeyedev/shared';
 import { isRetryableHttpError, maskPresignedUrl, withRetry } from './retry.js';
 export class PixeyeError extends Error {
     status;
     path;
     body;
-    constructor(status, path, body) {
+    origin;
+    constructor(status, path, body, 
+    /**
+     * Where the failure came from. `'api'` = the Pixeye control-plane (a 4xx
+     * here can be a customer misconfig — token/plan/permissions). `'r2'` = a
+     * data-plane PUT to R2 via a presigned URL (a 403/404 here is a Pixeye-side
+     * fault — expired URL, bucket/credential, clock skew — NEVER the customer's).
+     * Used by `isUploadMisconfig` so an R2 outage can't fail a customer's CI.
+     */
+    origin = 'api') {
         super(`Pixeye API ${path} failed (${status}): ${body}`);
         this.status = status;
         this.path = path;
         this.body = body;
+        this.origin = origin;
         this.name = 'PixeyeError';
     }
 }
+const { version } = createRequire(import.meta.url)('../package.json');
+/** What the API records on a build so a failed run can be matched to the client
+ *  that sent it: this package's version and the Node it ran on. */
+const USER_AGENT = `@pixeyedev/core/${version} node/${process.versions.node}`;
 export class PixeyeClient {
     serverUrl;
     token;
@@ -26,6 +41,7 @@ export class PixeyeClient {
             headers: {
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${this.token}`,
+                'User-Agent': USER_AGENT,
                 ...options.headers
             }
         });
@@ -67,7 +83,9 @@ export class PixeyeClient {
                 headers: { 'Content-Type': contentType }
             });
             if (!res.ok) {
-                throw new PixeyeError(res.status, maskedUrl, await res.text());
+                // 'r2' origin — a PUT failure here is Pixeye-side (expired presigned
+                // URL, bucket/creds, clock skew), never the customer's misconfig.
+                throw new PixeyeError(res.status, maskedUrl, await res.text(), 'r2');
             }
         }, isRetryableHttpError, {
             maxAttempts: 3,
@@ -102,15 +120,23 @@ export class PixeyeClient {
         });
         return PipelineFinalizeResponseSchema.parse(raw);
     }
-    async checkFileExists(hash) {
-        const result = await this.request(`/api/v1/upload/${hash}?token=${encodeURIComponent(this.token)}`);
+    /** `format` is the SNIFFED format of the bytes we would upload, and it
+     *  scopes the probe to that exact key: the same hash stored under another
+     *  extension by an older CLI is not this file. */
+    async checkFileExists(hash, format = 'png') {
+        const result = await this.request(`/api/v1/upload/${encodeURIComponent(hash)}?token=${encodeURIComponent(this.token)}` +
+            `&format=${encodeURIComponent(format)}`);
         return result.exists;
     }
-    async uploadLegacy(buffer, hash, filename) {
-        const blob = new Blob([new Uint8Array(buffer)], { type: 'image/png' });
+    /** `format` decides the stored key's extension server-side, so it must be
+     *  the same sniffed value the shard manifest carries. Older servers ignore
+     *  the field and keep storing under `.png`. */
+    async uploadLegacy(buffer, hash, filename, format = 'png') {
+        const blob = new Blob([new Uint8Array(buffer)], { type: CONTENT_TYPE_BY_FORMAT[format] });
         const formData = new FormData();
         formData.append('file', blob, filename);
         formData.append('hash', hash);
+        formData.append('format', format);
         formData.append('token', this.token);
         const url = `${this.serverUrl}/api/v1/upload`;
         const response = await fetch(url, { method: 'POST', body: formData });

package/dist/discover.d.ts

@@ -1,8 +1,10 @@
+import type { ScreenshotFormat } from '@pixeyedev/shared';
 export interface DiscoveredFile {
     filePath: string;
     name: string;
     fileHash: string;
-    format: 'png' | 'webp';
+    /** Sniffed from the bytes, not the extension — see `probeImage`. */
+    format: ScreenshotFormat;
     width: number;
     height: number;
     metadata?: Record<string, unknown>;

package/dist/discover.js

@@ -1,48 +1,7 @@
 import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { glob } from 'glob';
-const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
-const WEBP_RIFF = Buffer.from('RIFF');
-const WEBP_WEBP = Buffer.from('WEBP');
-const readPngDimensions = (buffer) => {
-    if (buffer.length < 24 || !buffer.subarray(0, 8).equals(PNG_SIGNATURE)) {
-        throw new Error('Invalid PNG file: missing or incorrect PNG signature');
-    }
-    const width = buffer.readUInt32BE(16);
-    const height = buffer.readUInt32BE(20);
-    return { width, height };
-};
-const readWebpDimensions = (buffer) => {
-    if (buffer.length < 30 ||
-        !buffer.subarray(0, 4).equals(WEBP_RIFF) ||
-        !buffer.subarray(8, 12).equals(WEBP_WEBP)) {
-        throw new Error('Invalid WebP file: missing RIFF/WEBP signature');
-    }
-    // VP8 lossy: chunk starts at offset 12, dimensions at offset 26-29
-    const chunk = buffer.subarray(12, 16).toString('ascii');
-    if (chunk === 'VP8 ') {
-        const width = buffer.readUInt16LE(26) & 0x3fff;
-        const height = buffer.readUInt16LE(28) & 0x3fff;
-        return { width, height };
-    }
-    // VP8L lossless: chunk starts at offset 12, dimensions encoded at offset 21
-    if (chunk === 'VP8L') {
-        const bits = buffer.readUInt32LE(21);
-        const width = (bits & 0x3fff) + 1;
-        const height = ((bits >> 14) & 0x3fff) + 1;
-        return { width, height };
-    }
-    // VP8X extended: dimensions at offset 24-29
-    if (chunk === 'VP8X') {
-        const width = (buffer.readUIntLE(24, 3) & 0xffffff) + 1;
-        const height = (buffer.readUIntLE(27, 3) & 0xffffff) + 1;
-        return { width, height };
-    }
-    throw new Error(`Unsupported WebP chunk type: ${chunk}`);
-};
-const readDimensions = (buffer, format) => {
-    return format === 'png' ? readPngDimensions(buffer) : readWebpDimensions(buffer);
-};
+import { probeImage, swapImageExtension } from './imageProbe.js';
 export const discoverScreenshots = async (directory) => {
     const files = await glob('**/*.{png,webp}', { cwd: directory, posix: true });
     files.sort();
@@ -50,12 +9,11 @@ export const discoverScreenshots = async (directory) => {
     for (const relativePath of files) {
         const filePath = `${directory}/${relativePath}`;
         const fileBuffer = await readFile(filePath);
-        const format = relativePath.endsWith('.webp') ? 'webp' : 'png';
         const fileHash = createHash('sha256').update(fileBuffer).digest('hex');
-        const { width, height } = readDimensions(fileBuffer, format);
-        const name = relativePath.replace(/\.(png|webp)$/, '');
+        const { format, width, height } = probeImage(fileBuffer, relativePath);
+        const name = swapImageExtension(relativePath, '');
         // Check for companion metadata file
-        const metadataPath = filePath.replace(/\.(png|webp)$/, '.pixeye.json');
+        const metadataPath = swapImageExtension(filePath, '.pixeye.json');
         let metadata;
         try {
             const metadataContent = await readFile(metadataPath, 'utf-8');

package/dist/imageProbe.d.ts

@@ -0,0 +1,22 @@
+import type { ScreenshotFormat } from '@pixeyedev/shared';
+/**
+ * Format + dimensions read from the FILE'S BYTES, never its name: Playwright
+ * writes `type: 'jpeg'` screenshots under `.png` paths, and trusting the
+ * extension failed the whole upload on "Invalid PNG file".
+ */
+export interface ProbedImage {
+    format: ScreenshotFormat;
+    width: number;
+    height: number;
+}
+/** Swap a screenshot's extension for `replacement` ('' strips it). One owner,
+ *  so the glob, the name strip and the sidecar lookup can never disagree. */
+export declare const swapImageExtension: (filePath: string, replacement: string) => string;
+/** Content sniff only — returns null when the bytes are none of the three. */
+export declare const sniffImageFormat: (buffer: Buffer) => ScreenshotFormat | null;
+/**
+ * Identify an image from its bytes. Throws naming `filePath` and what we
+ * accept — the CLI surfaces the message to a user staring at a CI log, so
+ * it must say which file is wrong.
+ */
+export declare const probeImage: (buffer: Buffer, filePath: string) => ProbedImage;

package/dist/imageProbe.js

@@ -0,0 +1,123 @@
+/** Every extension `discoverScreenshots` globs. Deliberately NOT jpg/jpeg:
+ *  the ask is JPEG BYTES under a `.png` name, not every jpg in the output
+ *  directory (owner 2026-09-02). Content decides `format`, the name does not. */
+const IMAGE_EXTENSION_RE = /\.(png|webp)$/;
+/** Swap a screenshot's extension for `replacement` ('' strips it). One owner,
+ *  so the glob, the name strip and the sidecar lookup can never disagree. */
+export const swapImageExtension = (filePath, replacement) => filePath.replace(IMAGE_EXTENSION_RE, replacement);
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const WEBP_RIFF = Buffer.from('RIFF');
+const WEBP_WEBP = Buffer.from('WEBP');
+const isPng = (buffer) => buffer.length >= 8 && buffer.subarray(0, 8).equals(PNG_SIGNATURE);
+const isJpeg = (buffer) => buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff;
+const isWebp = (buffer) => buffer.length >= 12 &&
+    buffer.subarray(0, 4).equals(WEBP_RIFF) &&
+    buffer.subarray(8, 12).equals(WEBP_WEBP);
+/** Content sniff only — returns null when the bytes are none of the three. */
+export const sniffImageFormat = (buffer) => {
+    if (isPng(buffer)) {
+        return 'png';
+    }
+    if (isJpeg(buffer)) {
+        return 'jpeg';
+    }
+    if (isWebp(buffer)) {
+        return 'webp';
+    }
+    return null;
+};
+const readPngDimensions = (buffer) => {
+    if (buffer.length < 24) {
+        throw new Error('PNG header is truncated');
+    }
+    return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+};
+/** Markers that carry no frame header, so their payload is skipped whole. */
+const JPEG_SOF_EXCLUDED = new Set([0xc4, 0xc8, 0xcc]);
+/**
+ * Walk the marker chain to the first Start-Of-Frame (SOF0 baseline, SOF2
+ * progressive, the rest of 0xC0–0xCF) and read its height/width. There is no
+ * fixed offset: the segments before it vary by encoder.
+ */
+const readJpegDimensions = (buffer) => {
+    let offset = 2;
+    while (offset + 9 < buffer.length) {
+        if (buffer[offset] !== 0xff) {
+            offset++;
+            continue;
+        }
+        const marker = buffer[offset + 1];
+        // 0xFF is a fill byte: the spec allows any number before a marker, and
+        // reading it AS the marker walks the chain off into the entropy data.
+        if (marker === 0xff) {
+            offset++;
+            continue;
+        }
+        if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+            offset += 2;
+            continue;
+        }
+        const segmentLength = buffer.readUInt16BE(offset + 2);
+        if (marker >= 0xc0 && marker <= 0xcf && !JPEG_SOF_EXCLUDED.has(marker)) {
+            return { height: buffer.readUInt16BE(offset + 5), width: buffer.readUInt16BE(offset + 7) };
+        }
+        if (segmentLength < 2) {
+            break;
+        }
+        offset += 2 + segmentLength;
+    }
+    throw new Error('JPEG has no start-of-frame marker');
+};
+const readWebpDimensions = (buffer) => {
+    if (buffer.length < 30) {
+        throw new Error('WebP header is truncated');
+    }
+    const chunk = buffer.subarray(12, 16).toString('ascii');
+    // VP8 lossy: dimensions at offset 26-29, masked to 14 bits.
+    if (chunk === 'VP8 ') {
+        return {
+            width: buffer.readUInt16LE(26) & 0x3fff,
+            height: buffer.readUInt16LE(28) & 0x3fff
+        };
+    }
+    // VP8L lossless: 14-bit width and height packed from offset 21.
+    if (chunk === 'VP8L') {
+        const bits = buffer.readUInt32LE(21);
+        return { width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1 };
+    }
+    // VP8X extended: 24-bit canvas dimensions at offset 24-29.
+    if (chunk === 'VP8X') {
+        return {
+            width: (buffer.readUIntLE(24, 3) & 0xffffff) + 1,
+            height: (buffer.readUIntLE(27, 3) & 0xffffff) + 1
+        };
+    }
+    throw new Error(`Unsupported WebP chunk type: ${chunk}`);
+};
+/**
+ * Identify an image from its bytes. Throws naming `filePath` and what we
+ * accept — the CLI surfaces the message to a user staring at a CI log, so
+ * it must say which file is wrong.
+ */
+export const probeImage = (buffer, filePath) => {
+    const format = sniffImageFormat(buffer);
+    if (format === null) {
+        throw new Error(`${filePath} is not a PNG, JPEG or WebP image (the file is corrupt, ` +
+            `truncated, or a different format saved under an image extension)`);
+    }
+    try {
+        const dimensions = format === 'png'
+            ? readPngDimensions(buffer)
+            : format === 'jpeg'
+                ? readJpegDimensions(buffer)
+                : readWebpDimensions(buffer);
+        if (dimensions.width <= 0 || dimensions.height <= 0) {
+            throw new Error(`reported ${dimensions.width}x${dimensions.height}`);
+        }
+        return { format, ...dimensions };
+    }
+    catch (err) {
+        throw new Error(`${filePath} looks like ${format.toUpperCase()} but its dimensions could not be ` +
+            `read (${err.message}) — the file is probably truncated`);
+    }
+};

package/dist/index.d.ts

@@ -6,7 +6,10 @@ export type { CIEnvironment } from './ci.js';
 export { detectBaseBranchFromGit, detectCIEnvironment } from './ci.js';
 export type { DiscoveredFile } from './discover.js';
 export { discoverScreenshots } from './discover.js';
+export type { ProbedImage } from './imageProbe.js';
+export { probeImage, sniffImageFormat, swapImageExtension } from './imageProbe.js';
 export { runParallel } from './parallel.js';
 export type { RetryOptions } from './retry.js';
 export { isRetryableHttpError, maskPresignedUrl, withRetry } from './retry.js';
 export { DEFAULT_SERVER_URL, DEFAULT_UPLOAD_CONCURRENCY } from './constants.js';
+export { isUploadMisconfig, renderUploadFailureBanner, resolveFailOnError, uploadErrorSummary } from './uploadError.js';

package/dist/index.js

@@ -2,8 +2,10 @@ export { PixeyeClient, PixeyeError } from './client.js';
 export { parseYamlLike, readEnvConfig, readGlobalConfig, readProjectConfig, resolveConfig, writeGlobalConfig, writeProjectConfig } from './config.js';
 export { detectBaseBranchFromGit, detectCIEnvironment } from './ci.js';
 export { discoverScreenshots } from './discover.js';
+export { probeImage, sniffImageFormat, swapImageExtension } from './imageProbe.js';
 // Parallel execution
 export { runParallel } from './parallel.js';
 export { isRetryableHttpError, maskPresignedUrl, withRetry } from './retry.js';
 // Constants
 export { DEFAULT_SERVER_URL, DEFAULT_UPLOAD_CONCURRENCY } from './constants.js';
+export { isUploadMisconfig, renderUploadFailureBanner, resolveFailOnError, uploadErrorSummary } from './uploadError.js';

package/dist/uploadError.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Classify an upload failure and render a loud banner — shared by the Playwright
+ * reporter and the CLI so a lapsed plan / bad token surfaces identically (P0-2).
+ *
+ * The rule: distinguish the CUSTOMER's misconfiguration (they must act) from a
+ * transient / our-side fault (their CI should not break over our hiccup).
+ */
+/**
+ * True when the failure is the customer's configuration/billing, not ours.
+ * A `PixeyeError` from the R2 data-plane (`origin: 'r2'`) is EXCLUDED — a
+ * 403/404 on a presigned PUT (expired URL, bucket/creds, clock skew) is a
+ * Pixeye-side fault and must never fail the customer's CI.
+ */
+export declare const isUploadMisconfig: (err: unknown) => boolean;
+/**
+ * One-line `HTTP <status> — <detail>` summary. Prefers the error's `body`
+ * (the meaningful server code, e.g. `SUBSCRIPTION_CANCELLED`) over the full
+ * `PixeyeError.message`, which already embeds the status (avoids `HTTP 402 —
+ * Pixeye API … failed (402): …`).
+ */
+export declare const uploadErrorSummary: (err: unknown) => string;
+/**
+ * Resolve the fail-on-error setting identically for the reporter and CLI: fail
+ * by default; opt out via EITHER an explicit `false` option OR
+ * `PIXEYE_FAIL_ON_ERROR=false`. (The CLI's commander always supplies a boolean
+ * option; the reporter's is optional — this keeps both consistent.)
+ */
+export declare const resolveFailOnError: (option: boolean | undefined, env: string | undefined) => boolean;
+/**
+ * A bright, unmissable banner for a rejected upload. `willFail` toggles the
+ * closing line between "failing this step" and "opted out — passing anyway".
+ */
+export declare const renderUploadFailureBanner: (err: unknown, opts: {
+    willFail: boolean;
+}) => string;

package/dist/uploadError.js

@@ -0,0 +1,83 @@
+/**
+ * Classify an upload failure and render a loud banner — shared by the Playwright
+ * reporter and the CLI so a lapsed plan / bad token surfaces identically (P0-2).
+ *
+ * The rule: distinguish the CUSTOMER's misconfiguration (they must act) from a
+ * transient / our-side fault (their CI should not break over our hiccup).
+ */
+/**
+ * HTTP statuses that mean the CUSTOMER must act — a bad/absent token (401),
+ * a lapsed subscription or exceeded quota (402), insufficient permissions
+ * (403), or a wrong project/endpoint (404). These fail CI by default so a run
+ * can't pass green while zero screenshots reached Pixeye. EVERYTHING else
+ * (429 rate-limit, 5xx, network, timeouts, no status) is transient / our fault
+ * → warn, never break their CI.
+ */
+const MISCONFIG_STATUSES = [401, 402, 403, 404];
+const statusOf = (err) => {
+    const status = err?.status;
+    return typeof status === 'number' ? status : undefined;
+};
+/**
+ * True when the failure is the customer's configuration/billing, not ours.
+ * A `PixeyeError` from the R2 data-plane (`origin: 'r2'`) is EXCLUDED — a
+ * 403/404 on a presigned PUT (expired URL, bucket/creds, clock skew) is a
+ * Pixeye-side fault and must never fail the customer's CI.
+ */
+export const isUploadMisconfig = (err) => {
+    if (err?.origin === 'r2') {
+        return false;
+    }
+    const status = statusOf(err);
+    return status !== undefined && MISCONFIG_STATUSES.includes(status);
+};
+/**
+ * One-line `HTTP <status> — <detail>` summary. Prefers the error's `body`
+ * (the meaningful server code, e.g. `SUBSCRIPTION_CANCELLED`) over the full
+ * `PixeyeError.message`, which already embeds the status (avoids `HTTP 402 —
+ * Pixeye API … failed (402): …`).
+ */
+export const uploadErrorSummary = (err) => {
+    const status = statusOf(err);
+    const body = err?.body;
+    const detail = typeof body === 'string' && body.length > 0
+        ? body
+        : err instanceof Error
+            ? err.message
+            : String(err);
+    return status !== undefined ? `HTTP ${status} — ${detail}` : detail;
+};
+/**
+ * Resolve the fail-on-error setting identically for the reporter and CLI: fail
+ * by default; opt out via EITHER an explicit `false` option OR
+ * `PIXEYE_FAIL_ON_ERROR=false`. (The CLI's commander always supplies a boolean
+ * option; the reporter's is optional — this keeps both consistent.)
+ */
+export const resolveFailOnError = (option, env) => option !== false && env !== 'false';
+/**
+ * A bright, unmissable banner for a rejected upload. `willFail` toggles the
+ * closing line between "failing this step" and "opted out — passing anyway".
+ */
+export const renderUploadFailureBanner = (err, opts) => {
+    const line = '━'.repeat(64);
+    const footer = opts.willFail
+        ? [
+            '  Failing this step so it cannot pass silently. Fix the above, or pass',
+            '  failOnError: false (reporter) / --no-fail-on-error (CLI) to opt out.'
+        ]
+        : ['  failOnError is OFF — this step passes despite the lost coverage.'];
+    return [
+        '',
+        `\x1b[31m\x1b[1m${line}`,
+        `  ✗ PIXEYE UPLOAD REJECTED — ${uploadErrorSummary(err)}`,
+        '',
+        '  Your screenshots did NOT reach Pixeye. Visual coverage for this run is',
+        '  LOST. This is a configuration or billing problem on your account (API',
+        '  token, subscription/quota, or project permissions) — not a transient',
+        '  Pixeye outage.',
+        '',
+        ...footer,
+        `${line}\x1b[0m`,
+        ''
+    ].join('\n');
+};

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@pixeyedev/core",
-  "version": "0.4.4",
+  "version": "0.4.6",
+  "license": "MIT",
   "private": false,
   "type": "module",
   "files": [
@@ -16,6 +17,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "prepack": "rm -rf dist && npm run build",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "lint": "echo 'ok'",