@browserstack/mcp-server 1.2.15-beta.2 → 1.2.16-beta.1

package/dist/lib/percy-api/client.js

@@ -1,275 +0,0 @@
-/**
- * Percy API HTTP client.
- *
- * Uses native `fetch` (consistent with existing Percy tools in this repo).
- * Handles JSON:API deserialization, rate limiting, and error enrichment.
- *
- * SECURITY: Token values are NEVER logged or exposed in error messages.
- */
-import { getPercyHeaders, getPercyApiBaseUrl } from "./auth.js";
-import { enrichPercyError } from "./errors.js";
-// ---------------------------------------------------------------------------
-// Helpers – kebab-case to camelCase
-// ---------------------------------------------------------------------------
-function kebabToCamel(str) {
-    return str.replace(/-([a-z0-9])/g, (_, char) => char.toUpperCase());
-}
-function camelCaseKeys(obj) {
-    if (obj === null || obj === undefined) {
-        return obj;
-    }
-    if (Array.isArray(obj)) {
-        return obj.map(camelCaseKeys);
-    }
-    if (typeof obj === "object") {
-        const result = {};
-        for (const [key, value] of Object.entries(obj)) {
-            const camelKey = kebabToCamel(key);
-            result[camelKey] =
-                value !== null && typeof value === "object"
-                    ? camelCaseKeys(value)
-                    : value;
-        }
-        return result;
-    }
-    return obj;
-}
-// ---------------------------------------------------------------------------
-// JSON:API Deserializer
-// ---------------------------------------------------------------------------
-/**
- * Builds a lookup index of included resources keyed by `type:id`.
- */
-function buildIncludedIndex(included) {
-    const index = new Map();
-    for (const resource of included) {
-        const flattened = flattenResource(resource);
-        index.set(`${resource.type}:${resource.id}`, flattened);
-    }
-    return index;
-}
-/**
- * Flattens a single JSON:API resource — merges `attributes` into the top
- * level alongside `id` and `type`, converting keys to camelCase.
- */
-function flattenResource(resource) {
-    const attrs = resource.attributes
-        ? camelCaseKeys(resource.attributes)
-        : {};
-    return {
-        id: resource.id,
-        type: resource.type,
-        ...attrs,
-    };
-}
-/**
- * Resolves relationships for a resource against the included index.
- * Returns the resolved object(s) or the raw { id, type } ref when not found.
- */
-function resolveRelationships(resource, index) {
-    if (!resource.relationships) {
-        return {};
-    }
-    const resolved = {};
-    for (const [relName, relValue] of Object.entries(resource.relationships)) {
-        const camelName = kebabToCamel(relName);
-        const { data } = relValue;
-        if (data === null || data === undefined) {
-            resolved[camelName] = null;
-        }
-        else if (Array.isArray(data)) {
-            resolved[camelName] = data.map((ref) => index.get(`${ref.type}:${ref.id}`) ?? { id: ref.id, type: ref.type });
-        }
-        else {
-            resolved[camelName] = index.get(`${data.type}:${data.id}`) ?? {
-                id: data.id,
-                type: data.type,
-            };
-        }
-    }
-    return resolved;
-}
-/**
- * Deserializes a JSON:API envelope into plain objects.
- *
- * - `data: null` → returns `null`
- * - `data: []` → returns `[]`
- * - `data: { ... }` → returns a single deserialized object
- * - `data: [{ ... }, ...]` → returns an array of deserialized objects
- */
-export function deserialize(envelope) {
-    const included = envelope.included ?? [];
-    const index = buildIncludedIndex(included);
-    if (envelope.data === null || envelope.data === undefined) {
-        return { data: null, meta: envelope.meta };
-    }
-    if (Array.isArray(envelope.data)) {
-        const records = envelope.data.map((resource) => ({
-            ...flattenResource(resource),
-            ...resolveRelationships(resource, index),
-        }));
-        return { data: records, meta: envelope.meta };
-    }
-    const record = {
-        ...flattenResource(envelope.data),
-        ...resolveRelationships(envelope.data, index),
-    };
-    return { data: record, meta: envelope.meta };
-}
-// ---------------------------------------------------------------------------
-// Rate Limit / Retry
-// ---------------------------------------------------------------------------
-const MAX_RETRIES = 3;
-const BASE_RETRY_DELAY_MS = 1_000;
-async function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-// ---------------------------------------------------------------------------
-// PercyClient
-// ---------------------------------------------------------------------------
-export class PercyClient {
-    config;
-    options;
-    constructor(config, options) {
-        this.config = config;
-        this.options = options ?? {};
-    }
-    // -----------------------------------------------------------------------
-    // Public HTTP methods
-    // -----------------------------------------------------------------------
-    /**
-     * GET request with optional query params and JSON:API `include`.
-     */
-    async get(path, params, includes) {
-        const url = this.buildUrl(path, params, includes);
-        return this.request("GET", url);
-    }
-    /**
-     * POST request with an optional JSON body.
-     */
-    async post(path, body) {
-        const url = this.buildUrl(path);
-        return this.request("POST", url, body);
-    }
-    /**
-     * PATCH request with an optional JSON body.
-     */
-    async patch(path, body) {
-        const url = this.buildUrl(path);
-        return this.request("PATCH", url, body);
-    }
-    /**
-     * DELETE request.
-     */
-    async del(path) {
-        const url = this.buildUrl(path);
-        await this.request("DELETE", url);
-    }
-    // -----------------------------------------------------------------------
-    // Internal
-    // -----------------------------------------------------------------------
-    buildUrl(path, params, includes) {
-        const base = getPercyApiBaseUrl();
-        // Ensure no double slashes between base and path
-        const normalizedPath = path.startsWith("/") ? path : `/${path}`;
-        const url = new URL(`${base}${normalizedPath}`);
-        if (params) {
-            for (const [key, value] of Object.entries(params)) {
-                url.searchParams.set(key, value);
-            }
-        }
-        if (includes && includes.length > 0) {
-            url.searchParams.set("include", includes.join(","));
-        }
-        return url.toString();
-    }
-    async request(method, url, body) {
-        const headers = await getPercyHeaders(this.config, {
-            scope: this.options.scope,
-            projectName: this.options.projectName,
-        });
-        let lastError;
-        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-            const fetchOptions = {
-                method,
-                headers,
-            };
-            if (body !== undefined) {
-                fetchOptions.body = JSON.stringify(body);
-            }
-            let response;
-            try {
-                response = await fetch(url, fetchOptions);
-            }
-            catch (networkError) {
-                lastError =
-                    networkError instanceof Error
-                        ? networkError
-                        : new Error(String(networkError));
-                // Network errors are not retryable via the rate-limit path,
-                // but we still respect the retry loop for consistency.
-                if (attempt < MAX_RETRIES) {
-                    await sleep(BASE_RETRY_DELAY_MS * Math.pow(2, attempt));
-                    continue;
-                }
-                throw lastError;
-            }
-            // 204 No Content
-            if (response.status === 204) {
-                return undefined;
-            }
-            // Rate limited — retry with backoff
-            if (response.status === 429) {
-                const retryAfter = response.headers.get("Retry-After");
-                const delayMs = retryAfter
-                    ? parseFloat(retryAfter) * 1_000
-                    : BASE_RETRY_DELAY_MS * Math.pow(2, attempt);
-                if (attempt < MAX_RETRIES) {
-                    await sleep(delayMs);
-                    continue;
-                }
-                // Exhausted retries — throw enriched error
-                let errorBody;
-                try {
-                    errorBody = await response.json();
-                }
-                catch {
-                    errorBody = undefined;
-                }
-                throw enrichPercyError(429, errorBody, `${method} ${url}`);
-            }
-            // Non-2xx error
-            if (!response.ok) {
-                let errorBody;
-                try {
-                    errorBody = await response.json();
-                }
-                catch {
-                    errorBody = undefined;
-                }
-                throw enrichPercyError(response.status, errorBody, `${method} ${url}`);
-            }
-            // Successful JSON response — deserialize JSON:API
-            const json = await response.json();
-            // If the response has a JSON:API `data` key, deserialize it
-            if (json && typeof json === "object" && "data" in json) {
-                const deserialized = deserialize(json);
-                // Unwrap: return the data directly (single object or array)
-                // Attach meta as a non-enumerable property so it's accessible but doesn't clutter
-                const result = deserialized.data;
-                if (result && typeof result === "object" && deserialized.meta) {
-                    Object.defineProperty(result, "__meta", {
-                        value: deserialized.meta,
-                        enumerable: false,
-                        writable: false,
-                    });
-                }
-                return result;
-            }
-            // Non-JSON:API response — return as-is
-            return json;
-        }
-        // Should not reach here, but satisfy TypeScript
-        throw lastError ?? new Error("Request failed after retries");
-    }
-}

package/dist/lib/percy-api/errors.d.ts

@@ -1,15 +0,0 @@
-/**
- * Percy API error enrichment module.
- * Maps Percy API error responses to actionable, user-friendly messages.
- */
-export declare class PercyApiError extends Error {
-    statusCode: number;
-    errorCode?: string;
-    body?: unknown;
-    constructor(message: string, statusCode: number, errorCode?: string, body?: unknown);
-}
-/**
- * Maps Percy API error responses to actionable messages.
- * Handles known error codes from Percy's JSON:API responses.
- */
-export declare function enrichPercyError(status: number, body: unknown, context?: string): PercyApiError;

package/dist/lib/percy-api/errors.js

@@ -1,52 +0,0 @@
-/**
- * Percy API error enrichment module.
- * Maps Percy API error responses to actionable, user-friendly messages.
- */
-export class PercyApiError extends Error {
-    statusCode;
-    errorCode;
-    body;
-    constructor(message, statusCode, errorCode, body) {
-        super(message);
-        this.name = "PercyApiError";
-        this.statusCode = statusCode;
-        this.errorCode = errorCode;
-        this.body = body;
-    }
-}
-/**
- * Maps Percy API error responses to actionable messages.
- * Handles known error codes from Percy's JSON:API responses.
- */
-export function enrichPercyError(status, body, context) {
-    const prefix = context ? `${context}: ` : "";
-    const errorBody = body;
-    const errors = (errorBody?.errors ?? []);
-    const firstError = errors[0];
-    const errorCode = (firstError?.code ?? firstError?.source);
-    const detail = (firstError?.detail ?? firstError?.title ?? "");
-    switch (status) {
-        case 401:
-            return new PercyApiError(`${prefix}Percy token is invalid or expired. Check PERCY_TOKEN environment variable.`, 401, errorCode, body);
-        case 403: {
-            if (errorCode === "project_rbac_access_denied") {
-                return new PercyApiError(`${prefix}Insufficient permissions. This operation requires write access to the project.`, 403, errorCode, body);
-            }
-            if (errorCode === "build_deleted") {
-                return new PercyApiError(`${prefix}This build has been deleted.`, 403, errorCode, body);
-            }
-            if (errorCode === "plan_history_exceeded") {
-                return new PercyApiError(`${prefix}This build is outside your plan's history limit.`, 403, errorCode, body);
-            }
-            return new PercyApiError(`${prefix}Forbidden: ${detail || "Access denied."}`, 403, errorCode, body);
-        }
-        case 404:
-            return new PercyApiError(`${prefix}Resource not found. Check the ID and try again.`, 404, errorCode, body);
-        case 422:
-            return new PercyApiError(`${prefix}Invalid request: ${detail || "Unprocessable entity."}`, 422, errorCode, body);
-        case 429:
-            return new PercyApiError(`${prefix}Rate limit exceeded. Try again shortly.`, 429, errorCode, body);
-        default:
-            return new PercyApiError(`${prefix}Percy API error (${status}): ${detail || "Unknown error"}`, status, errorCode, body);
-    }
-}

package/dist/lib/percy-api/formatter.d.ts

@@ -1,16 +0,0 @@
-/**
- * Markdown formatting utilities for Percy API responses.
- *
- * Each function transforms typed Percy API data into concise,
- * agent-readable markdown. All functions handle null/undefined
- * fields gracefully — showing "N/A" or omitting the section.
- */
-export declare function formatBuild(build: any): string;
-export declare function formatSnapshot(snapshot: any, comparisons?: any[]): string;
-export declare function formatComparison(comparison: any, options?: {
-    includeRegions?: boolean;
-}): string;
-export declare function formatSuggestions(suggestions: any[]): string;
-export declare function formatNetworkLogs(logs: any[]): string;
-export declare function formatBuildStatus(build: any): string;
-export declare function formatAiWarning(comparisons: any[]): string;