@argos-ci/core 5.1.1 → 5.1.3

package/dist/index.cjs

@@ -1,14 +1,14 @@
 exports.upload = async (...args) => {
-  const { upload } = await import("./index.js");
+  const { upload } = await import("./index.mjs");
   return upload(...args);
 };
 
 exports.finalize = async (...args) => {
-  const { finalize } = await import("./index.js");
+  const { finalize } = await import("./index.mjs");
   return finalize(...args);
 };
 
 exports.readConfig = async (...args) => {
-  const { readConfig } = await import("./index.js");
+  const { readConfig } = await import("./index.mjs");
   return readConfig(...args);
 };

package/dist/index.d.mts

@@ -0,0 +1,312 @@
+import { ArgosAPISchema } from "@argos-ci/api-client";
+import { ScreenshotMetadata } from "@argos-ci/util";
+
+//#region src/config.d.ts
+interface Config {
+  /**
+   * Base URL of the Argos API.
+   * Use this to target a self-hosted installation.
+   * @default "https://api.argos-ci.com/v2/"
+   */
+  apiBaseUrl: string;
+  /**
+   * Git commit SHA.
+   */
+  commit: string;
+  /**
+   * Git branch name of the build.
+   * @example "main", "develop", "release/1.0"
+   */
+  branch: string;
+  /**
+   * Argos repository access token.
+   */
+  token: string | null;
+  /**
+   * Custom build name.
+   * Useful for multi-build setups on the same commit.
+   */
+  buildName: string | null;
+  /**
+   * Whether this build is split across multiple parallel jobs.
+   * @default false
+   */
+  parallel: boolean;
+  /**
+   * Unique identifier shared by all parallel jobs.
+   */
+  parallelNonce: string | null;
+  /**
+   * Index of the current parallel job.
+   * Must be between 1 and `parallelTotal`, or null if not set.
+   */
+  parallelIndex: number | null;
+  /**
+   * Total number of parallel jobs.
+   * Use -1 if unknown, or null if not set.
+   */
+  parallelTotal: number | null;
+  /**
+   * Git branch used as the baseline for screenshot comparison.
+   */
+  referenceBranch: string | null;
+  /**
+   * Git commit SHA used as the baseline for screenshot comparison.
+   */
+  referenceCommit: string | null;
+  /**
+   * Repository slug of the source repository.
+   * Example: "my-org/my-repo" or "my-user/my-repo".
+   * If from a fork, this refers to the fork repository.
+   */
+  repository: string | null;
+  /**
+   * Repository slug of the original (base) repository.
+   * Example: "my-org/my-repo" or "my-user/my-repo".
+   * If from a fork, this refers to the base repository.
+   */
+  originalRepository: string | null;
+  /**
+   * CI job identifier (if provided by the CI environment).
+   */
+  jobId: string | null;
+  /**
+   * CI run identifier (if provided by the CI environment).
+   */
+  runId: string | null;
+  /**
+   * CI run attempt number (if provided by the CI environment).
+   */
+  runAttempt: number | null;
+  /**
+   * Pull request number associated with the build.
+   */
+  prNumber: number | null;
+  /**
+   * Pull request head commit SHA (if available).
+   */
+  prHeadCommit: string | null;
+  /**
+   * Pull request base branch (if available).
+   */
+  prBaseBranch: string | null;
+  /**
+   * Build mode to use.
+   * - "ci": Review visual changes introduced by a feature branch and prevent regressions.
+   * - "monitoring": Track visual changes outside the standard CI flow, either on a schedule or before a release.
+   * @see https://argos-ci.com/docs/build-modes
+   */
+  mode: "ci" | "monitoring" | null;
+  /**
+   * Name of the detected CI provider (if available).
+   * @example "github-actions", "gitlab-ci", "circleci"
+   */
+  ciProvider: string | null;
+  /**
+   * Diff sensitivity threshold between 0 and 1.
+   * Higher values make Argos less sensitive to differences.
+   */
+  threshold: number | null;
+  /**
+   * Base URL to use for preview links.
+   * @example "https://my-preview.example.com"
+   */
+  previewBaseUrl: string | null;
+  /**
+   * Skip this build.
+   * No screenshots are uploaded, and the commit status is marked as success.
+   */
+  skipped?: boolean;
+  /**
+   * Whether the environment is a merge queue.
+   */
+  mergeQueue?: boolean;
+  /**
+   * Whether this build contains only a subset of screenshots.
+   * This is useful when a build is created from an incomplete test suite where some tests are skipped.
+   */
+  subset?: boolean;
+}
+declare function readConfig(options?: Partial<Config>): Promise<Config>;
+declare function getConfigFromOptions({
+  parallel,
+  ...options
+}: Omit<Partial<Config>, "parallel"> & {
+  parallel?: {
+    /** Unique build ID for this parallel build */nonce: string; /** The number of parallel nodes being ran */
+    total: number; /** The index of the parallel node */
+    index?: number;
+  } | false | undefined;
+}): Promise<Config>;
+//#endregion
+//#region src/finalize.d.ts
+type FinalizeParameters = {
+  parallel?: {
+    nonce: string;
+  };
+};
+/**
+ * Finalize pending builds.
+ */
+declare function finalize(params: FinalizeParameters): Promise<{
+  builds: {
+    id: string;
+    number: number;
+    status: ("accepted" | "rejected") | ("no-changes" | "changes-detected") | ("expired" | "pending" | "progress" | "error" | "aborted");
+    conclusion: ("no-changes" | "changes-detected") | null;
+    stats: {
+      added: number;
+      removed: number;
+      unchanged: number;
+      changed: number;
+      ignored: number;
+      failure: number;
+      retryFailure: number;
+      total: number;
+    } | null;
+    metadata: {
+      testReport?: {
+        status: "passed" | "failed" | "timedout" | "interrupted";
+        stats?: {
+          startTime?: string | undefined;
+          duration?: number | undefined;
+        } | undefined;
+      } | undefined;
+    } | null;
+    url: string;
+    notification: {
+      description: string;
+      context: string;
+      github: {
+        state: "pending" | "success" | "error" | "failure";
+      };
+      gitlab: {
+        state: "pending" | "running" | "success" | "failed" | "canceled";
+      };
+    } | null;
+  }[];
+}>;
+//#endregion
+//#region src/upload.d.ts
+type BuildMetadata = ArgosAPISchema.components["schemas"]["BuildMetadata"];
+interface UploadParameters {
+  /**
+   * Globs that match image file paths to upload.
+   */
+  files?: string[];
+  /**
+   * Root directory used to resolve image paths.
+   * @default process.cwd()
+   */
+  root?: string;
+  /**
+   * Globs that match image file paths to exclude from upload.
+   * @default ["**\/*.{png,jpg,jpeg}"]
+   */
+  ignore?: string[];
+  /**
+   * Base URL of the Argos API.
+   * @default "https://api.argos-ci.com/v2/"
+   */
+  apiBaseUrl?: string;
+  /**
+   * Git commit SHA of the build.
+   */
+  commit?: string;
+  /**
+   * Git branch name of the build.
+   */
+  branch?: string;
+  /**
+   * Argos repository access token.
+   */
+  token?: string;
+  /**
+   * Pull request number associated with the build.
+   */
+  prNumber?: number;
+  /**
+   * Custom build name. Useful when triggering multiple Argos builds
+   * for the same commit.
+   */
+  buildName?: string;
+  /**
+   * Build mode to use.
+   * - "ci": Review the visual changes introduced by a feature branch and prevent regressions.
+   * - "monitoring": Track visual changes outside the standard CI flow, either on a schedule or before a release.
+   * @see https://argos-ci.com/docs/build-modes
+   * @default "ci"
+   */
+  mode?: "ci" | "monitoring";
+  /**
+   * Parallel test suite configuration.
+   * @default false
+   */
+  parallel?: {
+    /** Unique build identifier shared across parallel jobs. */nonce: string; /** Total number of parallel jobs, set to -1 to finalize manually. */
+    total: number; /** Index of the current job (must start from 1). */
+    index?: number;
+  } | false;
+  /**
+   * Branch used as the baseline for screenshot comparison.
+   */
+  referenceBranch?: string;
+  /**
+   * Commit SHA used as the baseline for screenshot comparison.
+   */
+  referenceCommit?: string;
+  /**
+   * Diff sensitivity threshold between 0 and 1.
+   * Higher values make Argos less sensitive to differences.
+   * @default 0.5
+   */
+  threshold?: number;
+  /**
+   * Additional build metadata.
+   */
+  metadata?: BuildMetadata;
+  /**
+   * Preview URL configuration.
+   * Can be a fixed base URL or a function to transform URLs dynamically.
+   */
+  previewUrl?: {
+    baseUrl: string;
+  } | ((url: string) => string);
+  /**
+   * Whether this build contains only a subset of screenshots.
+   * This is useful when a build is created from an incomplete test suite where some tests are skipped.
+   * @default false
+   */
+  subset?: boolean;
+}
+interface Screenshot {
+  hash: string;
+  optimizedPath: string;
+  metadata: ScreenshotMetadata | null;
+  threshold: number | null;
+  baseName: string | null;
+  pwTrace: {
+    path: string;
+    hash: string;
+  } | null;
+  name: string;
+  path: string;
+}
+/**
+ * Upload screenshots to Argos.
+ */
+declare function upload(params: UploadParameters): Promise<{
+  build: ArgosAPISchema.components["schemas"]["Build"];
+  screenshots: Screenshot[];
+}>;
+//#endregion
+//#region src/skip.d.ts
+type SkipParameters = Pick<UploadParameters, "apiBaseUrl" | "commit" | "branch" | "token" | "prNumber" | "buildName" | "metadata">;
+/**
+ * Mark a build as skipped.
+ */
+declare function skip(params: SkipParameters): Promise<{
+  build: ArgosAPISchema.components["schemas"]["Build"];
+}>;
+//#endregion
+export { Config, FinalizeParameters, UploadParameters, finalize, getConfigFromOptions, readConfig, skip, upload };