@vizzly-testing/cli 0.20.0 → 0.20.1-beta.1

package/dist/api/endpoints.js

@@ -0,0 +1,314 @@
+/**
+ * API Endpoints - Functions for each API operation
+ *
+ * Each function takes a client as the first parameter and returns the API result.
+ * This keeps the functions pure (no hidden state) and easily testable.
+ */
+
+import { VizzlyError } from '../errors/vizzly-error.js';
+import * as output from '../utils/output.js';
+import { buildBuildPayload, buildEndpointWithParams, buildQueryParams, buildScreenshotCheckObject, buildScreenshotPayload, buildShaCheckPayload, computeSha256, findScreenshotBySha, shaExists } from './core.js';
+
+// ============================================================================
+// Build Endpoints
+// ============================================================================
+
+/**
+ * Get build information
+ * @param {Object} client - API client
+ * @param {string} buildId - Build ID
+ * @param {string|null} include - Optional include parameter (e.g., 'screenshots')
+ * @returns {Promise<Object>} Build data
+ */
+export async function getBuild(client, buildId, include = null) {
+  let endpoint = `/api/sdk/builds/${buildId}`;
+  if (include) {
+    endpoint = buildEndpointWithParams(endpoint, {
+      include
+    });
+  }
+  return client.request(endpoint);
+}
+
+/**
+ * Get builds for a project
+ * @param {Object} client - API client
+ * @param {Object} filters - Filter options
+ * @returns {Promise<Array>} List of builds
+ */
+export async function getBuilds(client, filters = {}) {
+  let query = buildQueryParams(filters);
+  let endpoint = `/api/sdk/builds${query ? `?${query}` : ''}`;
+  return client.request(endpoint);
+}
+
+/**
+ * Create a new build
+ * @param {Object} client - API client
+ * @param {Object} metadata - Build metadata
+ * @returns {Promise<Object>} Created build data
+ */
+export async function createBuild(client, metadata) {
+  let payload = buildBuildPayload(metadata);
+  return client.request('/api/sdk/builds', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      build: payload
+    })
+  });
+}
+
+/**
+ * Update build status
+ * @param {Object} client - API client
+ * @param {string} buildId - Build ID
+ * @param {string} status - Build status (pending|running|completed|failed)
+ * @param {number|null} executionTimeMs - Execution time in milliseconds
+ * @returns {Promise<Object>} Updated build data
+ */
+export async function updateBuildStatus(client, buildId, status, executionTimeMs = null) {
+  let body = {
+    status
+  };
+  if (executionTimeMs != null) {
+    body.executionTimeMs = executionTimeMs;
+  }
+  return client.request(`/api/sdk/builds/${buildId}/status`, {
+    method: 'PUT',
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(body)
+  });
+}
+
+/**
+ * Finalize a build (convenience wrapper for updateBuildStatus)
+ * @param {Object} client - API client
+ * @param {string} buildId - Build ID
+ * @param {boolean} success - Whether the build succeeded
+ * @param {number|null} executionTimeMs - Execution time in milliseconds
+ * @returns {Promise<Object>} Finalized build data
+ */
+export async function finalizeBuild(client, buildId, success = true, executionTimeMs = null) {
+  let status = success ? 'completed' : 'failed';
+  return updateBuildStatus(client, buildId, status, executionTimeMs);
+}
+
+/**
+ * Get TDD baselines for a build
+ * @param {Object} client - API client
+ * @param {string} buildId - Build ID
+ * @returns {Promise<Object>} { build, screenshots, signatureProperties }
+ */
+export async function getTddBaselines(client, buildId) {
+  return client.request(`/api/sdk/builds/${buildId}/tdd-baselines`);
+}
+
+// ============================================================================
+// Screenshot Endpoints
+// ============================================================================
+
+/**
+ * Check if SHAs already exist on the server
+ * @param {Object} client - API client
+ * @param {Array} screenshots - Screenshots to check (objects with sha256, or string SHAs)
+ * @param {string} buildId - Build ID for screenshot record creation
+ * @returns {Promise<Object>} { existing, missing, screenshots }
+ */
+export async function checkShas(client, screenshots, buildId) {
+  try {
+    let payload = buildShaCheckPayload(screenshots, buildId);
+    return await client.request('/api/sdk/check-shas', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(payload)
+    });
+  } catch (error) {
+    // Continue without deduplication on error
+    output.debug('sha-check', 'failed, continuing without deduplication', {
+      error: error.message
+    });
+
+    // Extract SHAs for fallback response
+    let shaList = Array.isArray(screenshots) && screenshots.length > 0 && typeof screenshots[0] === 'object' ? screenshots.map(s => s.sha256) : screenshots;
+    return {
+      existing: [],
+      missing: shaList,
+      screenshots: []
+    };
+  }
+}
+
+/**
+ * Upload a screenshot with SHA deduplication
+ * @param {Object} client - API client
+ * @param {string} buildId - Build ID
+ * @param {string} name - Screenshot name
+ * @param {Buffer} buffer - Screenshot data
+ * @param {Object} metadata - Additional metadata
+ * @param {boolean} skipDedup - Skip SHA deduplication (uploadAll mode)
+ * @returns {Promise<Object>} Upload result
+ */
+export async function uploadScreenshot(client, buildId, name, buffer, metadata = {}, skipDedup = false) {
+  // Skip SHA deduplication if requested
+  if (skipDedup) {
+    let payload = buildScreenshotPayload(name, buffer, metadata);
+    return client.request(`/api/sdk/builds/${buildId}/screenshots`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(payload)
+    });
+  }
+
+  // Normal flow with SHA deduplication
+  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
+    };
+  }
+
+  // File doesn't exist, proceed with upload
+  let payload = buildScreenshotPayload(name, buffer, metadata, sha256);
+  return client.request(`/api/sdk/builds/${buildId}/screenshots`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(payload)
+  });
+}
+
+// ============================================================================
+// Comparison Endpoints
+// ============================================================================
+
+/**
+ * Get comparison information
+ * @param {Object} client - API client
+ * @param {string} comparisonId - Comparison ID
+ * @returns {Promise<Object>} Comparison data
+ */
+export async function getComparison(client, comparisonId) {
+  let response = await client.request(`/api/sdk/comparisons/${comparisonId}`);
+  return response.comparison;
+}
+
+/**
+ * Search for comparisons by name
+ * @param {Object} client - API client
+ * @param {string} name - Screenshot name to search for
+ * @param {Object} filters - Optional filters (branch, limit, offset)
+ * @returns {Promise<Object>} Search results with comparisons and pagination
+ */
+export async function searchComparisons(client, name, filters = {}) {
+  if (!name || typeof name !== 'string') {
+    throw new VizzlyError('name is required and must be a non-empty string');
+  }
+  let {
+    branch,
+    limit = 50,
+    offset = 0
+  } = filters;
+  let params = {
+    name,
+    limit: String(limit),
+    offset: String(offset)
+  };
+  if (branch) params.branch = branch;
+  let endpoint = buildEndpointWithParams('/api/sdk/comparisons/search', params);
+  return client.request(endpoint);
+}
+
+// ============================================================================
+// Hotspot Endpoints
+// ============================================================================
+
+/**
+ * Get hotspot analysis for a single screenshot
+ * @param {Object} client - API client
+ * @param {string} screenshotName - Screenshot name
+ * @param {Object} options - Optional settings
+ * @returns {Promise<Object>} Hotspot analysis data
+ */
+export async function getScreenshotHotspots(client, screenshotName, options = {}) {
+  let {
+    windowSize = 20
+  } = options;
+  let encodedName = encodeURIComponent(screenshotName);
+  let endpoint = buildEndpointWithParams(`/api/sdk/screenshots/${encodedName}/hotspots`, {
+    windowSize: String(windowSize)
+  });
+  return client.request(endpoint);
+}
+
+/**
+ * Batch get hotspot analysis for multiple screenshots
+ * @param {Object} client - API client
+ * @param {string[]} screenshotNames - Array of screenshot names
+ * @param {Object} options - Optional settings
+ * @returns {Promise<Object>} Hotspots keyed by screenshot name
+ */
+export async function getBatchHotspots(client, screenshotNames, options = {}) {
+  let {
+    windowSize = 20
+  } = options;
+  return client.request('/api/sdk/screenshots/hotspots', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      screenshot_names: screenshotNames,
+      windowSize
+    })
+  });
+}
+
+// ============================================================================
+// Auth/Token Endpoints
+// ============================================================================
+
+/**
+ * Get token context (organization and project info)
+ * @param {Object} client - API client
+ * @returns {Promise<Object>} Token context data
+ */
+export async function getTokenContext(client) {
+  return client.request('/api/sdk/token/context');
+}
+
+// ============================================================================
+// Parallel Build Endpoints
+// ============================================================================
+
+/**
+ * Finalize a parallel build
+ * @param {Object} client - API client
+ * @param {string} parallelId - Parallel ID to finalize
+ * @returns {Promise<Object>} Finalization result
+ */
+export async function finalizeParallelBuild(client, parallelId) {
+  return client.request(`/api/sdk/parallel/${parallelId}/finalize`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json'
+    }
+  });
+}

package/dist/api/index.js

@@ -0,0 +1,19 @@
+/**
+ * Vizzly API Module
+ *
+ * Functional API for interacting with the Vizzly platform.
+ *
+ * Usage:
+ *   import { createApiClient, getBuild, createBuild } from '../api/index.js';
+ *
+ *   let client = createApiClient({ token: 'xxx', command: 'run' });
+ *   let build = await getBuild(client, buildId);
+ */
+
+// Client factory
+export { createApiClient, DEFAULT_API_URL } from './client.js';
+// Core pure functions
+export { buildApiUrl, buildAuthHeader, buildBuildPayload, buildEndpointWithParams, buildQueryParams, buildRequestHeaders, buildScreenshotCheckObject, buildScreenshotPayload, buildShaCheckPayload, buildUserAgent, computeSha256, extractErrorBody, findScreenshotBySha, isAuthError, isRateLimited, parseApiError, partitionByShaExistence, shaExists, shouldRetryWithRefresh } from './core.js';
+
+// Endpoint functions
+export { checkShas, createBuild, finalizeBuild, finalizeParallelBuild, getBatchHotspots, getBuild, getBuilds, getComparison, getScreenshotHotspots, getTddBaselines, getTokenContext, searchComparisons, updateBuildStatus, uploadScreenshot } from './endpoints.js';

package/dist/auth/client.js

@@ -0,0 +1,91 @@
+/**
+ * Auth Client - HTTP client factory for authentication
+ *
+ * Creates a thin HTTP wrapper that can be injected into operations.
+ */
+
+import { getPackageVersion } from '../utils/package-info.js';
+import { buildAuthUserAgent, buildRequestHeaders, parseAuthError, parseAuthenticatedError } from './core.js';
+
+/**
+ * Parse response body based on content type
+ * @param {Response} response - Fetch response
+ * @returns {Promise<Object|string>} Parsed body
+ */
+async function parseResponseBody(response) {
+  try {
+    let contentType = response.headers.get('content-type');
+    if (contentType?.includes('application/json')) {
+      return await response.json();
+    }
+    return await response.text();
+  } catch {
+    return response.statusText || '';
+  }
+}
+
+/**
+ * Create an auth HTTP client
+ * @param {Object} options - Client options
+ * @param {string} options.baseUrl - API base URL
+ * @param {string} [options.userAgent] - Custom user agent
+ * @returns {Object} Auth client with request methods
+ */
+export function createAuthClient(options = {}) {
+  let {
+    baseUrl,
+    userAgent
+  } = options;
+  if (!userAgent) {
+    userAgent = buildAuthUserAgent(getPackageVersion());
+  }
+
+  /**
+   * Make an unauthenticated request
+   */
+  async function request(endpoint, fetchOptions = {}) {
+    let url = `${baseUrl}${endpoint}`;
+    let headers = buildRequestHeaders({
+      userAgent,
+      contentType: fetchOptions.headers?.['Content-Type'],
+      extra: fetchOptions.headers
+    });
+    let response = await fetch(url, {
+      ...fetchOptions,
+      headers
+    });
+    if (!response.ok) {
+      let body = await parseResponseBody(response);
+      throw parseAuthError(response.status, body, endpoint);
+    }
+    return response.json();
+  }
+
+  /**
+   * Make an authenticated request
+   */
+  async function authenticatedRequest(endpoint, accessToken, fetchOptions = {}) {
+    let url = `${baseUrl}${endpoint}`;
+    let headers = buildRequestHeaders({
+      userAgent,
+      accessToken,
+      contentType: fetchOptions.headers?.['Content-Type'],
+      extra: fetchOptions.headers
+    });
+    let response = await fetch(url, {
+      ...fetchOptions,
+      headers
+    });
+    if (!response.ok) {
+      let body = await parseResponseBody(response);
+      throw parseAuthenticatedError(response.status, body, endpoint);
+    }
+    return response.json();
+  }
+  return {
+    request,
+    authenticatedRequest,
+    getBaseUrl: () => baseUrl,
+    getUserAgent: () => userAgent
+  };
+}

package/dist/auth/core.js

@@ -0,0 +1,176 @@
+/**
+ * Auth Core - Pure functions for authentication logic
+ *
+ * No I/O, no side effects - just data transformations.
+ */
+
+import { AuthError, VizzlyError } from '../errors/vizzly-error.js';
+
+// ============================================================================
+// Header Building
+// ============================================================================
+
+/**
+ * Build Authorization header from access token
+ * @param {string|null} accessToken - Access token
+ * @returns {Object} Headers object with Authorization if token exists
+ */
+export function buildAuthHeader(accessToken) {
+  if (!accessToken) return {};
+  return {
+    Authorization: `Bearer ${accessToken}`
+  };
+}
+
+/**
+ * Build User-Agent header for auth requests
+ * @param {string} version - CLI version
+ * @returns {string} User-Agent string
+ */
+export function buildAuthUserAgent(version) {
+  return `vizzly-cli/${version} (auth)`;
+}
+
+/**
+ * Build complete headers for a request
+ * @param {Object} options - Header options
+ * @returns {Object} Complete headers object
+ */
+export function buildRequestHeaders({
+  userAgent,
+  accessToken,
+  contentType,
+  extra = {}
+}) {
+  return {
+    'User-Agent': userAgent,
+    ...(accessToken ? buildAuthHeader(accessToken) : {}),
+    ...(contentType ? {
+      'Content-Type': contentType
+    } : {}),
+    ...extra
+  };
+}
+
+// ============================================================================
+// Error Parsing
+// ============================================================================
+
+/**
+ * Parse error from API response
+ * @param {number} status - HTTP status code
+ * @param {Object|string} body - Response body (parsed JSON or text)
+ * @param {string} endpoint - API endpoint for context
+ * @returns {Error} Appropriate error type
+ */
+export function parseAuthError(status, body, _endpoint) {
+  let errorText = '';
+  if (typeof body === 'object' && body !== null) {
+    errorText = body.error || body.message || '';
+  } else if (typeof body === 'string') {
+    errorText = body;
+  }
+  if (status === 401) {
+    return new AuthError(errorText || 'Invalid credentials. Please check your email/username and password.');
+  }
+  if (status === 429) {
+    return new VizzlyError('Too many login attempts. Please try again later.', 'RATE_LIMIT_ERROR');
+  }
+  return new VizzlyError(`Authentication request failed: ${status}${errorText ? ` - ${errorText}` : ''}`, 'AUTH_REQUEST_ERROR');
+}
+
+/**
+ * Parse error for authenticated requests (different error messages)
+ * @param {number} status - HTTP status code
+ * @param {Object|string} body - Response body
+ * @param {string} endpoint - API endpoint
+ * @returns {Error} Appropriate error type
+ */
+export function parseAuthenticatedError(status, body, endpoint) {
+  let errorText = '';
+  if (typeof body === 'object' && body !== null) {
+    errorText = body.error || body.message || '';
+  } else if (typeof body === 'string') {
+    errorText = body;
+  }
+  if (status === 401) {
+    return new AuthError('Authentication token is invalid or expired. Please run "vizzly login" again.');
+  }
+  return new VizzlyError(`API request failed: ${status}${errorText ? ` - ${errorText}` : ''} (${endpoint})`, 'API_REQUEST_ERROR');
+}
+
+// ============================================================================
+// Payload Building
+// ============================================================================
+
+/**
+ * Build device poll request payload
+ * @param {string} deviceCode - Device code from initiate
+ * @returns {Object} Request payload
+ */
+export function buildDevicePollPayload(deviceCode) {
+  return {
+    device_code: deviceCode
+  };
+}
+
+/**
+ * Build refresh token request payload
+ * @param {string} refreshToken - Refresh token
+ * @returns {Object} Request payload
+ */
+export function buildRefreshPayload(refreshToken) {
+  return {
+    refreshToken
+  };
+}
+
+/**
+ * Build logout request payload
+ * @param {string} refreshToken - Refresh token to revoke
+ * @returns {Object} Request payload
+ */
+export function buildLogoutPayload(refreshToken) {
+  return {
+    refreshToken
+  };
+}
+
+// ============================================================================
+// Token Handling
+// ============================================================================
+
+/**
+ * Build token data for storage from API response
+ * @param {Object} response - API response with tokens
+ * @param {Object|null} existingUser - Existing user data to preserve
+ * @returns {Object} Token data for storage
+ */
+export function buildTokenData(response, existingUser = null) {
+  return {
+    accessToken: response.accessToken,
+    refreshToken: response.refreshToken,
+    expiresAt: response.expiresAt,
+    user: response.user || existingUser
+  };
+}
+
+/**
+ * Validate that tokens exist and have required fields
+ * @param {Object|null} auth - Auth tokens object
+ * @param {string} requiredField - Field that must exist ('accessToken' or 'refreshToken')
+ * @returns {{ valid: boolean, error: Error|null }}
+ */
+export function validateTokens(auth, requiredField = 'accessToken') {
+  if (!auth || !auth[requiredField]) {
+    let message = requiredField === 'refreshToken' ? 'No refresh token found. Please run "vizzly login" first.' : 'No authentication token found. Please run "vizzly login" first.';
+    return {
+      valid: false,
+      error: new AuthError(message)
+    };
+  }
+  return {
+    valid: true,
+    error: null
+  };
+}

package/dist/auth/index.js

@@ -0,0 +1,30 @@
+/**
+ * Auth Module - Public exports
+ *
+ * Provides functional authentication primitives:
+ * - core.js: Pure functions for headers, payloads, error parsing
+ * - client.js: HTTP client factory
+ * - operations.js: Auth operations with dependency injection
+ */
+
+// Re-export token store utilities for convenience
+import { clearAuthTokens, getAuthTokens, saveAuthTokens } from '../utils/global-config.js';
+export { clearAuthTokens, getAuthTokens, saveAuthTokens };
+// HTTP client factory
+export { createAuthClient } from './client.js';
+// Core pure functions
+export { buildAuthHeader, buildAuthUserAgent, buildDevicePollPayload, buildLogoutPayload, buildRefreshPayload, buildRequestHeaders, buildTokenData, parseAuthError, parseAuthenticatedError, validateTokens } from './core.js';
+// Auth operations (take dependencies as parameters)
+export { completeDeviceFlow, initiateDeviceFlow, isAuthenticated, logout, pollDeviceAuthorization, refresh, whoami } from './operations.js';
+
+/**
+ * Create a token store adapter from global-config functions
+ * Used by auth operations that need tokenStore parameter
+ */
+export function createTokenStore() {
+  return {
+    getTokens: getAuthTokens,
+    saveTokens: saveAuthTokens,
+    clearTokens: clearAuthTokens
+  };
+}