@pixeyedev/core 0.4.4 → 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

@@ -4,11 +4,21 @@ 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';
     }
 }
@@ -67,7 +77,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,

package/dist/index.d.ts

@@ -10,3 +10,4 @@ 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

@@ -7,3 +7,4 @@ 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/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.4",
+  "version": "0.4.5",
   "private": false,
   "type": "module",
   "files": [