@pixeyedev/core 0.4.3 → 0.4.5

package/dist/client.d.ts

@@ -3,7 +3,23 @@ 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;

package/dist/client.js

@@ -1,13 +1,24 @@
 import { 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';
     }
 }
@@ -58,14 +69,25 @@ export class PixeyeClient {
         return PresignUploadResponseSchema.parse(raw);
     }
     async uploadFile(presignedUrl, buffer, contentType) {
-        const res = await fetch(presignedUrl, {
-            method: 'PUT',
-            body: new Uint8Array(buffer),
-            headers: { 'Content-Type': contentType }
+        const maskedUrl = maskPresignedUrl(presignedUrl);
+        await withRetry(async () => {
+            const res = await fetch(presignedUrl, {
+                method: 'PUT',
+                body: new Uint8Array(buffer),
+                headers: { 'Content-Type': contentType }
+            });
+            if (!res.ok) {
+                // '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,
+            baseDelayMs: 1000,
+            onRetry: (attempt, err) => {
+                console.warn(`[pixeye] Upload retry ${attempt}/3: ${err.message}`);
+            }
         });
-        if (!res.ok) {
-            throw new PixeyeError(res.status, presignedUrl, await res.text());
-        }
     }
     async submitShard(opts) {
         const raw = await this.request(`/api/v1/builds/${opts.buildId}/shards`, {

package/dist/index.d.ts

@@ -7,4 +7,7 @@ export { detectBaseBranchFromGit, detectCIEnvironment } from './ci.js';
 export type { DiscoveredFile } from './discover.js';
 export { discoverScreenshots } from './discover.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

@@ -4,5 +4,7 @@ export { detectBaseBranchFromGit, detectCIEnvironment } from './ci.js';
 export { discoverScreenshots } from './discover.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/retry.d.ts

@@ -0,0 +1,14 @@
+export interface RetryOptions {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    onRetry?: (attempt: number, error: Error) => void;
+}
+/**
+ * Retry an async function with exponential backoff + jitter.
+ * Only retries on errors where shouldRetry returns true.
+ */
+export declare const withRetry: <T>(fn: () => Promise<T>, shouldRetry: (error: unknown) => boolean, opts?: RetryOptions) => Promise<T>;
+/** Returns true for HTTP 429/5xx responses or transient network errors. */
+export declare const isRetryableHttpError: (error: unknown) => boolean;
+/** Mask presigned URL signature for safe error logging. */
+export declare const maskPresignedUrl: (url: string) => string;

package/dist/retry.js

@@ -0,0 +1,40 @@
+/**
+ * Retry an async function with exponential backoff + jitter.
+ * Only retries on errors where shouldRetry returns true.
+ */
+export const withRetry = async (fn, shouldRetry, opts = {}) => {
+    const maxAttempts = opts.maxAttempts ?? 3;
+    const baseDelayMs = opts.baseDelayMs ?? 1000;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            if (attempt === maxAttempts || !shouldRetry(error)) {
+                throw error;
+            }
+            // Exponential backoff with equal jitter (half deterministic + half random)
+            const exponential = baseDelayMs * Math.pow(2, attempt - 1);
+            const delay = exponential * (0.5 + 0.5 * Math.random());
+            opts.onRetry?.(attempt, error instanceof Error ? error : new Error(String(error)));
+            await new Promise(r => setTimeout(r, delay));
+        }
+    }
+    throw new Error('Unreachable');
+};
+const TRANSIENT_NETWORK_RE = /fetch failed|ECONNRESET|ETIMEDOUT|ECONNREFUSED|ENOTFOUND|EPIPE|socket hang up/i;
+/** Returns true for HTTP 429/5xx responses or transient network errors. */
+export const isRetryableHttpError = (error) => {
+    // Check status code first (authoritative when present)
+    const status = error?.status;
+    if (status !== undefined) {
+        return status === 429 || (status >= 500 && status < 600);
+    }
+    // Fall back to message-based detection for genuine network errors (no HTTP response)
+    if (error instanceof Error && TRANSIENT_NETWORK_RE.test(error.message)) {
+        return true;
+    }
+    return false;
+};
+/** Mask presigned URL signature for safe error logging. */
+export const maskPresignedUrl = (url) => url.split('?')[0] + '?[signature-masked]';

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/dist/utils/parseShardInt.d.ts

@@ -0,0 +1,23 @@
+/**
+ * F-095: parse shard-related env vars (PIXEYE_SHARD_INDEX,
+ * PIXEYE_SHARD_TOTAL, CYPRESS_SPLIT_INDEX, CURRENTS_PARALLEL_INDEX, …)
+ * with a NaN guard.
+ *
+ * Bare `parseInt('abc', 10)` returns NaN; `JSON.stringify({ index: NaN })`
+ * coerces to `null` and the API rejects with a confusing
+ * "Validation failed: index must be a number" error 30s deep into a CI
+ * pipeline. Failing fast at parse time with a clear message identifying
+ * the offending env var lets users fix `PIXEYE_SHARD_INDEX=` typos
+ * without running the test suite.
+ *
+ * The helper is intentionally permissive about the shape: callers pass
+ * the env var name so the error message is self-explanatory. Returns
+ * `undefined` when the value is empty/missing (so callers can default).
+ */
+export declare const parseShardInt: (value: string | undefined | null, name: string) => number;
+/**
+ * Same as `parseShardInt` but returns `undefined` when the value is
+ * missing — useful when the env var is optional and the caller will
+ * fall back to a default. Still throws on a non-numeric explicit value.
+ */
+export declare const parseShardIntOptional: (value: string | undefined | null, name: string) => number | undefined;

package/dist/utils/parseShardInt.js

@@ -0,0 +1,41 @@
+/**
+ * F-095: parse shard-related env vars (PIXEYE_SHARD_INDEX,
+ * PIXEYE_SHARD_TOTAL, CYPRESS_SPLIT_INDEX, CURRENTS_PARALLEL_INDEX, …)
+ * with a NaN guard.
+ *
+ * Bare `parseInt('abc', 10)` returns NaN; `JSON.stringify({ index: NaN })`
+ * coerces to `null` and the API rejects with a confusing
+ * "Validation failed: index must be a number" error 30s deep into a CI
+ * pipeline. Failing fast at parse time with a clear message identifying
+ * the offending env var lets users fix `PIXEYE_SHARD_INDEX=` typos
+ * without running the test suite.
+ *
+ * The helper is intentionally permissive about the shape: callers pass
+ * the env var name so the error message is self-explanatory. Returns
+ * `undefined` when the value is empty/missing (so callers can default).
+ */
+export const parseShardInt = (value, name) => {
+    if (value === undefined || value === null || value === '') {
+        throw new Error(`${name} must be set`);
+    }
+    const parsed = parseInt(value, 10);
+    if (Number.isNaN(parsed)) {
+        throw new Error(`${name} must be an integer (got ${JSON.stringify(value)})`);
+    }
+    return parsed;
+};
+/**
+ * Same as `parseShardInt` but returns `undefined` when the value is
+ * missing — useful when the env var is optional and the caller will
+ * fall back to a default. Still throws on a non-numeric explicit value.
+ */
+export const parseShardIntOptional = (value, name) => {
+    if (value === undefined || value === null || value === '') {
+        return undefined;
+    }
+    const parsed = parseInt(value, 10);
+    if (Number.isNaN(parsed)) {
+        throw new Error(`${name} must be an integer (got ${JSON.stringify(value)})`);
+    }
+    return parsed;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixeyedev/core",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "private": false,
   "type": "module",
   "files": [