@bugbug-io/sdk 13.39.1

package/dist/index.js

@@ -0,0 +1,3844 @@
+// src/modules/auth/auth.ts
+var AuthModule = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  getAuth = async (params, options = {}) => {
+    const response = await this.#client.getAppRoot("/auth/authorize-url", {
+      ...options,
+      authenticated: false,
+      acceptRedirect: true,
+      redirect: "manual",
+      queryParams: {
+        client_id: params.clientId,
+        redirect_uri: params.redirectUri,
+        code_challenge: params.codeChallenge,
+        code_challenge_method: params.codeChallengeMethod,
+        state: params.state
+      }
+    });
+    const authorizeUrl = response instanceof Response ? response.headers.get("location") : void 0;
+    if (!authorizeUrl) {
+      throw new Error("BugBug OAuth authorize response did not include a redirect URL.");
+    }
+    return { authorizeUrl: new URL(authorizeUrl, response.url).toString() };
+  };
+  exchangeCode = async (payload, options = {}) => this.#client.postAppRoot("/auth/oauth/token/", {
+    ...options,
+    authenticated: false,
+    body: {
+      grant_type: payload.grantType,
+      client_id: payload.clientId,
+      redirect_uri: payload.redirectUri,
+      code: payload.code,
+      code_verifier: payload.codeVerifier
+    }
+  });
+  identity = async (options = {}) => this.#client.getAppRoot("/auth/identity", options);
+};
+
+// src/modules/components/components.ts
+var ComponentsModule = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  /**
+   * List all components with optional filtering and pagination
+   *
+   * @param options - Query options including search query, page, and page size
+   * @returns Paginated list of components with nested structure
+   *
+   * @example
+   * ```typescript
+   * // List all components
+   * const components = await sdk.components.list();
+   *
+   * // Search for specific components
+   * const loginComponents = await sdk.components.list({
+   *   query: 'login',
+   *   cursor: nextToken,
+   *   pageSize: 50
+   * });
+   * ```
+   */
+  list = async (options = {}) => {
+    const { query: searchQuery, cursor, pageSize, ordering, ...requestOptions } = options;
+    return this.#client.get("/components/", {
+      queryParams: {
+        query: searchQuery,
+        cursor,
+        page_size: pageSize,
+        ordering
+      },
+      ...requestOptions
+    });
+  };
+  /**
+   * Fetch component usage — how many tests reference this component and which.
+   *
+   * @param componentId - UUID of the component.
+   * @returns `{ usage, testsIds }` from `GET /components/{id}/usage/`.
+   */
+  getUsage = async (componentId, options = {}) => this.#client.get("/components/{id}/usage/", {
+    pathParams: { id: componentId },
+    ...options
+  });
+};
+
+// ../core/dist/utils/time.js
+var hoursAgo = (hours) => new Date(Date.now() - hours * 60 * 60 * 1e3).toISOString();
+var now = () => (/* @__PURE__ */ new Date()).toISOString();
+
+// src/modules/config/config.ts
+var ConfigModule = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  /**
+   * Fetch the BugBug infrastructure IP ranges that should be allowlisted for
+   * outbound runner traffic.
+   */
+  getIpAddresses = async (options = {}) => this.#client.get("/config/ips/", options);
+  /**
+   * Liveness probe + token check.
+   *
+   * `GET /config/status/` is unauthenticated. If the SDK's `apiToken` is sent,
+   * the server validates it and reports the result via `authenticated`; an
+   * invalid token still returns 200, so this method only throws on
+   * transport-level failures.
+   */
+  getStatus = async (options = {}) => this.#client.get("/config/status/", options);
+  /**
+   * Probe API connectivity and authentication by making one lightweight call.
+   *
+   * Never throws — transport failures are returned as `connected: false` with
+   * the error message. When the call succeeds, `authenticated` reflects whether
+   * the configured API token is currently valid.
+   *
+   * @returns A `ConnectivityStatus` snapshot with response time and message.
+   */
+  testConnectivity = async (options = {}) => {
+    const startTime = Date.now();
+    try {
+      const { authenticated } = await this.getStatus(options);
+      return {
+        connected: true,
+        responseTime: Date.now() - startTime,
+        timestamp: now(),
+        message: "API connectivity successful",
+        authenticated
+      };
+    } catch (error) {
+      return {
+        connected: false,
+        responseTime: Date.now() - startTime,
+        timestamp: now(),
+        error: error instanceof Error ? error.message : "Unknown error",
+        message: "API connectivity failed"
+      };
+    }
+  };
+  /**
+   * Single-shot system summary: IP ranges + connectivity probe.
+   *
+   * Internally issues one IP-fetch and reuses it as the connectivity probe to
+   * avoid duplicate requests.
+   *
+   * @returns A {@link SdkSystemInfo} snapshot with `{ ipAddresses, connectivity, timestamp }`.
+   */
+  getSystemInfo = async (options = {}) => {
+    const startTime = Date.now();
+    let ipAddresses = null;
+    let connectivity;
+    try {
+      ipAddresses = await this.getIpAddresses(options);
+      connectivity = {
+        connected: true,
+        responseTime: Date.now() - startTime,
+        timestamp: now(),
+        message: "API connectivity successful"
+      };
+    } catch (error) {
+      connectivity = {
+        connected: false,
+        responseTime: Date.now() - startTime,
+        timestamp: now(),
+        error: error instanceof Error ? error.message : "Unknown error",
+        message: "API connectivity failed"
+      };
+    }
+    return {
+      ipAddresses,
+      connectivity,
+      timestamp: now()
+    };
+  };
+};
+
+// src/utils/pagination.ts
+var DEFAULT_PAGE_SIZE = 100;
+var getAllPages = async (listPage, options = {}) => {
+  const items = [];
+  const baseOptions = options;
+  let { cursor } = baseOptions;
+  do {
+    const response = await listPage({
+      ...baseOptions,
+      cursor,
+      pageSize: baseOptions.pageSize ?? DEFAULT_PAGE_SIZE
+    });
+    items.push(...response.results ?? []);
+    cursor = response.nextToken ?? void 0;
+  } while (cursor);
+  return items;
+};
+
+// src/modules/groups/groups.ts
+var GroupsModule = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  /**
+   * List groups with pagination, search, and ordering.
+   *
+   * @param options.query - Search query matched against group name.
+   * @param options.ordering - Sort key; prefix with `-` for descending.
+   * @returns Paginated `GroupsListResponse`.
+   */
+  list = async (options = {}) => {
+    const { query: searchQuery, cursor, pageSize, ordering, ...requestOptions } = options;
+    return this.#client.get("/groups/", {
+      queryParams: {
+        query: searchQuery,
+        cursor,
+        page_size: pageSize,
+        ordering
+      },
+      ...requestOptions
+    });
+  };
+  /**
+   * Fetch every group across all pages.
+   */
+  getAll = async (options = {}) => getAllPages((pageOptions) => this.list({ ...options, ...pageOptions }));
+  /**
+   * Fetch a single group by ID (with nested steps).
+   *
+   * @throws {NotFoundError} When no group matches `groupId`.
+   */
+  get = async (groupId, options = {}) => this.#client.get("/groups/{id}/", {
+    pathParams: { id: groupId },
+    ...options
+  });
+  /**
+   * Create a new (empty) group.
+   *
+   * @throws {ValidationError} On invalid payload.
+   */
+  create = async (data, options = {}) => this.#client.post("/groups/", {
+    body: data,
+    ...options
+  });
+  /**
+   * Fully replace a group via PUT. Use {@link partialUpdate} for PATCH semantics.
+   *
+   * @throws {NotFoundError} When the group does not exist.
+   * @throws {ValidationError} On invalid payload.
+   */
+  update = async (groupId, data, options = {}) => this.#client.put("/groups/{id}/", {
+    pathParams: { id: groupId },
+    body: data,
+    ...options
+  });
+  /**
+   * Patch selected fields on a group (PATCH semantics).
+   *
+   * @throws {NotFoundError} When the group does not exist.
+   * @throws {ValidationError} On invalid payload.
+   */
+  partialUpdate = async (groupId, data, options = {}) => this.#client.patch("/groups/{id}/", {
+    pathParams: { id: groupId },
+    body: data,
+    ...options
+  });
+  /**
+   * Delete a group by ID. Tests that reference this group will lose those steps.
+   *
+   * @throws {NotFoundError} When the group does not exist.
+   */
+  delete = async (groupId, options = {}) => this.#client.delete("/groups/{id}/", {
+    pathParams: { id: groupId },
+    ...options
+  });
+};
+
+// ../core/dist/utils/validation.js
+var UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var isUuid = (value) => UUID_REGEX.test(value);
+
+// src/constants/sdk-error-codes.ts
+var SDK_ERROR_CODES = {
+  AUTHENTICATION_ERROR: "AUTHENTICATION_ERROR",
+  AUTHORIZATION_ERROR: "AUTHORIZATION_ERROR",
+  VALIDATION_ERROR: "VALIDATION_ERROR",
+  CONFIGURATION_ERROR: "CONFIGURATION_ERROR",
+  MISSING_PROJECT_ID_ERROR: "MISSING_PROJECT_ID_ERROR",
+  NOT_FOUND_ERROR: "NOT_FOUND_ERROR",
+  RATE_LIMIT_ERROR: "RATE_LIMIT_ERROR",
+  TIMEOUT_ERROR: "TIMEOUT_ERROR",
+  NETWORK_ERROR: "NETWORK_ERROR",
+  CANCELLATION_ERROR: "CANCELLATION_ERROR",
+  INTERNAL_SERVER_ERROR: "INTERNAL_SERVER_ERROR",
+  SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE",
+  UNEXPECTED_RESPONSE: "UNEXPECTED_RESPONSE",
+  HTTP_ERROR: "HTTP_ERROR"
+};
+var STATUS_NO_RESPONSE = 0;
+var STATUS_CLIENT_TIMEOUT = 408;
+var STATUS_CLIENT_CANCELLED = 499;
+
+// src/types/errors.ts
+var HTTP_STATUS_INTERNAL_SERVER_ERROR = 500;
+var HTTP_STATUS_SERVICE_UNAVAILABLE = 503;
+var BugBugError = class _BugBugError extends Error {
+  code;
+  statusCode;
+  response;
+  request;
+  cause;
+  constructor(code, message, statusCode, response, cause, request) {
+    super(message);
+    this.name = "BugBugError";
+    this.code = code;
+    this.statusCode = statusCode;
+    this.response = response;
+    this.request = request ?? (response ? { url: response.url } : void 0);
+    this.cause = cause;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _BugBugError);
+    }
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+      request: this.request,
+      stack: this.stack
+    };
+  }
+};
+var AuthenticationError = class extends BugBugError {
+  constructor(message = "Authentication failed", response, request) {
+    super(
+      SDK_ERROR_CODES.AUTHENTICATION_ERROR,
+      message,
+      response?.status ?? 401,
+      response,
+      void 0,
+      request
+    );
+    this.name = "AuthenticationError";
+  }
+};
+var AuthorizationError = class extends BugBugError {
+  constructor(message = "Access denied", response, request) {
+    super(
+      SDK_ERROR_CODES.AUTHORIZATION_ERROR,
+      message,
+      response?.status ?? 403,
+      response,
+      void 0,
+      request
+    );
+    this.name = "AuthorizationError";
+  }
+};
+var ValidationError = class extends BugBugError {
+  fields;
+  constructor(message, response, fields, request) {
+    super(
+      SDK_ERROR_CODES.VALIDATION_ERROR,
+      message,
+      response?.status ?? 400,
+      response,
+      void 0,
+      request
+    );
+    this.name = "ValidationError";
+    this.fields = fields;
+  }
+};
+var ConfigurationError = class extends BugBugError {
+  constructor(message) {
+    super(SDK_ERROR_CODES.CONFIGURATION_ERROR, message, STATUS_NO_RESPONSE);
+    this.name = "ConfigurationError";
+  }
+};
+var MissingProjectIdError = class extends BugBugError {
+  constructor(message = "No project selected. Provide a project id (--project-id) or switch project.", response, request) {
+    super(
+      SDK_ERROR_CODES.MISSING_PROJECT_ID_ERROR,
+      message,
+      response?.status ?? 400,
+      response,
+      void 0,
+      request
+    );
+    this.name = "MissingProjectIdError";
+  }
+};
+var NotFoundError = class extends BugBugError {
+  constructor(message = "Resource not found", response, request) {
+    super(
+      SDK_ERROR_CODES.NOT_FOUND_ERROR,
+      message,
+      response?.status ?? 404,
+      response,
+      void 0,
+      request
+    );
+    this.name = "NotFoundError";
+  }
+};
+var RateLimitError = class extends BugBugError {
+  retryAfter;
+  constructor(retryAfter, message = "Rate limit exceeded", response, request) {
+    super(
+      SDK_ERROR_CODES.RATE_LIMIT_ERROR,
+      message,
+      response?.status ?? 429,
+      response,
+      void 0,
+      request
+    );
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var TimeoutError = class extends BugBugError {
+  timeout;
+  constructor(timeout, message, request) {
+    const defaultMessage = `Request timed out after ${timeout}ms`;
+    super(
+      SDK_ERROR_CODES.TIMEOUT_ERROR,
+      message || defaultMessage,
+      STATUS_CLIENT_TIMEOUT,
+      void 0,
+      void 0,
+      request
+    );
+    this.name = "TimeoutError";
+    this.timeout = timeout;
+  }
+};
+var NetworkError = class extends BugBugError {
+  constructor(message, cause, request) {
+    super(SDK_ERROR_CODES.NETWORK_ERROR, message, STATUS_NO_RESPONSE, void 0, cause, request);
+    this.name = "NetworkError";
+  }
+};
+var CancellationError = class extends BugBugError {
+  constructor(message = "Request was cancelled", request) {
+    super(
+      SDK_ERROR_CODES.CANCELLATION_ERROR,
+      message,
+      STATUS_CLIENT_CANCELLED,
+      void 0,
+      void 0,
+      request
+    );
+    this.name = "CancellationError";
+  }
+};
+var InternalServerError = class extends BugBugError {
+  constructor(message = "Internal server error", response, request) {
+    super(
+      SDK_ERROR_CODES.INTERNAL_SERVER_ERROR,
+      message,
+      response?.status ?? HTTP_STATUS_INTERNAL_SERVER_ERROR,
+      response,
+      void 0,
+      request
+    );
+    this.name = "InternalServerError";
+  }
+};
+var ServiceUnavailableError = class extends BugBugError {
+  constructor(message = "Service temporarily unavailable", response, request) {
+    super(
+      SDK_ERROR_CODES.SERVICE_UNAVAILABLE,
+      message,
+      response?.status ?? HTTP_STATUS_SERVICE_UNAVAILABLE,
+      response,
+      void 0,
+      request
+    );
+    this.name = "ServiceUnavailableError";
+  }
+};
+var UnexpectedResponseError = class extends BugBugError {
+  constructor(message, cause, request) {
+    super(
+      SDK_ERROR_CODES.UNEXPECTED_RESPONSE,
+      message,
+      STATUS_NO_RESPONSE,
+      void 0,
+      cause,
+      request
+    );
+    this.name = "UnexpectedResponseError";
+  }
+};
+var HttpError = class extends BugBugError {
+  constructor(message, statusCode, response, request) {
+    super(SDK_ERROR_CODES.HTTP_ERROR, message, statusCode, response, void 0, request);
+    this.name = "HttpError";
+  }
+};
+function isBugBugError(error) {
+  return error instanceof BugBugError;
+}
+function isAuthenticationError(error) {
+  return error instanceof AuthenticationError;
+}
+function isAuthorizationError(error) {
+  return error instanceof AuthorizationError;
+}
+function isValidationError(error) {
+  return error instanceof ValidationError;
+}
+function isConfigurationError(error) {
+  return error instanceof ConfigurationError;
+}
+function isMissingProjectIdError(error) {
+  return error instanceof MissingProjectIdError;
+}
+function isNotFoundError(error) {
+  return error instanceof NotFoundError;
+}
+function isRateLimitError(error) {
+  return error instanceof RateLimitError;
+}
+function isTimeoutError(error) {
+  return error instanceof TimeoutError;
+}
+function isNetworkError(error) {
+  return error instanceof NetworkError;
+}
+function isCancellationError(error) {
+  return error instanceof CancellationError;
+}
+function isInternalServerError(error) {
+  return error instanceof InternalServerError;
+}
+function isServiceUnavailableError(error) {
+  return error instanceof ServiceUnavailableError;
+}
+function isUnexpectedResponseError(error) {
+  return error instanceof UnexpectedResponseError;
+}
+function isHttpError(error) {
+  return error instanceof HttpError;
+}
+
+// src/modules/profiles/profiles.ts
+var ProfilesModule = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  /**
+   * List run profiles, one page at a time.
+   *
+   * @param options.cursor - Opaque cursor returned as `nextToken` by the previous page.
+   * @param options.pageSize - Items per page.
+   * @returns Paginated `ProfilesListResponse` (validated via Zod).
+   * @throws {UnexpectedResponseError} On Zod validation failure.
+   */
+  list = async (options = {}) => {
+    const { cursor, pageSize, ...requestOptions } = options;
+    return this.#client.get("/profiles/", {
+      queryParams: {
+        cursor,
+        page_size: pageSize
+      },
+      ...requestOptions
+    });
+  };
+  /**
+   * Fetch a single profile by ID.
+   *
+   * @throws {NotFoundError} When no profile matches `profileId`.
+   */
+  get = async (profileId, options = {}) => this.#client.get("/profiles/{id}/", {
+    pathParams: { id: profileId },
+    ...options
+  });
+  /**
+   * Find a profile by name across all pages.
+   *
+   * @returns The matching profile, or `null` when no profile has that name.
+   */
+  findByName = async (profileName, options = {}) => {
+    const profiles = await this.getAll(options);
+    return profiles.find((profile) => profile.name === profileName) || null;
+  };
+  /**
+   * Fetch every profile across all pages.
+   *
+   * Internally follows `nextToken` until the API signals exhaustion.
+   * For large tenants this can issue multiple sequential requests; cache the
+   * result where possible.
+   */
+  getAll = async (options = {}) => getAllPages((pageOptions) => this.list({ ...options, ...pageOptions }));
+  /**
+   * Return the profile flagged `isDefault`, falling back to the first profile.
+   *
+   * @returns The default `Profile`, or `null` when the tenant has no profiles.
+   */
+  getDefault = async (options = {}) => {
+    const profiles = await this.getAll(options);
+    return profiles.find((profile) => profile.isDefault) || profiles[0] || null;
+  };
+  /**
+   * Resolve a profile name **or** UUID to a profile UUID suitable for the
+   * `runProfileId` field on a run request.
+   *
+   * - UUID input → returned unchanged with **no** API call.
+   * - Name input → looked up via {@link findByName}.
+   *
+   * @param profileNameOrId - Human-readable profile name (e.g. `"Production"`) or UUID.
+   * @returns The matching profile UUID.
+   * @throws {NotFoundError} When `profileNameOrId` is not a UUID and no profile has that name.
+   *
+   * @example
+   * ```typescript
+   * const profileId = await sdk.profiles.resolveId('Production');
+   * await sdk.tests.startRun(testId, { profileName: profileId });
+   * ```
+   */
+  resolveId = async (profileNameOrId, options = {}) => {
+    if (isUuid(profileNameOrId)) {
+      return profileNameOrId;
+    }
+    const profile = await this.findByName(profileNameOrId, options);
+    if (!profile) {
+      throw new NotFoundError(`Profile '${profileNameOrId}' not found`);
+    }
+    return profile.id;
+  };
+};
+
+// src/modules/project/project.ts
+var ProjectModule = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  /**
+   * Fetch project settings (e.g. retention, integrations).
+   *
+   * @returns The `ProjectSettings` object for the project.
+   */
+  getSettings = async (options = {}) => this.#client.get("/settings/", options);
+  /**
+   * Export the entire project as a ZIP archive (tests, suites, components,
+   * profiles, settings).
+   *
+   * @returns Raw ZIP bytes ready to be written to disk or uploaded elsewhere.
+   *
+   * @example
+   * ```typescript
+   * import { writeFile } from 'node:fs/promises';
+   * const zipBytes = await sdk.project.export();
+   * await writeFile('project.zip', zipBytes);
+   * ```
+   */
+  export = async (options = {}) => this.#client.getBinary("/project/export/", options);
+  /**
+   * Import a project from a ZIP archive.
+   *
+   * Performs the two-step server flow:
+   * 1. **Validate** the upload — surfaces server-side errors (malformed ZIP,
+   *    naming conflicts, …) as {@link ValidationError}.
+   * 2. **Run** the import asynchronously using the validated upload id.
+   *
+   * @param zipBytes - Raw ZIP archive bytes.
+   * @returns The response from the import run endpoint (typically a 202 with
+   *   empty body — kept as `unknown` until the API stabilizes the shape).
+   * @throws {UnexpectedResponseError} When validation succeeds but the server
+   *   omits the `uploadId` needed to trigger the run step.
+   * @throws {ValidationError} When the ZIP is rejected by validate.
+   *
+   * @example
+   * ```typescript
+   * import { readFile } from 'node:fs/promises';
+   * const bytes = await readFile('project.zip');
+   * await sdk.project.import(bytes);
+   * ```
+   */
+  import = async (zipBytes, options = {}) => {
+    const validation = await this.#validateImport(zipBytes, options);
+    const uploadId = typeof validation.uploadId === "string" ? validation.uploadId : void 0;
+    if (!uploadId) {
+      throw new UnexpectedResponseError(
+        "Import validation succeeded but did not return an uploadId."
+      );
+    }
+    return this.#client.post("/project/import/run/", {
+      ...options,
+      body: { uploadId }
+    });
+  };
+  #validateImport = async (zipBytes, options) => {
+    const form = new FormData();
+    form.append(
+      "file",
+      new Blob([zipBytes], { type: "application/zip" }),
+      "project.zip"
+    );
+    return this.#client.postForm(
+      "/project/import/validate/",
+      form,
+      options
+    );
+  };
+};
+
+// src/modules/projectArtifacts/projectArtifacts.ts
+var ProjectArtifactsModule = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  upload = async ({
+    projectId,
+    file,
+    fileName,
+    contentType = "application/octet-stream",
+    stepId,
+    ...options
+  }) => {
+    const form = new FormData();
+    const blob = file instanceof Blob ? file : new Blob([file], { type: contentType });
+    form.append("file", blob, fileName);
+    if (stepId) {
+      form.append("stepId", stepId);
+    }
+    return this.#client.postForm("/projects/{projectId}/artifacts/", form, {
+      ...options,
+      pathParams: { projectId },
+      useAppRoot: true
+    });
+  };
+};
+
+// src/modules/projects/projects.ts
+var ProjectsModule = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  /**
+   * List projects accessible with the current token, one page at a time.
+   *
+   * @param options.cursor - Opaque cursor returned as `nextToken` by the previous page.
+   * @param options.pageSize - Items per page.
+   * @param options.query - Case-insensitive name filter.
+   * @returns Paginated `ProjectsListResponse`.
+   */
+  list = async (options = {}) => {
+    const { cursor, pageSize, query, ...requestOptions } = options;
+    return this.#client.get("/projects/", {
+      ...requestOptions,
+      queryParams: {
+        cursor,
+        page_size: pageSize,
+        query
+      },
+      projectScoped: false
+    });
+  };
+  /**
+   * Fetch every project across all pages.
+   *
+   * Internally follows `nextToken` until the API signals exhaustion.
+   */
+  getAll = async (options = {}) => getAllPages((pageOptions) => this.list({ ...options, ...pageOptions }));
+  /**
+   * Find a project by its id across all pages.
+   *
+   * @returns The matching project, or `null` when no project has that id.
+   */
+  findById = async (projectId, options = {}) => {
+    const projects = await this.getAll(options);
+    return projects.find((project) => project.id === projectId) ?? null;
+  };
+};
+
+// src/modules/stepRuns/stepRuns.ts
+var StepRunsModule = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  /**
+   * Fetch full details for a single step run.
+   *
+   * @param stepRunId - UUID of the step run (from a `TestRun.stepsRuns` entry).
+   * @returns The step-run record including error code and timing.
+   * @throws {NotFoundError} When no step run matches `stepRunId`.
+   */
+  get = async (stepRunId, options = {}) => this.#client.get("/stepruns/{id}/", {
+    pathParams: { id: stepRunId },
+    ...options
+  });
+};
+
+// src/modules/steps/steps.ts
+var StepsModule = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  /**
+   * Fetch full details of a single step.
+   *
+   * @throws {NotFoundError} When no step matches `stepId`.
+   */
+  get = async (stepId, options = {}) => this.#client.get("/steps/{id}/", {
+    pathParams: { id: stepId },
+    ...options
+  });
+  /**
+   * Create a new step inside an existing group.
+   *
+   * @param data - Step payload; `type` discriminates the validation schema.
+   * @throws {ValidationError} On invalid payload (DRF field errors on `error.fields`).
+   */
+  create = async (data, options = {}) => this.#client.post("/steps/", {
+    body: data,
+    ...options
+  });
+  /**
+   * Fully replace a step via PUT. Use {@link partialUpdate} for PATCH semantics.
+   *
+   * @throws {NotFoundError} When the step does not exist.
+   * @throws {ValidationError} On invalid payload.
+   */
+  update = async (stepId, data, options = {}) => this.#client.put("/steps/{id}/", {
+    pathParams: { id: stepId },
+    body: data,
+    ...options
+  });
+  /**
+   * Patch selected fields on a step (PATCH semantics).
+   *
+   * @throws {NotFoundError} When the step does not exist.
+   * @throws {ValidationError} On invalid payload.
+   */
+  partialUpdate = async (stepId, data, options = {}) => this.#client.patch("/steps/{id}/", {
+    pathParams: { id: stepId },
+    body: data,
+    ...options
+  });
+  /**
+   * Delete a step by ID.
+   *
+   * @throws {NotFoundError} When the step does not exist.
+   */
+  delete = async (stepId, options = {}) => this.#client.delete("/steps/{id}/", {
+    pathParams: { id: stepId },
+    ...options
+  });
+};
+
+// src/types/sdk.ts
+var isRunningStatus = (status) => ["initialized", "queued", "running", "auto_retrying"].includes(status ?? "");
+var isEditingStatus = (status) => ["recording", "paused"].includes(status ?? "");
+var isFailedStatus = (status) => ["failed", "error"].includes(status ?? "");
+var isPassedStatus = (status) => ["passed"].includes(status ?? "");
+var isCompletedStatus = (status) => ["passed", "failed", "error", "stopped"].includes(status ?? "");
+
+// ../core/dist/utils/async.js
+var sleep = (ms) => new Promise((resolve4) => {
+  setTimeout(resolve4, ms);
+});
+
+// src/utils/polling.ts
+var pollRunUntilComplete = async (getRun, isComplete, options) => {
+  const { pollInterval = 2e3, timeout = options.defaultTimeout, onProgress } = options;
+  const endTime = Date.now() + timeout;
+  const sleepWithinTimeout = async () => {
+    const remainingMs = endTime - Date.now();
+    if (remainingMs <= 0) throw new TimeoutError(timeout, options.timeoutMessage(timeout));
+    await sleep(Math.min(pollInterval, remainingMs));
+  };
+  while (Date.now() < endTime) {
+    try {
+      const run = await getRun();
+      await onProgress?.(run);
+      if (isComplete(run)) {
+        return run;
+      }
+      await sleepWithinTimeout();
+    } catch (error) {
+      if (!isNetworkError(error)) {
+        throw error;
+      }
+      await sleepWithinTimeout();
+    }
+  }
+  throw new TimeoutError(timeout, options.timeoutMessage(timeout));
+};
+
+// src/modules/suites/suites.ts
+var SuitesModule = class {
+  #client;
+  #profiles;
+  constructor(client) {
+    this.#client = client;
+    this.#profiles = new ProfilesModule(client);
+  }
+  /**
+   * List suites with pagination, search, and ordering.
+   *
+   * @param options.cursor - Opaque cursor returned as `nextToken` by the previous page.
+   * @param options.pageSize - Items per page.
+   * @param options.query - Search query matched against suite name.
+   * @param options.ordering - Sort key; prefix with `-` for descending.
+   * @returns Paginated `SuitesListResponse` envelope (validated via Zod).
+   * @throws {UnexpectedResponseError} On Zod validation failure.
+   */
+  list = async (options = {}) => {
+    const { cursor, pageSize, query: searchQuery, ordering, ...requestOptions } = options;
+    return this.#client.get("/suites/", {
+      queryParams: {
+        cursor,
+        page_size: pageSize,
+        query: searchQuery,
+        ordering
+      },
+      ...requestOptions
+    });
+  };
+  /**
+   * Fetch every suite across all pages.
+   */
+  getAll = async (options = {}) => getAllPages((pageOptions) => this.list(pageOptions), options);
+  /**
+   * Fetch a single suite by ID.
+   *
+   * @throws {NotFoundError} When no suite matches `suiteId`.
+   */
+  get = async (suiteId, options = {}) => this.#client.get("/suites/{id}/", {
+    pathParams: { id: suiteId },
+    ...options
+  });
+  /**
+   * Create a new suite.
+   *
+   * @throws {ValidationError} On invalid payload.
+   */
+  create = async (data, options = {}) => this.#client.post("/suites/", {
+    body: data,
+    ...options
+  });
+  /**
+   * Fully replace a suite via PUT (all fields required).
+   * Use {@link partialUpdate} for sparse PATCH semantics.
+   *
+   * @throws {NotFoundError} When the suite does not exist.
+   * @throws {ValidationError} On invalid payload.
+   */
+  update = async (suiteId, data, options = {}) => this.#client.put("/suites/{id}/", {
+    pathParams: { id: suiteId },
+    body: data,
+    ...options
+  });
+  /**
+   * Patch selected fields on a suite (PATCH semantics).
+   *
+   * @throws {NotFoundError} When the suite does not exist.
+   * @throws {ValidationError} On invalid payload.
+   */
+  partialUpdate = async (suiteId, data, options = {}) => this.#client.patch("/suites/{id}/", {
+    pathParams: { id: suiteId },
+    body: data,
+    ...options
+  });
+  /**
+   * Delete a suite by ID.
+   *
+   * @throws {NotFoundError} When the suite does not exist.
+   */
+  delete = async (suiteId, options = {}) => this.#client.delete("/suites/{id}/", {
+    pathParams: { id: suiteId },
+    ...options
+  });
+  async startRun(suiteId, options = {}) {
+    const {
+      watchProgress,
+      pollInterval,
+      timeout,
+      onProgress,
+      profileName,
+      variables,
+      ...runOptions
+    } = options;
+    const runProfileId = profileName ? await this.#profiles.resolveId(profileName, runOptions) : void 0;
+    const runResult = await this.#client.post("/suiteruns/", {
+      body: {
+        suiteId,
+        runProfileId,
+        variables: variables ?? [],
+        triggeredBy: this.#client.getConfig().triggeredBy
+      },
+      ...runOptions
+    });
+    if (watchProgress) {
+      return this.watchRunProgress(runResult.id, onProgress ?? (() => {
+      }), {
+        pollInterval,
+        timeout
+      });
+    }
+    return runResult;
+  }
+  /**
+   * Fetch full suite-run details including child test runs.
+   *
+   * @throws {NotFoundError} When the run does not exist.
+   */
+  getRun = async (runId, options = {}) => this.#client.get("/suiteruns/{id}/", {
+    pathParams: { id: runId },
+    ...options
+  });
+  /**
+   * Get list of suite runs.
+   *
+   */
+  listRuns = async (options = {}) => {
+    const {
+      cursor,
+      pageSize,
+      ordering,
+      startedAfter,
+      startedBefore,
+      status,
+      suiteId,
+      ...requestOptions
+    } = options;
+    return this.#client.get("/suiteruns/", {
+      queryParams: {
+        cursor,
+        page_size: pageSize,
+        ordering,
+        started_after: startedAfter,
+        started_before: startedBefore,
+        status,
+        suiteId
+      },
+      ...requestOptions
+    });
+  };
+  /**
+   * Get recent suite runs within a time window
+   */
+  getRecentRuns = async (options = {}) => {
+    const {
+      hours = 24,
+      pageSize = 50,
+      ordering = "-started",
+      suiteId,
+      ...requestOptions
+    } = options;
+    const startedAfter = hoursAgo(hours);
+    return this.listRuns({
+      pageSize,
+      ordering,
+      startedAfter,
+      suiteId,
+      ...requestOptions
+    });
+  };
+  /**
+   * Fetch only the lightweight status of a suite run. Prefer this over
+   * {@link getRun} when polling.
+   */
+  getRunProgress = async (runId, options = {}) => this.#client.get("/suiteruns/{id}/status/", {
+    pathParams: { id: runId },
+    ...options
+  });
+  /**
+   * Request cancellation of an in-progress suite run.
+   *
+   * @returns The updated status; the run may still take a moment to settle.
+   */
+  stopRun = async (runId, options = {}) => this.#client.post("/suiteruns/{id}/stop/", {
+    pathParams: { id: runId },
+    ...options
+  });
+  /**
+   * Fetch screenshots captured across all child test runs of a suite run.
+   */
+  getRunScreenshots = async (runId, options = {}) => {
+    const screenshots = await this.#client.get(
+      "/suiteruns/{id}/screenshots/",
+      {
+        pathParams: { id: runId },
+        ...options
+      }
+    );
+    return screenshots.testsRuns;
+  };
+  /**
+   * Download the combined JUnit XML report for a suite run, aggregating all
+   * child test runs.
+   *
+   * @returns The JUnit report body as a string.
+   */
+  downloadRunJunitReport = async (runId, options = {}) => this.#client.getText("/suiteruns/{id}/report/junit/", {
+    pathParams: { id: runId },
+    ...options
+  });
+  /**
+   * List artifacts attached to a suite run. The current public API exposes the
+   * combined JUnit report artifact here.
+   */
+  listRunDebugArtifacts = async (runId, options = {}) => {
+    const { signal, timeout, headers } = options;
+    return this.#client.get("/suiteruns/{id}/debug-artifacts/", {
+      pathParams: { id: runId },
+      signal,
+      timeout,
+      headers
+    });
+  };
+  /**
+   * Poll a suite run's lightweight `/status/` endpoint until it reaches a
+   * terminal status, then return the full `SuiteRun` once.
+   *
+   * Transient network errors are retried; non-network errors propagate.
+   *
+   * @param runId - UUID of the suite run.
+   * @param onProgress - Invoked on every successful poll with the latest `SuiteRunState`
+   *   (including the terminal one). Receives `finishedTests`/`totalTests`/`webappUrl`
+   *   for in-flight progress UI.
+   * @param options.pollInterval - Poll interval in ms (default 2000).
+   * @param options.timeout - Wait timeout in ms (default 600_000 = 10 minutes; suites typically take longer than single tests).
+   * @throws {TimeoutError} When the run does not complete in time.
+   */
+  watchRunProgress = async (runId, onProgress, options = {}) => {
+    const { pollInterval, timeout, ...requestOptions } = options;
+    await pollRunUntilComplete(
+      () => this.getRunProgress(runId, requestOptions),
+      (status) => isCompletedStatus(status.status),
+      {
+        pollInterval,
+        timeout,
+        onProgress,
+        defaultTimeout: 6e5,
+        // 10 minutes (suites typically take longer)
+        timeoutMessage: (t) => `Suite run ${runId} did not complete within ${t}ms`
+      }
+    );
+    return this.getRun(runId, requestOptions);
+  };
+};
+
+// src/modules/tests/tests.utils.ts
+function buildTestImportFormData(payload, fmt) {
+  const form = new FormData();
+  const filename = fmt === "yaml" ? "test.yaml" : "test.zip";
+  const mime = fmt === "yaml" ? "application/x-yaml" : "application/zip";
+  const blob = typeof payload === "string" ? new Blob([payload], { type: mime }) : new Blob([payload], { type: mime });
+  form.append("file", blob, filename);
+  return form;
+}
+
+// src/modules/tests/tests.ts
+var TestsModule = class {
+  #client;
+  #profiles;
+  constructor(client) {
+    this.#client = client;
+    this.#profiles = new ProfilesModule(client);
+  }
+  /**
+   * List tests with pagination, search, and ordering.
+   *
+   * @param options.cursor - Opaque cursor returned as `nextToken` by the previous page.
+   * @param options.pageSize - Number of items per page.
+   * @param options.query - Search query matched against test name.
+   * @param options.ordering - Sort key; prefix with `-` for descending.
+   * @returns Paginated `TestsListResponse` envelope (validated via Zod).
+   * @throws {UnexpectedResponseError} When the server response fails Zod validation.
+   */
+  list = async (options = {}) => {
+    const { cursor, pageSize, query: searchQuery, ordering, ...requestOptions } = options;
+    return this.#client.get("/tests/", {
+      queryParams: {
+        cursor,
+        page_size: pageSize,
+        query: searchQuery,
+        ordering
+      },
+      ...requestOptions
+    });
+  };
+  /**
+   * Fetch every test across all pages.
+   */
+  getAll = async (options = {}) => getAllPages((pageOptions) => this.list(pageOptions), options);
+  /**
+   * Fetch a single test by ID.
+   *
+   * @param testId - UUID of the test.
+   * @returns The full `Test` resource.
+   * @throws {NotFoundError} When no test matches `testId`.
+   */
+  get = async (testId, options = {}) => this.#client.get("/tests/{id}/", {
+    pathParams: { id: testId },
+    ...options
+  });
+  /**
+   * Create a new empty test.
+   *
+   * @param data - Test creation payload (at minimum, `name` and `screenSizeType`).
+   * @returns The newly-created `Test`.
+   * @throws {ValidationError} On invalid payload (DRF field errors on `error.fields`).
+   */
+  create = async (data, options = {}) => this.#client.post("/tests/", {
+    body: data,
+    ...options
+  });
+  /**
+   * Update a test. The tests endpoint accepts partial payloads via PATCH, so
+   * this and {@link partialUpdate} share the same semantics.
+   *
+   * @param testId - UUID of the test to update.
+   * @param data - Fields to patch.
+   * @throws {NotFoundError} When the test does not exist.
+   * @throws {ValidationError} When the payload fails server-side validation.
+   */
+  update = async (testId, data, options = {}) => this.#client.patch("/tests/{id}/", {
+    pathParams: { id: testId },
+    body: data,
+    ...options
+  });
+  /** Alias for {@link update}. The tests endpoint already uses PATCH semantics. */
+  partialUpdate = async (testId, data, options = {}) => this.update(testId, data, options);
+  /**
+   * Delete a test by ID.
+   *
+   * @throws {NotFoundError} When the test does not exist.
+   */
+  delete = async (testId, options = {}) => this.#client.delete("/tests/{id}/", {
+    pathParams: { id: testId },
+    ...options
+  });
+  /**
+   * Link an existing component/group into a test at an optional position.
+   *
+   * @param testId - UUID of the test to insert into.
+   * @param data - `{ groupId, atIndex? }` insertion descriptor.
+   * @returns Insert response with the resulting step layout.
+   */
+  linkComponent = async (testId, data, options = {}) => this.#client.post("/tests/{id}/insert-component/", {
+    pathParams: { id: testId },
+    body: data,
+    ...options
+  });
+  /**
+   * Unlink a component/group from a test.
+   *
+   * @param testId - UUID of the test to unlink from.
+   * @param data - Unlink descriptor identifying which component to remove.
+   */
+  unlinkComponent = async (testId, data, options = {}) => this.#client.post("/tests/{id}/unlink-component/", {
+    pathParams: { id: testId },
+    body: data,
+    ...options
+  });
+  /**
+   * Run a test by ID
+   */
+  #run = async (testId, options = {}) => {
+    const { profileName, variables, ...requestOptions } = options;
+    const runProfileId = profileName ? await this.#profiles.resolveId(profileName, requestOptions) : void 0;
+    return this.#client.post("/testruns/", {
+      body: {
+        testId,
+        runProfileId,
+        variables: variables ?? [],
+        triggeredBy: this.#client.getConfig().triggeredBy
+      },
+      ...requestOptions
+    });
+  };
+  /**
+   * Run a test by name (finds test by name first)
+   */
+  #runByName = async (testName, options = {}) => {
+    const test = await this.#findByName(testName, options);
+    if (!test) {
+      throw new NotFoundError(`Test '${testName}' not found`);
+    }
+    return this.#run(test.id, options);
+  };
+  #findByName = async (testName, options = {}) => {
+    let cursor;
+    const pageSize = 100;
+    while (true) {
+      const response = await this.list({ ...options, query: testName, cursor, pageSize });
+      const results = response.results ?? [];
+      const exactMatch = results.find((testSummary) => testSummary.name === testName);
+      if (exactMatch) return exactMatch;
+      cursor = response.nextToken ?? void 0;
+      if (!cursor) {
+        return null;
+      }
+    }
+  };
+  async startRun(testNameOrId, options = {}) {
+    const { watchProgress, pollInterval, timeout, onProgress, ...runOptions } = options;
+    const callRun = isUuid(testNameOrId) ? this.#run : this.#runByName;
+    const runResult = await callRun(testNameOrId, runOptions);
+    if (!watchProgress) return runResult;
+    return this.watchRunProgress(runResult.id, onProgress ?? (() => {
+    }), {
+      pollInterval,
+      timeout
+    });
+  }
+  /**
+   * Fetch full test-run details including step runs.
+   *
+   * @param runId - UUID of the test run.
+   * @throws {NotFoundError} When the run does not exist.
+   */
+  getRun = async (runId, options = {}) => this.#client.get("/testruns/{id}/", {
+    pathParams: { id: runId },
+    ...options
+  });
+  /**
+   * Fetch only the lightweight status of a test run (no step detail).
+   * Prefer this over {@link getRun} when polling.
+   */
+  getRunProgress = async (runId, options = {}) => this.#client.get("/testruns/{id}/status/", {
+    pathParams: { id: runId },
+    ...options
+  });
+  /**
+   * Request cancellation of an in-progress test run.
+   *
+   * @param runId - UUID of the run to stop.
+   * @returns The updated status; the run may still take a moment to settle.
+   */
+  stopRun = async (runId, options = {}) => this.#client.post("/testruns/{id}/stop/", {
+    pathParams: { id: runId },
+    ...options
+  });
+  /**
+   * Fetch step-level screenshots captured during a run.
+   *
+   * @returns Per-step-run screenshot entries; empty array when none available.
+   */
+  getRunScreenshots = async (runId, options = {}) => {
+    const screenshots = await this.#client.get(
+      "/testruns/{id}/screenshots/",
+      {
+        pathParams: { id: runId },
+        ...options
+      }
+    );
+    return screenshots.stepsRuns || [];
+  };
+  /**
+   * List test runs filtered by status, time window, and optional test ID.
+   *
+   * @param options.testId - When set, restricts to runs of that test (UUID).
+   * @param options.startedAfter - ISO timestamp; only runs started after this point.
+   * @param options.startedBefore - ISO timestamp; only runs started before this point.
+   * @param options.status - Filter by `TestRunState['status']`.
+   * @returns Paginated `TestRunsListResponse`.
+   */
+  listRuns = async (options = {}) => {
+    const {
+      cursor,
+      pageSize,
+      ordering,
+      startedAfter,
+      startedBefore,
+      status,
+      testId,
+      ...requestOptions
+    } = options;
+    return this.#client.get("/testruns/", {
+      queryParams: {
+        cursor,
+        page_size: pageSize,
+        ordering,
+        started_after: startedAfter,
+        started_before: startedBefore,
+        status,
+        testId
+      },
+      ...requestOptions
+    });
+  };
+  /**
+   * Move a step to a new position within a test's step list.
+   *
+   * @param testId - UUID of the test to reorder.
+   * @param data - `{ stepId, atIndex }` move descriptor.
+   * @returns The updated `Test` with the new step ordering.
+   */
+  updateStepPosition = async (testId, data, options = {}) => this.#client.postNoContent("/tests/{id}/update-step-position/", {
+    pathParams: { id: testId },
+    body: data,
+    ...options
+  });
+  /**
+   * Convenience wrapper around {@link listRuns} that returns runs started in
+   * the last N hours, newest first by default.
+   *
+   * @param options.hours - Look-back window in hours (default 24).
+   * @param options.pageSize - Max runs per page (default 50).
+   * @param options.ordering - Sort order; defaults to most-recent first.
+   */
+  getRecentRuns = async (options = {}) => {
+    const { hours = 24, pageSize = 50, ordering = "-started", ...requestOptions } = options;
+    const startedAfter = hoursAgo(hours);
+    return this.listRuns({
+      pageSize,
+      ordering,
+      startedAfter,
+      ...requestOptions
+    });
+  };
+  /**
+   * Download the JUnit XML report for a test run. Useful for CI integrations
+   * that consume JUnit (e.g. Jenkins, GitLab CI, GitHub Actions test reporters).
+   *
+   * @returns The JUnit report body as a string.
+   */
+  downloadRunJunitReport = async (runId, options = {}) => this.#client.getText("/testruns/{id}/report/junit/", {
+    pathParams: { id: runId },
+    ...options
+  });
+  /**
+   * Fetch test-run log output. The server may return either log content
+   * inline or a redirect/URL string — both are returned verbatim as text.
+   */
+  getRunLogs = async (runId, options = {}) => this.#client.getText("/testruns/{id}/logs/", {
+    pathParams: { id: runId },
+    ...options
+  });
+  /**
+   * Poll a test run's lightweight `/status/` endpoint until it reaches a
+   * terminal status.
+   *
+   * Transient network errors are retried; non-network errors propagate.
+   *
+   * @param runId - UUID of the test run to watch.
+   * @param onProgress - Invoked on every successful poll with the latest `TestRunState`
+   *   (including the terminal one). Receives `finishedSteps`/`totalSteps`/`webappUrl`
+   *   for in-flight progress UI.
+   * @param options.pollInterval - Poll interval in ms (default 2000).
+   * @param options.timeout - Wait timeout in ms (default 300_000 = 5 minutes).
+   * @throws {TimeoutError} When the run does not complete within the timeout.
+   *
+   * @example
+   * ```typescript
+   * const run = await sdk.tests.watchRunProgress(
+   *   runId,
+   *   (s) => console.log(`${s.status} ${s.finishedSteps}/${s.totalSteps}`),
+   *   { pollInterval: 3000, timeout: 600_000 },
+   * );
+   * ```
+   */
+  watchRunProgress = async (runId, onProgress, options = {}) => {
+    const { pollInterval, timeout, ...requestOptions } = options;
+    await pollRunUntilComplete(
+      () => this.getRunProgress(runId, requestOptions),
+      (status) => isCompletedStatus(status.status),
+      {
+        pollInterval,
+        timeout,
+        onProgress,
+        defaultTimeout: 3e5,
+        // 5 minutes
+        timeoutMessage: (t) => `Test run ${runId} did not complete within ${t}ms`
+      }
+    );
+    return this.getRun(runId, requestOptions);
+  };
+  /**
+   * List debug artifacts (HARs, traces, etc.) produced by a test run.
+   */
+  listRunDebugArtifacts = async (runId, options = {}) => {
+    const { signal, timeout, headers } = options;
+    return this.#client.get("/testruns/{id}/debug-artifacts/", {
+      pathParams: { id: runId },
+      signal,
+      timeout,
+      headers
+    });
+  };
+  /**
+   * Fetch a single debug artifact (e.g. HAR, network trace) for a run.
+   *
+   * @param runId - UUID of the run.
+   * @param artifactType - Artifact discriminator (e.g. `'har'`).
+   */
+  getRunDebugArtifact = async (runId, artifactType, options = {}) => this.#client.get("/testruns/{id}/debug-artifacts/{artifact_type}/", {
+    pathParams: { id: runId, artifact_type: artifactType },
+    ...options
+  });
+  export(testId, fmt, options = {}) {
+    if (fmt === "yaml") {
+      return this.#client.getText("/tests/{id}/export/{fmt}/", {
+        pathParams: { id: testId, fmt },
+        ...options
+      });
+    }
+    return this.#client.getBinary("/tests/{id}/export/{fmt}/", {
+      pathParams: { id: testId, fmt },
+      ...options
+    });
+  }
+  /**
+   * Import a single test from YAML (string) or ZIP (Uint8Array). Returns the
+   * created test summary.
+   *
+   * @param payload - YAML text or raw ZIP bytes.
+   * @param fmt - Format matching `payload` (`'yaml'` or `'zip'`).
+   * @param options.conflictMode - How to resolve naming collisions on the server
+   *   (e.g. `'rename'`). Forwarded as a query string parameter.
+   * @throws {ValidationError} When the server rejects the payload.
+   *
+   * @example
+   * ```typescript
+   * const yaml = await readFile('test.yaml', 'utf8');
+   * const test = await sdk.tests.import(yaml, 'yaml', { conflictMode: 'rename' });
+   * ```
+   */
+  import = async (payload, fmt, options = {}) => {
+    const { conflictMode, ...requestOptions } = options;
+    const form = buildTestImportFormData(payload, fmt);
+    return this.#client.postForm("/tests/import/", form, {
+      ...requestOptions,
+      queryParams: {
+        conflictMode
+      }
+    });
+  };
+};
+
+// src/modules/variables/variables.ts
+var VariablesModule = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  list = async (options = {}) => this.#client.get("/variables/", options);
+  get = async (key, options = {}) => this.#client.get("/variables/{key}/", {
+    pathParams: { key },
+    ...options
+  });
+  create = async (options) => {
+    const { key, value, type, isSecret, description, ...requestOptions } = options;
+    return this.#client.post("/variables/", {
+      body: {
+        key,
+        value,
+        type,
+        isSecret,
+        description
+      },
+      ...requestOptions
+    });
+  };
+  update = async (key, options) => {
+    const { value, type, isSecret, description, ...requestOptions } = options;
+    return this.#client.patch("/variables/{key}/", {
+      pathParams: { key },
+      body: {
+        value,
+        type,
+        isSecret,
+        description
+      },
+      ...requestOptions
+    });
+  };
+};
+
+// src/modules/visualRegression/visualRegression.ts
+var VisualRegressionModule = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  /**
+   * List reference screenshots for a given step.
+   *
+   * @param options.stepId - UUID of the visual-regression step (required).
+   * @param options.cursor - Opaque cursor returned as `nextToken` by the previous page.
+   * @param options.pageSize - Items per page.
+   */
+  listReferenceScreenshots = async (options) => {
+    const { stepId, cursor, pageSize, ...requestOptions } = options;
+    return this.#client.get(
+      "/visual-regression/reference-screenshots/",
+      {
+        queryParams: { step_id: stepId, cursor, page_size: pageSize },
+        ...requestOptions
+      }
+    );
+  };
+  /**
+   * Fetch a single reference screenshot.
+   *
+   * @throws {NotFoundError} When no reference screenshot matches `id`.
+   */
+  getReferenceScreenshot = async (id, options = {}) => this.#client.get(
+    "/visual-regression/reference-screenshots/{id}/",
+    { pathParams: { id }, ...options }
+  );
+  /**
+   * Create a new reference screenshot for a visual-regression step.
+   *
+   * @throws {ValidationError} On invalid payload.
+   */
+  createReferenceScreenshot = async (data, options = {}) => this.#client.post("/visual-regression/reference-screenshots/", {
+    body: data,
+    ...options
+  });
+  /**
+   * Patch a reference screenshot.
+   *
+   * @throws {NotFoundError} When the reference screenshot does not exist.
+   * @throws {ValidationError} On invalid payload.
+   */
+  updateReferenceScreenshot = async (id, data, options = {}) => this.#client.patch(
+    "/visual-regression/reference-screenshots/{id}/",
+    { pathParams: { id }, body: data, ...options }
+  );
+  /**
+   * Delete a reference screenshot.
+   *
+   * @throws {NotFoundError} When the reference screenshot does not exist.
+   */
+  deleteReferenceScreenshot = async (id, options = {}) => this.#client.delete("/visual-regression/reference-screenshots/{id}/", {
+    pathParams: { id },
+    ...options
+  });
+  /**
+   * Resolve failed visual-regression checks.
+   *
+   * @param options.type - `set_new_reference` accepts the observed screenshot as the new
+   *   baseline; `set_new_max_difference` raises the step's allowed difference to just above
+   *   the observed value. The value is computed server-side and cannot be supplied.
+   * @param options.stepRunId - Resolve a single step run.
+   * @param options.testRunId - Resolve every failed visual-regression step in a test run.
+   *
+   * Provide exactly one of `stepRunId` or `testRunId`.
+   */
+  resolveReview = async (options) => {
+    const { type, testRunId, stepRunId, ...requestOptions } = options;
+    return this.#client.post("/visual-regression/resolve/", {
+      body: {
+        type,
+        ...stepRunId !== void 0 ? { stepRunId } : {},
+        ...testRunId !== void 0 ? { testRunId } : {}
+      },
+      ...requestOptions
+    });
+  };
+};
+
+// ../core/dist/utils/envConfig.js
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { dirname as dirname3, resolve as resolve3 } from "path";
+import { parse as parseDotenv } from "dotenv";
+
+// ../core/dist/constants/defaults.js
+var DEFAULT_CONFIG_FILE_NAME = "bugbug.yaml";
+var DEFAULT_API_URL = "https://app.bugbug.io/api/v2";
+var DEFAULT_YAML_SCHEMA_URL = `${DEFAULT_API_URL}/schema/yaml/v1/`;
+var DEFAULT_MCP_URL = "https://mcp.bugbug.io";
+var DEFAULT_MCP_ACCESS_PATH = "/mcp";
+var DEFAULT_MCP_ACCESS_URL = `${DEFAULT_MCP_URL}${DEFAULT_MCP_ACCESS_PATH}`;
+var DOCS_BASE_URL = "https://docs.bugbug.io";
+var DOCS_ASK_URL = `${DOCS_BASE_URL}/master.md`;
+var CREDENTIALS_DIR_NAME = ".bugbug";
+var GLOBAL_CONFIG_FILE_NAME = "config.yaml";
+var DEFAULT_ROOT_CONFIG_FILE_NAME = `~/${CREDENTIALS_DIR_NAME}/${GLOBAL_CONFIG_FILE_NAME}`;
+var DEFAULT_ROOT_CONFIG_TEMP = `~/${CREDENTIALS_DIR_NAME}/tmp`;
+
+// ../core/dist/utils/globalConfigFile.js
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, resolve } from "path";
+
+// ../core/dist/utils/yaml.js
+import { parse, stringify } from "yaml";
+
+// ../core/dist/utils/globalConfigFile.js
+var globalConfigFilePath = (home = homedir()) => resolve(home, CREDENTIALS_DIR_NAME, GLOBAL_CONFIG_FILE_NAME);
+var readGlobalConfig = (home = homedir()) => {
+  const path = globalConfigFilePath(home);
+  if (!existsSync(path))
+    return {};
+  try {
+    const parsed = parse(readFileSync(path, "utf8"));
+    if (!parsed || typeof parsed !== "object")
+      return {};
+    return extractKnownFields(parsed);
+  } catch {
+    return {};
+  }
+};
+var resolveTokenForProject = (projectId, home = homedir()) => readGlobalConfig(home).credentials?.[projectId]?.token;
+var getUserToken = (home = homedir()) => readGlobalConfig(home).userToken;
+var getCurrentProject = (home = homedir()) => readGlobalConfig(home).currentProject;
+var extractKnownFields = (obj) => {
+  const out = {};
+  if (obj.credentials && typeof obj.credentials === "object") {
+    const creds = {};
+    for (const [key, raw] of Object.entries(obj.credentials)) {
+      const entry = toCredentialEntry(key, raw);
+      if (entry)
+        creds[key] = entry;
+    }
+    out.credentials = creds;
+  }
+  if (typeof obj.userToken === "string" && obj.userToken.length > 0)
+    out.userToken = obj.userToken;
+  if (typeof obj.currentProject === "string" && obj.currentProject.length > 0) {
+    out.currentProject = obj.currentProject;
+  }
+  return out;
+};
+var toCredentialEntry = (key, raw) => {
+  if (!raw || typeof raw !== "object")
+    return void 0;
+  const r = raw;
+  const id = typeof r.id === "string" && r.id.length > 0 ? r.id : key;
+  if (typeof r.token !== "string" || r.token.length === 0)
+    return void 0;
+  return { id, token: r.token };
+};
+
+// ../core/dist/utils/localConfigFile.js
+import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2, resolve as resolve2 } from "path";
+
+// ../core/dist/utils/userCwd.js
+var userCwd = () => process.env.INIT_CWD ?? process.cwd();
+
+// ../core/dist/utils/localConfigFile.js
+var localConfigFilePath = (cwd = userCwd()) => resolve2(cwd, DEFAULT_CONFIG_FILE_NAME);
+var findLocalConfigFile = (cwd = userCwd()) => {
+  let dir = resolve2(cwd);
+  while (true) {
+    const candidate = localConfigFilePath(dir);
+    if (existsSync2(candidate))
+      return candidate;
+    const parent = dirname2(dir);
+    if (parent === dir)
+      return void 0;
+    dir = parent;
+  }
+};
+var readLocalConfigFile = (cwd = userCwd()) => {
+  const path = findLocalConfigFile(cwd);
+  if (!path)
+    return {};
+  const raw = readFileSync2(path, "utf8");
+  try {
+    const parsed = parse(raw);
+    if (!parsed || typeof parsed !== "object")
+      return {};
+    return extractKnownFields2(parsed);
+  } catch (cause) {
+    throw new Error(`Failed to parse ${DEFAULT_CONFIG_FILE_NAME} at ${path}: ${cause.message}`);
+  }
+};
+var extractKnownFields2 = (obj) => {
+  const out = {};
+  if (typeof obj.projectId === "string")
+    out.projectId = obj.projectId;
+  if (typeof obj.token === "string")
+    out.token = obj.token;
+  if (typeof obj.apiUrl === "string")
+    out.apiUrl = obj.apiUrl;
+  if (typeof obj.telemetry === "boolean")
+    out.telemetry = obj.telemetry;
+  if (typeof obj.logLevel === "string")
+    out.logLevel = obj.logLevel;
+  return out;
+};
+
+// ../core/dist/utils/envConfig.js
+var resolveEnvConfig = (opts = {}) => {
+  const cwd = opts.cwd ?? userCwd();
+  const overrides = opts.overrides ?? {};
+  const localConfigFile = readLocalConfigFile(cwd);
+  const envFile = readEnvFiles(cwd);
+  const projectId = overrides.projectId ?? process.env.BUGBUG_PROJECT_ID ?? localConfigFile.projectId ?? envFile.projectId ?? getCurrentProject(opts.home);
+  const globalToken = (projectId ? resolveTokenForProject(projectId, opts.home) : void 0) ?? getUserToken(opts.home);
+  const logLevel = process.env.LOG_LEVEL ?? localConfigFile.logLevel ?? envFile.logLevel ?? "info";
+  return {
+    token: overrides.token ?? process.env.BUGBUG_API_TOKEN ?? localConfigFile.token ?? envFile.token ?? globalToken,
+    apiUrl: overrides.apiUrl ?? process.env.BUGBUG_API_URL ?? localConfigFile.apiUrl ?? envFile.apiUrl ?? DEFAULT_API_URL,
+    projectId,
+    verbose: overrides.verbose ?? logLevel === "debug",
+    nodeEnv: process.env.NODE_ENV ?? envFile.nodeEnv,
+    sentryDsn: process.env.SENTRY_DSN ?? envFile.sentryDsn
+  };
+};
+var readEnvFiles = (cwd) => {
+  const currentNodeEnv = process.env.NODE_ENV;
+  const fileNames = [".env"];
+  if (currentNodeEnv)
+    fileNames.push(`.env.${currentNodeEnv}`);
+  let token;
+  let apiUrl;
+  let projectId;
+  let logLevel;
+  let nodeEnv;
+  let sentryDsn;
+  let dir = resolve3(cwd);
+  while (true) {
+    for (const name of fileNames) {
+      const path = resolve3(dir, name);
+      if (!existsSync3(path))
+        continue;
+      try {
+        const parsed = parseDotenv(readFileSync3(path, "utf8"));
+        token ??= typeof parsed.BUGBUG_API_TOKEN === "string" ? parsed.BUGBUG_API_TOKEN : void 0;
+        apiUrl ??= typeof parsed.BUGBUG_API_URL === "string" ? parsed.BUGBUG_API_URL : void 0;
+        projectId ??= typeof parsed.BUGBUG_PROJECT_ID === "string" ? parsed.BUGBUG_PROJECT_ID : void 0;
+        logLevel ??= typeof parsed.BUGBUG_LOG_LEVEL === "string" ? parsed.BUGBUG_LOG_LEVEL : void 0;
+        nodeEnv ??= typeof parsed.NODE_ENV === "string" ? parsed.NODE_ENV : void 0;
+        sentryDsn ??= typeof parsed.SENTRY_DSN === "string" ? parsed.SENTRY_DSN : void 0;
+      } catch {
+      }
+    }
+    if (token && apiUrl && projectId)
+      break;
+    const parent = dirname3(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return { token, apiUrl, projectId, logLevel, nodeEnv, sentryDsn };
+};
+
+// ../core/dist/utils/userAgent.js
+var buildUserAgent = (clientType, version) => `BugBug ${clientType.toUpperCase()} ${version}`;
+
+// ../core/package.json
+var package_default = {
+  name: "@bugbug-io/core",
+  version: "13.39.1",
+  private: true,
+  type: "module",
+  main: "dist/index.js",
+  types: "dist/index.d.ts",
+  exports: {
+    ".": {
+      development: "./src/index.ts",
+      import: "./dist/index.js",
+      types: "./dist/index.d.ts"
+    },
+    "./constants/defaults": {
+      development: "./src/constants/defaults.ts",
+      import: "./dist/constants/defaults.js",
+      types: "./dist/constants/defaults.d.ts"
+    },
+    "./constants/status": {
+      development: "./src/constants/status.ts",
+      import: "./dist/constants/status.js",
+      types: "./dist/constants/status.d.ts"
+    },
+    "./utils/async": {
+      development: "./src/utils/async.ts",
+      import: "./dist/utils/async.js",
+      types: "./dist/utils/async.d.ts"
+    },
+    "./utils/collections": {
+      development: "./src/utils/collections.ts",
+      import: "./dist/utils/collections.js",
+      types: "./dist/utils/collections.d.ts"
+    },
+    "./utils/localConfigFile": {
+      development: "./src/utils/localConfigFile.ts",
+      import: "./dist/utils/localConfigFile.js",
+      types: "./dist/utils/localConfigFile.d.ts"
+    },
+    "./utils/env": {
+      development: "./src/utils/env.ts",
+      import: "./dist/utils/env.js",
+      types: "./dist/utils/env.d.ts"
+    },
+    "./utils/envConfig": {
+      development: "./src/utils/envConfig.ts",
+      import: "./dist/utils/envConfig.js",
+      types: "./dist/utils/envConfig.d.ts"
+    },
+    "./utils/globalConfigFile": {
+      development: "./src/utils/globalConfigFile.ts",
+      import: "./dist/utils/globalConfigFile.js",
+      types: "./dist/utils/globalConfigFile.d.ts"
+    },
+    "./utils/duration": {
+      development: "./src/utils/duration.ts",
+      import: "./dist/utils/duration.js",
+      types: "./dist/utils/duration.d.ts"
+    },
+    "./utils/logger": {
+      development: "./src/utils/logger.ts",
+      import: "./dist/utils/logger.js",
+      types: "./dist/utils/logger.d.ts"
+    },
+    "./utils/strings": {
+      development: "./src/utils/strings.ts",
+      import: "./dist/utils/strings.js",
+      types: "./dist/utils/strings.d.ts"
+    },
+    "./utils/time": {
+      development: "./src/utils/time.ts",
+      import: "./dist/utils/time.js",
+      types: "./dist/utils/time.d.ts"
+    },
+    "./utils/sentry": {
+      development: "./src/utils/sentry.ts",
+      import: "./dist/utils/sentry.js",
+      types: "./dist/utils/sentry.d.ts"
+    },
+    "./utils/userAgent": {
+      development: "./src/utils/userAgent.ts",
+      import: "./dist/utils/userAgent.js",
+      types: "./dist/utils/userAgent.d.ts"
+    },
+    "./utils/userCwd": {
+      development: "./src/utils/userCwd.ts",
+      import: "./dist/utils/userCwd.js",
+      types: "./dist/utils/userCwd.d.ts"
+    },
+    "./utils/version": {
+      development: "./src/utils/version.ts",
+      import: "./dist/utils/version.js",
+      types: "./dist/utils/version.d.ts"
+    },
+    "./utils/validation": {
+      development: "./src/utils/validation.ts",
+      import: "./dist/utils/validation.js",
+      types: "./dist/utils/validation.d.ts"
+    },
+    "./utils/variables": {
+      development: "./src/utils/variables.ts",
+      import: "./dist/utils/variables.js",
+      types: "./dist/utils/variables.d.ts"
+    },
+    "./utils/yaml": {
+      development: "./src/utils/yaml.ts",
+      import: "./dist/utils/yaml.js",
+      types: "./dist/utils/yaml.d.ts"
+    },
+    "./services/telemetry": {
+      development: "./src/services/telemetry/index.ts",
+      import: "./dist/services/telemetry/index.js",
+      types: "./dist/services/telemetry/index.d.ts"
+    },
+    "./services/telemetry/analytics": {
+      development: "./src/services/telemetry/analytics/index.ts",
+      import: "./dist/services/telemetry/analytics/index.js",
+      types: "./dist/services/telemetry/analytics/index.d.ts"
+    },
+    "./services/telemetry/sentry": {
+      development: "./src/services/telemetry/sentry.ts",
+      import: "./dist/services/telemetry/sentry.js",
+      types: "./dist/services/telemetry/sentry.d.ts"
+    },
+    "./install/install.types": {
+      development: "./src/install/install.types.ts",
+      import: "./dist/install/install.types.js",
+      types: "./dist/install/install.types.d.ts"
+    },
+    "./install/clients": {
+      development: "./src/install/clients.ts",
+      import: "./dist/install/clients.js",
+      types: "./dist/install/clients.d.ts"
+    },
+    "./install/installPlugin": {
+      development: "./src/install/installPlugin.ts",
+      import: "./dist/install/installPlugin.js",
+      types: "./dist/install/installPlugin.d.ts"
+    },
+    "./install/detect": {
+      development: "./src/install/detect.ts",
+      import: "./dist/install/detect.js",
+      types: "./dist/install/detect.d.ts"
+    },
+    "./install/installContext": {
+      development: "./src/install/installContext.ts",
+      import: "./dist/install/installContext.js",
+      types: "./dist/install/installContext.d.ts"
+    },
+    "./install/external": {
+      development: "./src/install/external.ts",
+      import: "./dist/install/external.js",
+      types: "./dist/install/external.d.ts"
+    },
+    "./install/jsonConfig": {
+      development: "./src/install/jsonConfig.ts",
+      import: "./dist/install/jsonConfig.js",
+      types: "./dist/install/jsonConfig.d.ts"
+    },
+    "./install/writers": {
+      development: "./src/install/writers.ts",
+      import: "./dist/install/writers.js",
+      types: "./dist/install/writers.d.ts"
+    },
+    "./install/skills": {
+      development: "./src/install/skills.ts",
+      import: "./dist/install/skills.js",
+      types: "./dist/install/skills.d.ts"
+    },
+    "./install/pluginRef": {
+      development: "./src/install/pluginRef.ts",
+      import: "./dist/install/pluginRef.js",
+      types: "./dist/install/pluginRef.d.ts"
+    },
+    "./install/pluginsCli": {
+      development: "./src/install/pluginsCli.ts",
+      import: "./dist/install/pluginsCli.js",
+      types: "./dist/install/pluginsCli.d.ts"
+    },
+    "./install/localCatalog": {
+      development: "./src/install/localCatalog.ts",
+      import: "./dist/install/localCatalog.js",
+      types: "./dist/install/localCatalog.d.ts"
+    },
+    "./testUtils/mockRequest": {
+      development: "./src/testUtils/mockRequest.ts",
+      import: "./dist/testUtils/mockRequest.js",
+      types: "./dist/testUtils/mockRequest.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  files: [
+    "dist/**/*"
+  ],
+  scripts: {
+    build: "tsc -b --force",
+    dev: "tsc -b --watch",
+    test: "vitest run",
+    "test:watch": "vitest --watch",
+    "format:check": "oxfmt --check",
+    "oxlint:check": "oxlint .",
+    "oxlint:ci": "oxlint . --max-warnings=0",
+    lint: "npm run format:check && npm run oxlint:check",
+    "lint:fix": "oxfmt && oxlint . --fix",
+    "lint:ci": "npm run format:check && npm run oxlint:ci",
+    typecheck: "tsc --noEmit",
+    clean: "rm -rf dist node_modules/.tmp/tsconfig.tsbuildinfo"
+  },
+  dependencies: {
+    "@sentry/node": "^10.66.0",
+    dotenv: "^16.6.1",
+    yaml: "^2.8.4"
+  },
+  devDependencies: {
+    "@bugbug-io/config": "*",
+    "@bugbug-io/oxlint-config": "*",
+    nock: "^14.0.9"
+  },
+  engines: {
+    node: ">=24"
+  }
+};
+
+// ../core/dist/utils/version.js
+var getVersion = () => package_default.version;
+
+// src/services/apiClient/apiClient.ts
+import createClient from "openapi-fetch";
+
+// src/services/rateLimiter/rateLimiter.constants.ts
+var RATE_LIMIT_MIN_REQUESTS = 1;
+var RATE_LIMIT_MAX_REQUESTS = 100;
+var RATE_LIMIT_MIN_WINDOW_MS = 1e3;
+var RATE_LIMIT_MAX_WINDOW_MS = 6e4;
+
+// src/services/rateLimiter/rateLimiter.ts
+var RateLimiter = class {
+  #requests = [];
+  #config;
+  constructor(config) {
+    this.#warnIfUnsupportedConfig(config);
+    this.#config = {
+      maxRequests: config.maxRequests,
+      windowMs: config.windowMs,
+      retryAfter: config.retryAfter || 1e3,
+      retryServer429: config.retryServer429 ?? true,
+      exponentialBackoff: {
+        baseDelay: config.exponentialBackoff.baseDelay,
+        maxDelay: config.exponentialBackoff.maxDelay,
+        maxRetries: config.exponentialBackoff.maxRetries
+      }
+    };
+  }
+  #warnIfUnsupportedConfig(config) {
+    if (config.maxRequests < RATE_LIMIT_MIN_REQUESTS || config.maxRequests > RATE_LIMIT_MAX_REQUESTS) {
+      console.warn(
+        `BugBug SDK rateLimit.maxRequests should be between ${RATE_LIMIT_MIN_REQUESTS} and ${RATE_LIMIT_MAX_REQUESTS}.`
+      );
+    }
+    if (config.windowMs < RATE_LIMIT_MIN_WINDOW_MS || config.windowMs > RATE_LIMIT_MAX_WINDOW_MS) {
+      console.warn(
+        `BugBug SDK rateLimit.windowMs should be between ${RATE_LIMIT_MIN_WINDOW_MS} and ${RATE_LIMIT_MAX_WINDOW_MS}.`
+      );
+    }
+  }
+  /**
+   * Execute a function with rate limiting and exponential backoff.
+   *
+   * The retry loop fires when:
+   * 1. The **client-side** gate trips (`canMakeRequest()` returns false) — `fn`
+   *    was never called.
+   * 2. The function throws `RateLimitError` (typically a server 429) AND
+   *    `retryServer429` is enabled. Retrying server 429s on non-idempotent
+   *    requests (POST startRun, POST startRun) can produce duplicate
+   *    resources — set `retryServer429: false` to disable.
+   *
+   * @param fn - The function to execute under rate limiting.
+   * @returns The function's resolved value.
+   * @throws {RateLimitError} When retries are exhausted or `retryServer429` is
+   *   disabled and the server returned 429.
+   */
+  async execute(fn) {
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.#config.exponentialBackoff.maxRetries; attempt++) {
+      if (!this.#canMakeRequest()) {
+        const waitTime = this.#getWaitTime();
+        const gateError = new RateLimitError(
+          waitTime,
+          `Rate limit exceeded. Wait ${waitTime}ms before retrying.`
+        );
+        lastError = gateError;
+        if (attempt === this.#config.exponentialBackoff.maxRetries) {
+          throw gateError;
+        }
+        await this.#sleep(this.#computeBackoff(attempt, gateError.retryAfter));
+        continue;
+      }
+      const stamp = this.#recordRequest();
+      try {
+        return await fn();
+      } catch (fnError) {
+        this.#releaseRequest(stamp);
+        if (!(fnError instanceof RateLimitError)) {
+          throw fnError;
+        }
+        lastError = fnError;
+        if (!this.#config.retryServer429) {
+          throw fnError;
+        }
+        if (attempt === this.#config.exponentialBackoff.maxRetries) {
+          throw fnError;
+        }
+        await this.#sleep(this.#computeBackoff(attempt, fnError.retryAfter));
+      }
+    }
+    throw lastError || new Error("Max retries exceeded");
+  }
+  #computeBackoff = (attempt, retryAfter) => {
+    const baseDelay = retryAfter || this.#config.exponentialBackoff.baseDelay;
+    const delay = Math.min(
+      baseDelay * Math.pow(2, attempt),
+      this.#config.exponentialBackoff.maxDelay
+    );
+    const jitter = Math.random() * 0.1 * delay;
+    return delay + jitter;
+  };
+  /**
+   * Sleep utility
+   */
+  #sleep(ms) {
+    return new Promise((resolve4) => {
+      setTimeout(resolve4, ms);
+    });
+  }
+  /**
+   * Check if we can make a request within the rate limit
+   */
+  #canMakeRequest() {
+    this.#cleanOldRequests();
+    return this.#requests.length < this.#config.maxRequests;
+  }
+  /**
+   * Record a new request. Returns the timestamp pushed so callers can later
+   * release **this specific** stamp via {@link releaseRequest}, avoiding the
+   * pop()-the-wrong-stamp race when multiple `execute()` calls overlap.
+   */
+  #recordRequest() {
+    const stamp = Date.now();
+    this.#requests.push(stamp);
+    return stamp;
+  }
+  /**
+   * Remove a previously-recorded stamp by identity (first occurrence). Safe to
+   * call when the stamp has already been cleaned by the window-trim sweep —
+   * the lookup simply finds no match and the array is left untouched.
+   */
+  #releaseRequest = (stamp) => {
+    const index = this.#requests.indexOf(stamp);
+    if (index !== -1) {
+      this.#requests.splice(index, 1);
+    }
+  };
+  /**
+   * Clean up old requests outside the time window
+   */
+  #cleanOldRequests() {
+    const now2 = Date.now();
+    const cutoff = now2 - this.#config.windowMs;
+    this.#requests = this.#requests.filter((timestamp) => timestamp > cutoff);
+  }
+  /**
+   * Get the time to wait before the next request can be made
+   */
+  #getWaitTime() {
+    if (this.#requests.length === 0) {
+      return 0;
+    }
+    const oldestRequest = Math.min(...this.#requests);
+    const waitTime = this.#config.windowMs - (Date.now() - oldestRequest);
+    return Math.max(0, waitTime);
+  }
+  /**
+   * Snapshot of the current rate-limiter state.
+   *
+   * @returns `requestsInWindow`, `remainingRequests`, `canMakeRequest`,
+   *   `resetTime` (epoch ms when the oldest tracked request leaves the
+   *   window — `null` when no requests are tracked).
+   */
+  getStatus() {
+    this.#cleanOldRequests();
+    return {
+      requestsInWindow: this.#requests.length,
+      maxRequests: this.#config.maxRequests,
+      remainingRequests: Math.max(0, this.#config.maxRequests - this.#requests.length),
+      windowMs: this.#config.windowMs,
+      resetTime: this.#requests.length > 0 ? Math.min(...this.#requests) + this.#config.windowMs : null,
+      canMakeRequest: this.#canMakeRequest()
+    };
+  }
+  /**
+   * Discard all tracked request timestamps. Useful in tests or after a clock
+   * jump. Not normally called in production.
+   */
+  reset() {
+    this.#requests = [];
+  }
+};
+
+// src/services/apiClient/apiClient.utils.ts
+function formatApiErrorMessage(error) {
+  if (isHtmlErrorBody(error)) return "";
+  return formatApiErrorValue(error) ?? "";
+}
+function isHtmlErrorBody(error) {
+  if (typeof error !== "string") return false;
+  const trimmed = error.trimStart().toLowerCase();
+  return trimmed.startsWith("<!doctype html") || trimmed.startsWith("<html");
+}
+function formatNetworkErrorMessage(error) {
+  const { cause } = error;
+  const causeMessage = formatNetworkErrorCause(cause);
+  return causeMessage ? `Network error: ${error.message} (${causeMessage})` : `Network error: ${error.message}`;
+}
+function formatUnexpectedResponseMessage(error, method, url) {
+  return `Unexpected non-JSON response from ${method} ${url}: ${error.message}. Check BUGBUG_API_URL; this usually means the server returned an HTML page instead of the BugBug API.`;
+}
+function formatNetworkErrorCause(cause) {
+  if (!cause) return void 0;
+  if (cause instanceof Error && cause.message) return cause.message;
+  if (typeof cause === "string") return cause;
+  if (typeof cause !== "object") return String(cause);
+  const obj = cause;
+  const code = typeof obj.code === "string" ? obj.code : void 0;
+  const address = typeof obj.address === "string" ? obj.address : void 0;
+  const port = typeof obj.port === "number" || typeof obj.port === "string" ? String(obj.port) : void 0;
+  if (code && address && port) return `${code} ${address}:${port}`;
+  if (code && address) return `${code} ${address}`;
+  if (code) return code;
+  try {
+    return JSON.stringify(obj);
+  } catch {
+    return String(cause);
+  }
+}
+function parseErrorBody(error) {
+  if (typeof error !== "string") return error;
+  const trimmed = error.trim();
+  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return void 0;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return void 0;
+  }
+}
+function extractFieldErrors(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return void 0;
+  const out = {};
+  const walk = (value, path) => {
+    if (value === null || value === void 0) return;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      if (path) (out[path] ??= []).push(String(value));
+      return;
+    }
+    if (Array.isArray(value)) {
+      const stringEntries = value.filter(
+        (v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean"
+      );
+      if (stringEntries.length === value.length && path) {
+        out[path] = [...out[path] ?? [], ...stringEntries.map(String)];
+        return;
+      }
+      value.forEach((item, index) => walk(item, path ? `${path}[${index}]` : `[${index}]`));
+      return;
+    }
+    if (typeof value === "object") {
+      for (const [key, nested] of Object.entries(value)) {
+        if (!path && (key === "detail" || key === "message" || key === "error")) continue;
+        walk(nested, path ? `${path}.${key}` : key);
+      }
+    }
+  };
+  walk(body, "");
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function formatApiErrorValue(value, path = "") {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) {
+    const parts2 = value.map((item) => formatApiErrorValue(item, path)).filter((item) => Boolean(item));
+    return parts2.length ? parts2.join(", ") : void 0;
+  }
+  if (!value || typeof value !== "object") return void 0;
+  const obj = value;
+  for (const key of ["message", "detail", "error"]) {
+    const message = formatApiErrorValue(obj[key], path);
+    if (message) return message;
+  }
+  const parts = Object.entries(obj).map(([key, nested]) => {
+    const nestedPath = path ? `${path}.${key}` : key;
+    const formatted = formatApiErrorValue(nested, nestedPath);
+    if (!formatted) return void 0;
+    return formatted.includes(":") ? formatted : `${nestedPath}: ${formatted}`;
+  }).filter((item) => Boolean(item));
+  return parts.length ? parts.join("; ") : void 0;
+}
+function parseJsonOrText(text) {
+  if (!text) return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+// src/services/apiClient/apiClient.ts
+var BugBugApiClient = class {
+  #config;
+  #client;
+  #rateLimiter;
+  constructor(config) {
+    const resolved = resolveEnvConfig({
+      overrides: { token: config.apiToken, apiUrl: config.apiUrl, projectId: config.projectId }
+    });
+    this.#config = {
+      apiToken: resolved.token ?? "",
+      projectId: resolved.projectId ?? "",
+      triggeredBy: config.triggeredBy || "api",
+      apiUrl: this.#normalizeApiUrl(resolved.apiUrl),
+      verbose: config.verbose || false,
+      logLevel: config.logLevel || "info",
+      timeout: config.timeout || 3e4,
+      rateLimit: config.rateLimit || {
+        maxRequests: 100,
+        windowMs: 6e4,
+        exponentialBackoff: {
+          baseDelay: 1e3,
+          maxDelay: 3e4,
+          maxRetries: 3
+        }
+      },
+      requestHeaders: {
+        "User-Agent": buildUserAgent("sdk", getVersion()),
+        ...config.requestHeaders
+      },
+      onBeforeRequest: config.onBeforeRequest || (() => {
+      }),
+      onAfterRequest: config.onAfterRequest || (() => {
+      }),
+      onRequestError: config.onRequestError || (() => {
+      })
+    };
+    this.#validateConfig();
+    this.#client = this.#createApiClient();
+    this.#rateLimiter = new RateLimiter(this.#config.rateLimit);
+  }
+  #createApiClient = () => createClient({
+    baseUrl: this.#config.apiUrl,
+    headers: {
+      ...this.#identityHeaders(),
+      "Content-Type": "application/json"
+    }
+  });
+  /** Auth + identification headers shared by the openapi client and raw fetch paths. */
+  #identityHeaders = () => ({
+    ...this.#config.requestHeaders,
+    Authorization: `Token ${this.#config.apiToken}`
+  });
+  /**
+   * Project-scoping query param for organization/user tokens. Project tokens don't
+   * need it (their project is implied), so it's only sent when a project id is
+   * configured. The backend public API reads `projectId` from query params,
+   * request body, or URL kwargs.
+   */
+  #scopedParams = (params, options = {}) => {
+    const { projectScoped = true } = options;
+    if (!projectScoped || !this.#config.projectId) return params;
+    const query = params?.query ?? {};
+    if (query.projectId !== void 0 || query.project_id !== void 0) return params;
+    return {
+      ...params?.path ? { path: params.path } : {},
+      query: {
+        ...query,
+        projectId: this.#config.projectId
+      }
+    };
+  };
+  /**
+   * Detect the "project id required" 400 the backend returns when an
+   * organization/user token hits a project-scoped endpoint without a project.
+   *
+   * STUB: keyed off message/field text until the backend exposes a stable
+   * error code for this case.
+   */
+  #isMissingProjectId = (message, fields) => {
+    const haystacks = [
+      message,
+      ...Object.keys(fields ?? {}),
+      ...Object.values(fields ?? {}).flat()
+    ];
+    return haystacks.some((value) => /project[\s_-]*id/i.test(value) && /requir/i.test(value)) || Object.keys(fields ?? {}).some((key) => /^project[\s_-]*id$/i.test(key));
+  };
+  /**
+   * Validate the configuration
+   */
+  #validateConfig = () => {
+    if (!this.#config.apiToken) {
+      throw new ConfigurationError("API token is required");
+    }
+    if (!this.#config.apiUrl) {
+      throw new ConfigurationError("API URL is required");
+    }
+    if (!URL.canParse(this.#config.apiUrl)) {
+      throw new ConfigurationError("Invalid API URL format");
+    }
+  };
+  /**
+   * Make an HTTP request with rate limiting using openapi-fetch
+   */
+  #makeRequest = async (method, path, options = {}) => {
+    const { body, params, signal, timeout, headers: customHeaders, projectScoped = true } = options;
+    const scopedParams = this.#scopedParams(params, { projectScoped });
+    const requestUrl = this.#buildRequestUrl(path, scopedParams);
+    const requestOrigin = { method, url: requestUrl };
+    const requestData = {
+      method,
+      path,
+      body,
+      params: scopedParams,
+      signal,
+      timeout,
+      headers: customHeaders
+    };
+    this.#config.onBeforeRequest(requestData);
+    return this.#rateLimiter.execute(async () => {
+      const abortContext = this.#createAbortContext(signal, timeout);
+      try {
+        if (this.#config.verbose) {
+          this.#log("debug", `\u2192 ${method} ${path}`, { params, body });
+        }
+        const requestOptions = {
+          signal: abortContext.signal,
+          headers: {
+            ...customHeaders,
+            ...this.#identityHeaders()
+          }
+        };
+        if (scopedParams) {
+          requestOptions.params = scopedParams;
+        }
+        if (body !== void 0) {
+          requestOptions.body = body;
+        }
+        let response;
+        switch (method) {
+          case "GET":
+            response = await this.#client.GET(path, requestOptions);
+            break;
+          case "POST":
+            response = await this.#client.POST(path, requestOptions);
+            break;
+          case "PUT":
+            response = await this.#client.PUT(path, requestOptions);
+            break;
+          case "DELETE":
+            response = await this.#client.DELETE(path, requestOptions);
+            break;
+          case "PATCH":
+            response = await this.#client.PATCH(path, requestOptions);
+            break;
+          default:
+            throw new ValidationError(`Unsupported HTTP method: ${method}`);
+        }
+        abortContext.clear();
+        if (this.#config.verbose) {
+          this.#log("debug", `\u2190 ${response.response?.status} ${method} ${path}`, {
+            status: response.response?.status,
+            statusText: response.response?.statusText
+          });
+        }
+        if (response.error) {
+          this.#config.onRequestError(requestData, response.response, response.error);
+          await this.#handleOpenApiError(response.error, response.response, requestOrigin);
+        }
+        const result = response.data;
+        this.#config.onAfterRequest(requestData);
+        return result;
+      } catch (error) {
+        abortContext.clear();
+        if (error instanceof SyntaxError) {
+          throw new UnexpectedResponseError(
+            formatUnexpectedResponseMessage(error, method, requestUrl),
+            error,
+            requestOrigin
+          );
+        }
+        throw this.#toTransportError(error, requestOrigin, abortContext);
+      }
+    });
+  };
+  /**
+   * Handle OpenAPI fetch errors. Always reads the real `response.status` so
+   * "no response" never masquerades as 500.
+   */
+  #handleOpenApiError = async (error, response, request) => {
+    const status = response?.status;
+    const errorMessage = formatApiErrorMessage(error);
+    const errorBody = parseErrorBody(error);
+    const fields = extractFieldErrors(errorBody);
+    switch (status) {
+      case 401:
+        throw new AuthenticationError(
+          errorMessage || "Invalid API token or authentication failed",
+          response,
+          request
+        );
+      case 403:
+        throw new AuthorizationError(
+          errorMessage || "Access denied. Check your permissions.",
+          response,
+          request
+        );
+      case 404:
+        throw new NotFoundError(errorMessage || "Resource not found", response, request);
+      case 400:
+      case 422:
+        if (status === 400 && this.#isMissingProjectId(errorMessage, fields)) {
+          throw new MissingProjectIdError(void 0, response, request);
+        }
+        throw new ValidationError(
+          errorMessage || "Validation failed. Check your request data.",
+          response,
+          fields,
+          request
+        );
+      case 429: {
+        const retryAfter = response?.headers.get("Retry-After");
+        const retryAfterMs = retryAfter ? parseInt(retryAfter) * 1e3 : void 0;
+        throw new RateLimitError(
+          retryAfterMs,
+          errorMessage || "Rate limit exceeded",
+          response,
+          request
+        );
+      }
+      case 500:
+        throw new InternalServerError(
+          errorMessage || "Internal server error. Please try again later.",
+          response,
+          request
+        );
+      case 502:
+      case 503:
+      case 504:
+        throw new ServiceUnavailableError(
+          errorMessage || "Service temporarily unavailable. Please try again later.",
+          response,
+          request
+        );
+      default:
+        if (status === void 0) {
+          throw new NetworkError(
+            errorMessage || "No response received from BugBug API",
+            void 0,
+            request
+          );
+        }
+        throw new HttpError(
+          errorMessage || `HTTP ${status}: ${response?.statusText || "Unknown error"}`,
+          status,
+          response,
+          request
+        );
+    }
+  };
+  /**
+   * Issue a GET request through the openapi-fetch JSON path.
+   *
+   * @param path - API path template (e.g. `/tests/{id}/`).
+   * @param options.queryParams - Mapped to URL search params; `undefined`/`null` values are dropped.
+   * @param options.pathParams - Used to substitute `{name}` placeholders in `path`.
+   * @returns Parsed JSON response body typed as `T`.
+   */
+  get = async (path, options = {}) => {
+    const { queryParams, pathParams, ...requestOptions } = options;
+    return this.#makeRequest("GET", path, {
+      params: {
+        query: queryParams,
+        path: pathParams
+      },
+      ...requestOptions
+    });
+  };
+  /**
+   * Issue a POST request. The body is JSON-serialized by openapi-fetch.
+   *
+   * @param path - API path template.
+   * @param options.body - Request body (JSON-serialized).
+   * @param options.queryParams - URL search params.
+   * @param options.pathParams - Path-segment values.
+   */
+  post = async (path, options = {}) => {
+    const { body, queryParams, pathParams, ...requestOptions } = options;
+    return this.#makeRequest("POST", path, {
+      body,
+      params: {
+        query: queryParams,
+        path: pathParams
+      },
+      ...requestOptions
+    });
+  };
+  getAppRoot = async (path, options = {}) => {
+    const { acceptRedirect = false, authenticated = true, redirect, ...requestOptions } = options;
+    return this.#rawFetch(
+      "GET",
+      path,
+      { ...requestOptions, acceptRedirect, authenticated, redirect, useAppRoot: true },
+      async (response) => {
+        if (acceptRedirect && response.status >= 300 && response.status < 400) {
+          return response;
+        }
+        const text = await response.text();
+        if (!text) return response;
+        return parseJsonOrText(text);
+      }
+    );
+  };
+  postAppRoot = async (path, options = {}) => {
+    const { authenticated = true, body, ...requestOptions } = options;
+    return this.#rawFetch(
+      "POST",
+      path,
+      {
+        ...requestOptions,
+        authenticated,
+        useAppRoot: true,
+        ...body !== void 0 ? { body: JSON.stringify(body), contentType: "application/json" } : {}
+      },
+      async (response) => parseJsonOrText(await response.text())
+    );
+  };
+  /**
+   * Issue a JSON POST request for endpoints that intentionally return no
+   * response body even on 2xx success.
+   */
+  postNoContent = async (path, options = {}) => {
+    const { body, queryParams, pathParams, ...requestOptions } = options;
+    return this.#rawFetch(
+      "POST",
+      path,
+      {
+        ...requestOptions,
+        queryParams,
+        pathParams,
+        ...body !== void 0 ? { body: JSON.stringify(body), contentType: "application/json" } : {}
+      },
+      async () => void 0
+    );
+  };
+  /** Issue a PUT request (full-replace semantics). See {@link post} for parameters. */
+  put = async (path, options = {}) => {
+    const { body, queryParams, pathParams, ...requestOptions } = options;
+    return this.#makeRequest("PUT", path, {
+      body,
+      params: {
+        query: queryParams,
+        path: pathParams
+      },
+      ...requestOptions
+    });
+  };
+  /** Issue a PATCH request (partial-update semantics). See {@link post} for parameters. */
+  patch = async (path, options = {}) => {
+    const { body, queryParams, pathParams, ...requestOptions } = options;
+    return this.#makeRequest("PATCH", path, {
+      body,
+      params: {
+        query: queryParams,
+        path: pathParams
+      },
+      ...requestOptions
+    });
+  };
+  /**
+   * Issue a DELETE request. An optional `body` is accepted for DRF endpoints
+   * that require one, though `openapi-fetch` only sends it when the OpenAPI
+   * spec declares it.
+   */
+  delete = async (path, options = {}) => {
+    const { body, queryParams, pathParams, ...requestOptions } = options;
+    return this.#makeRequest("DELETE", path, {
+      body,
+      params: {
+        query: queryParams,
+        path: pathParams
+      },
+      ...requestOptions
+    });
+  };
+  /**
+   * GET an endpoint that returns plain text (e.g. JUnit XML, logs).
+   *
+   * Bypasses the openapi-fetch JSON parser. Errors still flow through the
+   * shared status→error mapping.
+   *
+   * @returns The response body as a string.
+   */
+  getText = async (path, options = {}) => this.#rawFetch("GET", path, options, async (response) => response.text());
+  /**
+   * GET an endpoint returning binary bytes (ZIP / octet-stream).
+   *
+   * @returns The response body as `Uint8Array`.
+   */
+  getBinary = async (path, options = {}) => this.#rawFetch(
+    "GET",
+    path,
+    options,
+    async (response) => new Uint8Array(await response.arrayBuffer())
+  );
+  /**
+   * POST raw bytes or text with an explicit `Content-Type`.
+   *
+   * Used for binary (ZIP) and YAML uploads that don't fit the openapi-fetch
+   * JSON path. The response is parsed as JSON when possible, otherwise the
+   * raw text is returned.
+   *
+   * @param path - API path template.
+   * @param body - Raw bytes or string to send as the request body.
+   * @param options.contentType - MIME type sent in the `Content-Type` header.
+   * @returns Parsed JSON body or raw text.
+   */
+  postRaw = async (path, body, options) => {
+    const { contentType, ...rest } = options;
+    return this.#rawFetch(
+      "POST",
+      path,
+      { ...rest, body, contentType },
+      async (response) => parseJsonOrText(await response.text())
+    );
+  };
+  /**
+   * POST a `multipart/form-data` body. The browser/fetch sets the
+   * `Content-Type` boundary automatically.
+   *
+   * @param path - API path template.
+   * @param form - The `FormData` instance to send.
+   * @returns Parsed JSON body or raw text.
+   */
+  postForm = async (path, form, options = {}) => this.#rawFetch(
+    "POST",
+    path,
+    { ...options, body: form },
+    async (response) => parseJsonOrText(await response.text())
+  );
+  /**
+   * Shared scaffolding for the raw-`fetch` paths (text/binary/multipart/custom
+   * content type) that bypass openapi-fetch. Owns URL building, request hooks,
+   * rate limiting, timeout/abort handling, verbose logging, error mapping, and
+   * the transport-level catch — so each public method only supplies how to read
+   * the successful response body.
+   */
+  #rawFetch = async (method, path, options, readBody) => {
+    const {
+      queryParams,
+      pathParams,
+      signal,
+      timeout,
+      headers: customHeaders,
+      body,
+      contentType,
+      authenticated = true,
+      acceptRedirect = false,
+      redirect,
+      useAppRoot = false,
+      projectScoped = true
+    } = options;
+    const scopedParams = this.#scopedParams(
+      { path: pathParams, query: queryParams },
+      { projectScoped: projectScoped && authenticated && !useAppRoot }
+    );
+    const url = this.#buildRequestUrl(path, scopedParams, useAppRoot);
+    const requestData = {
+      method,
+      path,
+      params: scopedParams,
+      signal,
+      timeout,
+      headers: customHeaders
+    };
+    const requestOrigin = { method, url };
+    this.#config.onBeforeRequest(requestData);
+    return this.#rateLimiter.execute(async () => {
+      const abortContext = this.#createAbortContext(signal, timeout);
+      try {
+        if (this.#config.verbose) {
+          this.#log("debug", `\u2192 ${method} ${path} (raw)`, { queryParams, pathParams });
+        }
+        const response = await fetch(url, {
+          method,
+          redirect,
+          headers: {
+            // Caller headers go first so the SDK's auth + identification
+            // headers always win — a stray `Authorization` in caller-supplied
+            // headers would otherwise silently replace the SDK token.
+            ...customHeaders,
+            ...authenticated ? this.#identityHeaders() : this.#requestHeaders(),
+            ...contentType ? { "Content-Type": contentType } : {}
+          },
+          ...body !== void 0 ? { body } : {},
+          signal: abortContext.signal
+        });
+        abortContext.clear();
+        if (this.#config.verbose) {
+          this.#log("debug", `\u2190 ${response.status} ${method} ${path}`, {
+            status: response.status,
+            statusText: response.statusText
+          });
+        }
+        if (!response.ok && !(acceptRedirect && response.status >= 300 && response.status < 400)) {
+          const errorText = await response.text();
+          this.#config.onRequestError(requestData, response, new Error(errorText));
+          await this.#handleOpenApiError(errorText, response, requestOrigin);
+        }
+        const result = await readBody(response);
+        this.#config.onAfterRequest(requestData);
+        return result;
+      } catch (error) {
+        abortContext.clear();
+        throw this.#toTransportError(error, requestOrigin, abortContext);
+      }
+    });
+  };
+  #createAbortContext = (signal, timeout) => {
+    const controller = new AbortController();
+    const requestTimeout = timeout || this.#config.timeout;
+    let timedOut = false;
+    const timeoutId = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, requestTimeout);
+    const abortFromCaller = () => {
+      if (!controller.signal.aborted) {
+        controller.abort(signal?.reason);
+      }
+    };
+    if (signal) {
+      if (signal.aborted) {
+        abortFromCaller();
+      } else {
+        signal.addEventListener("abort", abortFromCaller, { once: true });
+      }
+    }
+    return {
+      signal: controller.signal,
+      timeout: requestTimeout,
+      isTimedOut: () => timedOut,
+      clear: () => {
+        clearTimeout(timeoutId);
+        signal?.removeEventListener("abort", abortFromCaller);
+      }
+    };
+  };
+  /**
+   * Map a thrown transport-level error to the matching SDK error, or rethrow
+   * SDK errors (e.g. from `handleOpenApiError`) untouched.
+   */
+  #toTransportError = (error, requestOrigin, abortContext) => {
+    if (error instanceof DOMException && error.name === "AbortError") {
+      if (abortContext?.isTimedOut()) {
+        return new TimeoutError(abortContext.timeout, void 0, requestOrigin);
+      }
+      return new CancellationError("Request was cancelled", requestOrigin);
+    }
+    if (error instanceof TypeError && error.message.includes("fetch")) {
+      return new NetworkError(formatNetworkErrorMessage(error), error, requestOrigin);
+    }
+    return error;
+  };
+  /**
+   * Return a frozen snapshot of the resolved configuration (defaults applied).
+   */
+  getConfig = () => ({ ...this.#config });
+  /**
+   * Patch configuration at runtime. Re-builds the openapi-fetch client when
+   * `apiToken` or `apiUrl` changes, and rebuilds the rate limiter when
+   * `rateLimit` changes — other fields take effect on the next request.
+   *
+   * @param updates - Partial configuration overrides to merge in.
+   */
+  updateConfig = (updates) => {
+    this.#config = { ...this.#config, ...updates };
+    this.#config.apiUrl = this.#normalizeApiUrl(this.#config.apiUrl);
+    if (updates.apiToken || updates.apiUrl) {
+      this.#client = this.#createApiClient();
+    }
+    if (updates.rateLimit) {
+      this.#rateLimiter = new RateLimiter(this.#config.rateLimit);
+    }
+  };
+  /**
+   * Snapshot of the in-process rate-limiter state.
+   *
+   * @returns `{ requestsInWindow, remainingRequests, maxRequests, windowMs, resetTime, canMakeRequest }`.
+   */
+  getRateLimitStatus = () => this.#rateLimiter.getStatus();
+  /**
+   * Log messages based on log level
+   */
+  #log = (level, message, data) => {
+    const levels = { debug: 0, info: 1, warn: 2, error: 3 };
+    const currentLevel = levels[this.#config.logLevel];
+    const messageLevel = levels[level];
+    if (messageLevel >= currentLevel) {
+      const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+      const logMessage = `[${timestamp}] [${level.toUpperCase()}] ${message}`;
+      if (data) {
+        console[level](logMessage, data);
+      } else {
+        console[level](logMessage);
+      }
+    }
+  };
+  #normalizeApiUrl = (apiUrl) => apiUrl.replace(/\/+$/, "");
+  #requestHeaders = () => ({
+    ...this.#config.requestHeaders
+  });
+  /**
+   * Base URL for the few endpoints Django serves at its site root rather than
+   * under `/api/v2` (`/auth/authorize-url`, `/auth/identity`,
+   * `/auth/oauth/token/`).
+   *
+   * Stripping the `/api/v<n>` suffix is correct when talking straight to Django
+   * (local dev, in-cluster `backend:8000`). Hosted BugBug sits behind nginx,
+   * which forwards those routes only under its `/rest/` prefix — bare requests
+   * fall through to the web app and return HTML — so those deployments set
+   * `BUGBUG_APP_URL` to override this.
+   */
+  #appBaseUrl = () => this.#normalizeApiUrl(
+    process.env.BUGBUG_APP_URL || this.#config.apiUrl.replace(/\/api\/v\d+\/?$/i, "")
+  );
+  #buildRequestUrl = (path, params, useAppRoot = false) => {
+    let url = `${useAppRoot ? this.#appBaseUrl() : this.#config.apiUrl}${path}`;
+    if (params?.path) {
+      Object.entries(params.path).forEach(([key, value]) => {
+        url = url.replace(`{${key}}`, encodeURIComponent(value));
+      });
+    }
+    if (params?.query) {
+      const searchParams = new URLSearchParams();
+      Object.entries(params.query).forEach(([key, value]) => {
+        if (value !== void 0 && value !== null) {
+          searchParams.append(key, String(value));
+        }
+      });
+      const query = searchParams.toString();
+      if (query) url += `?${query}`;
+    }
+    return url;
+  };
+};
+
+// src/sdk.ts
+var BugBugSDK = class {
+  #client;
+  tests;
+  suites;
+  profiles;
+  config;
+  groups;
+  components;
+  steps;
+  stepRuns;
+  project;
+  projectArtifacts;
+  projects;
+  variables;
+  visualRegression;
+  auth;
+  /**
+   * @param config - SDK configuration (API token, base URL, rate limits, etc.)
+   */
+  constructor(config) {
+    this.#client = new BugBugApiClient(config);
+    this.tests = new TestsModule(this.#client);
+    this.suites = new SuitesModule(this.#client);
+    this.profiles = new ProfilesModule(this.#client);
+    this.config = new ConfigModule(this.#client);
+    this.groups = new GroupsModule(this.#client);
+    this.components = new ComponentsModule(this.#client);
+    this.steps = new StepsModule(this.#client);
+    this.stepRuns = new StepRunsModule(this.#client);
+    this.project = new ProjectModule(this.#client);
+    this.projectArtifacts = new ProjectArtifactsModule(this.#client);
+    this.projects = new ProjectsModule(this.#client);
+    this.variables = new VariablesModule(this.#client);
+    this.visualRegression = new VisualRegressionModule(this.#client);
+    this.auth = new AuthModule(this.#client);
+  }
+  /**
+   * Get the current SDK configuration.
+   *
+   * @returns Readonly configuration object with all resolved defaults
+   *
+   * @example
+   * ```typescript
+   * const config = sdk.getConfig();
+   * console.log(`API URL: ${config.apiUrl}`);
+   * console.log(`Verbose: ${config.verbose}`);
+   * ```
+   */
+  getConfig = () => this.#client.getConfig();
+  /**
+   * Update SDK configuration at runtime.
+   *
+   * @param updates - Partial configuration updates to apply
+   *
+   * @example
+   * ```typescript
+   * sdk.updateConfig({
+   *   verbose: true,
+   *   timeout: 60000
+   * });
+   * ```
+   */
+  updateConfig = (updates) => {
+    this.#client.updateConfig(updates);
+  };
+  /**
+   * Set the active project for subsequent project-scoped requests.
+   * Shorthand for `updateConfig({ projectId })`.
+   *
+   * @param projectId - The project id to scope requests to.
+   *
+   * @example
+   * ```typescript
+   * sdk.setProject('00000000-0000-0000-0000-000000000001');
+   * ```
+   */
+  setProject = (projectId) => {
+    this.updateConfig({ projectId });
+  };
+  /**
+   * Test API connectivity and authentication.
+   *
+   * @param options - Request options including timeout and signal
+   * @returns Connectivity test result with timing and status
+   *
+   * @example
+   * ```typescript
+   * const result = await sdk.testConnection();
+   * if (result.connected) {
+   *   console.log(`Connected in ${result.responseTime}ms`);
+   * } else {
+   *   console.error(`Connection failed: ${result.error}`);
+   * }
+   * ```
+   */
+  testConnection = async (options = {}) => this.config.testConnectivity(options);
+};
+
+// src/modules/visualRegression/visualRegression.constants.ts
+var VISUAL_REGRESSION_RESOLUTION_ACTIONS = [
+  "acceptBaseline",
+  "increaseMaxDifference"
+];
+var VISUAL_REGRESSION_RESOLUTION_TYPE_BY_ACTION = {
+  acceptBaseline: "set_new_reference",
+  increaseMaxDifference: "set_new_max_difference"
+};
+
+// src/modules/auth/auth.types.ts
+var BUGBUG_CLI_OAUTH_CLIENT_ID = "bugbug-cli";
+var BUGBUG_MCP_OAUTH_CLIENT_ID = "bugbug-mcp";
+var BUGBUG_OAUTH_CODE_CHALLENGE_METHOD = "S256";
+
+// src/modules/auth/auth.utils.ts
+import { randomBytes, randomUUID, createHash } from "crypto";
+var createOAuthState = () => randomUUID();
+var createOAuthCodeVerifier = () => randomBytes(48).toString("base64url");
+var createOAuthCodeChallenge = (verifier) => createHash("sha256").update(verifier).digest("base64url");
+
+// src/modules/steps/steps.utils.ts
+var ASSERTION_STEP_TYPES = [
+  "assert",
+  "ifCondition"
+];
+var VISUAL_REGRESSION_STEP_TYPES = [
+  "elementVisualRegression",
+  "pageVisualRegression"
+];
+var isAssertionStepType = (stepType) => typeof stepType === "string" && ASSERTION_STEP_TYPES.includes(stepType);
+var isVisualRegressionStepType = (stepType) => typeof stepType === "string" && VISUAL_REGRESSION_STEP_TYPES.includes(stepType);
+
+// ../api-schema/dist/schemas/common.js
+import { z } from "zod";
+var UuidSchema = z.string().min(1).describe("UUID");
+var DateTimeSchema = z.string().describe("ISO 8601 date-time string");
+var CursorSchema = z.string().describe("Opaque cursor returned as next_token.");
+var PageSizeSchema = z.number().int().min(1).max(100).describe("Number of results per page.");
+var StepTimingSecondsSchema = z.number().min(0).max(300).nullable().optional();
+
+// ../api-schema/dist/schemas/enums.js
+import { z as z2 } from "zod";
+var DEBUG_ARTIFACT_TYPES = [
+  "network_logs",
+  "logs",
+  "dom_snapshot"
+];
+var DebugArtifactByTypeSchema = z2.enum(DEBUG_ARTIFACT_TYPES);
+var RUN_MODES = [
+  "server",
+  "local",
+  "recording"
+];
+var RunModeSchema = z2.enum(RUN_MODES).describe("Run execution mode: server, local, recording.");
+var WAITING_CONDITION_TYPES = [
+  "documentComplete",
+  "elementIsVisible",
+  "elementIsNotCovered",
+  "elementIsNotAnimating",
+  "elementIsNotDisabled",
+  "elementHasFocus",
+  "networkIdle",
+  "pageNavigationAfterExecution",
+  "elementHasAttribute"
+];
+var WaitingConditionTypeSchema = z2.enum(WAITING_CONDITION_TYPES).describe("Waiting condition type evaluated by BugBug.");
+var StatusSchema = z2.enum([
+  "initialized",
+  "passed",
+  "failed",
+  "auto_retrying",
+  "recording",
+  "queued",
+  "running",
+  "stopped",
+  "paused",
+  "error",
+  "skipped"
+]);
+var StepTypeSchema = z2.enum([
+  "answerPrompt",
+  "assert",
+  "change",
+  "clear",
+  "click",
+  "dblClick",
+  "rightClick",
+  "closeTab",
+  "dragAndDrop",
+  "elementVisualRegression",
+  "execute",
+  "goto",
+  "goBack",
+  "goForward",
+  "hover",
+  "ifCondition",
+  "mouseDown",
+  "mouseUp",
+  "newTab",
+  "pageVisualRegression",
+  "pasteFromClipboard",
+  "reloadPage",
+  "scroll",
+  "select",
+  "setLocalVariable",
+  "switchContext",
+  "type",
+  "uploadFile"
+]).describe("Available step types: answerPrompt, assert, change, clear, click, dblClick, rightClick, closeTab, dragAndDrop, elementVisualRegression, execute, goto, goBack, goForward, hover, ifCondition, mouseDown, mouseUp, newTab, pageVisualRegression, pasteFromClipboard, reloadPage, scroll, select, setLocalVariable, switchContext, type, uploadFile.");
+var AssertionTypeSchema = z2.enum([
+  "contain",
+  "equal",
+  "greaterThan",
+  "lessThan",
+  "match",
+  "notContain",
+  "notEqual",
+  "notMatch",
+  "any"
+]).describe("Assertion operators supported by BugBug: contain, equal, greaterThan, lessThan, match, notContain, notEqual, notMatch, any.");
+var AssertionPropertySchema = z2.enum([
+  "checked",
+  "count",
+  "customJavaScript",
+  "exist",
+  "notChecked",
+  "notExist",
+  "notVisible",
+  "textContent",
+  "hasAttribute",
+  "hasNotAttribute",
+  "value",
+  "visible",
+  "pageTitle",
+  "pageShowsText",
+  "pageDoesNotShowText",
+  "pageUrlIs",
+  "downloadStarted",
+  "variableValue",
+  "clipboardValue",
+  "disabled",
+  "notDisabled"
+]).describe("Assertion properties supported by BugBug, including element state, page-level checks, downloads, variables, clipboard, and disabled state.");
+var SelectorTypeSchema = z2.enum(["XPath", "customCSS", "customXPath", ""]).nullable().describe("Selector engines or strategies supported by BugBug: XPath, customCSS, customXPath.");
+var SelectorsRelationSchema = z2.enum(["descendant", "ancestor", "sibling"]).describe("How selectors inside a group are combined: descendant, ancestor, sibling.");
+var InteractionPositionSchema = z2.enum([
+  "smart",
+  "custom",
+  "topLeft",
+  "topCenter",
+  "topRight",
+  "middleLeft",
+  "middleCenter",
+  "middleRight",
+  "bottomLeft",
+  "bottomCenter",
+  "bottomRight"
+]).describe("Element interaction position used by BugBug.");
+var DragAndDropTargetSchema = z2.enum(["coords", "element"]).describe("Drag-and-drop target mode.");
+var ScrollEdgeSchema = InteractionPositionSchema.exclude(["smart", "custom"]).nullable().describe("Element edge to scroll toward.");
+var ScrollDirectionSchema = z2.enum(["down", "up", "right", "left"]).nullable();
+var ScrollToSchema = z2.enum(["coords", "edge", "untilNextStepElementIsVisible", "elementIntoView"]).describe("Scroll target strategy.");
+var ScrollInsideSchema = z2.enum(["window", "element"]).describe("Whether to scroll inside the window or target element.");
+var SelectTypeSchema = z2.enum(["text", "index", "value"]).describe("How the option should be matched.");
+var ScreenSizeTypeSchema = z2.enum(["desktop", "mobile", "custom"]).describe("Screen size preset used when running or recording the test.");
+var TriggeredBySchema = z2.enum(["user", "api", "webhook", "scheduler", "github", "cli", "agent"]).describe("Origin that triggered the run.");
+
+// ../api-schema/dist/schemas/selectors.js
+import { z as z3 } from "zod";
+var SelectorSchema = z3.object({
+  id: UuidSchema.optional().describe("Selector UUID when persisted by the API."),
+  selector: z3.string().nullable().describe("Raw xpath or css selector expression used to find an element."),
+  type: SelectorTypeSchema.describe("Selector engine or strategy name used by BugBug."),
+  isActive: z3.boolean().describe("Whether this selector is enabled."),
+  step: UuidSchema.optional().describe("Owning step UUID when returned by the API.")
+}).passthrough();
+var SelectorsGroupSchema = z3.object({
+  id: UuidSchema.optional().describe("Selectors group UUID when persisted by the API."),
+  relation: SelectorsRelationSchema.describe("How selectors groups inside the preset are combined."),
+  selectors: z3.array(SelectorSchema).min(1, "Selectors group must contain at least one selector.").describe("Selectors included in this group. Must contain at least one selector.")
+}).passthrough();
+var SelectorsPresetSchema = z3.object({
+  id: UuidSchema.optional().describe("Selectors preset UUID when persisted by the API."),
+  isCustom: z3.boolean().describe("Whether the preset was manually customized."),
+  isActive: z3.boolean().describe("Whether the preset is enabled for the step."),
+  selectorsGroups: z3.array(SelectorsGroupSchema).min(1, "Selectors preset must contain at least one selectors group.").describe("Selector groups used to locate the target element. Must contain at least one group when provided.")
+}).passthrough();
+
+// ../api-schema/dist/schemas/steps.js
+import { z as z4 } from "zod";
+
+// ../api-schema/dist/step-error-codes.js
+var STEP_ERROR_CODES = [
+  "ELEMENT_DOES_NOT_EXIST",
+  "ELEMENT_REMOVED",
+  "SELECTOR_REQUIRED",
+  "INVALID_ELEMENT_SELECTOR",
+  "INTERACTION_POSITION_OUT_OF_VIEWPORT",
+  "FRAME_DOES_NOT_EXIST",
+  "FRAME_LOADS_TOO_LONG",
+  "WINDOW_OR_TAB_DOES_NOT_EXIST",
+  "TAB_CLOSED",
+  "WINDOW_CLOSED",
+  "WINDOW_MINIMIZED",
+  "UNEXPECTED_WINDOW_STATE_CHANGE",
+  "UNCHANGABLE_ELEMENT",
+  "TYPED_TEXT_DIFFERENT_THAN_EXPECTED",
+  "INVALID_FIELD_VALUE",
+  "INVALID_OPTION_INDEX",
+  "MISSING_OPTION_VALUE",
+  "MISSING_OPTION_TEXT",
+  "MISSING_OPTION_INDEX",
+  "SELECT_OPTION_FAILED",
+  "MULTIPLE_OPTIONS_WITH_VALUE",
+  "MISSING_GOTO_STEP",
+  "INVALID_URL",
+  "PAGE_LOADING_ERROR",
+  "ELEMENT_VISUAL_REGRESSION_FAILED",
+  "PAGE_VISUAL_REGRESSION_FAILED",
+  "SCREENSHOT_CAPTURE_ERROR",
+  "REFERENCE_SCREENSHOT_NOT_FOUND",
+  "SCREENSHOT_COMPARISON_ERROR",
+  "CODE_EXECUTION_ERROR",
+  "INVALID_EXECUTION_RESULT",
+  "VARIABLE_DOES_NOT_EXIST",
+  "VARIABLE_NESTING_LIMIT_EXCEEDED",
+  "EVENT_DISPATCHED_ON_INVALID_ELEMENT",
+  "EVENT_DISPATCH_FAILED",
+  "FAILED_WAITING_CONDITIONS",
+  "PROMPT_DOES_NOT_EXIST",
+  "UNHANDLED_PROMPT",
+  "NEXT_STEP_ELEMENT_REQUIRED",
+  "NEXT_ACTIVE_STEP_WITH_ELEMENT_REQUIRED",
+  "ASSERT_FAILED",
+  "SCROLL_FAILED",
+  "TIMEOUT",
+  "SINGLE_TEST_TIME_EXCEEDED",
+  "UNSUPPORTED_BROWSER",
+  "DEBUGGER_DETACHED",
+  "BLOCKED_BY_BROWSER_POLICY",
+  "INVALID_CUSTOM_HEADERS",
+  "INVALID_DATA_FORMAT",
+  "RUNTIME_ERROR",
+  "INTERNAL_ERROR",
+  "INITIALIZATION_ERROR",
+  "AUTHENTICATION_ERROR",
+  "STEP_RUN_INITIALIZATION_ERROR",
+  "UNRECOGNIZED_STEP_TYPE",
+  "FRAME_IS_NOT_INITIALIZED",
+  "INVALID_MOUSE_INPUT_PARAMS",
+  "FILE_DOES_NOT_EXIST",
+  "FILE_UPLOAD_ERROR",
+  "VALUE_COMPUTING_ERROR",
+  "WEBSOCKET_ERROR",
+  "WEBSOCKET_SETUP_ERROR",
+  "REQUEST_ERROR",
+  "LOGS_UPLOAD_TIMEOUT",
+  "EXTENSION_DOES_NOT_RESPONSE",
+  "EXTENSION_DISCONNECTED",
+  "EXTENSION_DISCONNECTED_ERROR",
+  "TAKING_SCREENSHOT_TIMEOUT",
+  "MISSING_STEP_SCREENSHOT",
+  "MISSING_ELEMENT_SCREENSHOT"
+];
+
+// ../api-schema/dist/schemas/steps.js
+var WaitingConditionSchema = z4.object({
+  type: WaitingConditionTypeSchema,
+  expected: z4.string().nullable().describe("Expected value for the waiting condition, if any.")
+}).passthrough();
+var StepErrorCodeSchema = z4.enum(STEP_ERROR_CODES);
+var StepSourceSchema = z4.enum(["api", "agent"]).describe("Creation source for public API step writes.");
+var StepBaseSchema = z4.object({
+  id: UuidSchema.describe("Step UUID. Omit when creating a new step."),
+  atIndex: z4.number().nullable().describe("Insert position within the group."),
+  name: z4.string().nullable().optional().describe("Human-readable step name."),
+  blockId: UuidSchema.nullable().optional().describe("Id of step representing a block start eg. ifCondition step"),
+  groupId: UuidSchema.nullable().describe("Owning group UUID for the step."),
+  originGroupId: UuidSchema.optional().describe("Original group UUID from the API response. Omit when creating a new step."),
+  notes: z4.string().nullable().optional().describe("Optional step notes."),
+  isActive: z4.boolean().optional().describe("Whether the step is enabled."),
+  runTimeout: StepTimingSecondsSchema.describe("Maximum execution time in seconds before the step times out. If not defined, default project settings will be used."),
+  sleep: StepTimingSecondsSchema.describe("Delay in seconds before running the step. If not defined, default project settings will be used."),
+  continueOnFailure: z4.boolean().optional().describe("Whether the run should continue after a fail."),
+  waitingConditions: z4.array(WaitingConditionSchema.extend({
+    isActive: z4.boolean(),
+    isOverridden: z4.boolean().default(true).describe("Required when overriding default waiting condition config."),
+    timeout: z4.number().nullable().optional().default(null).describe("Custom waiting condition timeout")
+  })).optional().describe("Optional waiting conditions evaluated around the step."),
+  selectorsPresets: z4.array(SelectorsPresetSchema).optional().describe("Element selector presets required by element-targeting steps variants."),
+  source: StepSourceSchema.optional().describe("Optional creation source. Direct API and SDK clients should use api; agent/MCP clients should use agent.")
+}).passthrough();
+var omitStepRuntimeFields = (schema) => schema.omit({
+  id: true,
+  originGroupId: true
+});
+var toStepPatchSchema = (schema) => {
+  const createSchema = omitStepRuntimeFields(schema).omit({
+    source: true
+  });
+  return createSchema.partial().extend({
+    type: createSchema.shape.type
+  });
+};
+var asNonEmptyDiscriminatedOptions = (schemas) => {
+  const [first, ...rest] = schemas;
+  if (!first) {
+    throw new Error("Expected at least one step schema");
+  }
+  return [first, ...rest];
+};
+var AnswerPromptStepSchema = StepBaseSchema.extend({
+  type: z4.literal("answerPrompt").describe("Respond to a browser prompt dialog."),
+  value: z4.string().describe("Prompt response value.")
+});
+var AssertStepSchema = StepBaseSchema.extend({
+  type: z4.literal("assert").describe("Create an assertion step."),
+  selectorsPresets: z4.array(SelectorsPresetSchema).describe("Target selectors used by the element-related assertion."),
+  assertionProperty: AssertionPropertySchema.describe("Assertion property to inspect, for example text or value."),
+  assertionType: AssertionTypeSchema.describe("Assertion operator used by BugBug."),
+  assertionExpectedValue: z4.string().nullable().describe("Expected assertion value when applicable."),
+  assertionJavaScript: z4.string().nullable().describe("Custom JavaScript used by script-based assertions."),
+  assertionVariableName: z4.string().nullable().describe("Variable name used by variable-based assertions.")
+});
+var PasteFromClipboardStepSchema = StepBaseSchema.extend({
+  type: z4.literal("pasteFromClipboard").describe("Paste clipboard contents into the active element.")
+});
+var ChangeStepSchema = StepBaseSchema.extend({
+  type: z4.literal("change").describe("Change the value of the targeted element."),
+  value: z4.string().describe("Value to set on the target element.")
+});
+var ClearStepSchema = StepBaseSchema.extend({
+  type: z4.literal("clear").describe("Clear the value of the targeted element.")
+});
+var ClickStepShape = {
+  interactionPosition: InteractionPositionSchema.describe("Click position relative to the target element."),
+  selectorsPresets: z4.array(SelectorsPresetSchema).describe("Target selectors used to locate the element.")
+};
+var ClickStepSchema = StepBaseSchema.extend({
+  type: z4.literal("click").describe("Perform a click on the targeted element."),
+  ...ClickStepShape
+});
+var DoubleClickStepSchema = StepBaseSchema.extend({
+  type: z4.literal("dblClick").describe("Perform a double click on the targeted element."),
+  ...ClickStepShape
+});
+var RightClickStepSchema = StepBaseSchema.extend({
+  type: z4.literal("rightClick").describe("Perform a right click on the targeted element."),
+  ...ClickStepShape
+});
+var CloseTabStepSchema = StepBaseSchema.extend({
+  type: z4.literal("closeTab").describe("Close the current browser tab.")
+});
+var DragAndDropStepSchema = StepBaseSchema.extend({
+  type: z4.literal("dragAndDrop").describe("Drag from one element and drop onto another."),
+  dndDragOn: DragAndDropTargetSchema.describe("Whether dragging starts from coordinates or an element."),
+  interactionPosition: InteractionPositionSchema.describe("Drag start position relative to the target element."),
+  dndDragX: z4.number().nullable().optional().describe("Drag start X coordinate when dragging by coordinates."),
+  dndDragY: z4.number().nullable().optional().describe("Drag start Y coordinate when dragging by coordinates."),
+  dndDropOn: DragAndDropTargetSchema.describe("Whether dropping targets coordinates or an element."),
+  dndDropInteractionPosition: InteractionPositionSchema.describe("Drop position relative to the target element."),
+  dndDropX: z4.number().nullable().optional().describe("Drop X coordinate when dropping by coordinates."),
+  dndDropY: z4.number().nullable().optional().describe("Drop Y coordinate when dropping by coordinates."),
+  dndDropSelectorsPresets: z4.array(SelectorsPresetSchema).optional().describe("Target selectors used to locate the drop element.")
+});
+var ExecuteStepSchema = StepBaseSchema.extend({
+  type: z4.literal("execute").describe("Execute custom JavaScript in the page context."),
+  code: z4.string().describe("JavaScript source code to execute.")
+});
+var GotoStepSchema = StepBaseSchema.extend({
+  type: z4.literal("goto").describe("Navigate the browser to a URL."),
+  url: z4.string().describe("Absolute URL to open.")
+});
+var HoverStepSchema = StepBaseSchema.extend({
+  type: z4.literal("hover").describe("Hover over the targeted element."),
+  interactionPosition: InteractionPositionSchema.describe("Hover position relative to the target element."),
+  selectorsPresets: z4.array(SelectorsPresetSchema).describe("Target selectors used to locate the element.")
+});
+var MouseDownStepSchema = StepBaseSchema.extend({
+  type: z4.literal("mouseDown").describe("Press the mouse button on the targeted element."),
+  interactionPosition: InteractionPositionSchema.describe("Mouse-down position relative to the target element."),
+  selectorsPresets: z4.array(SelectorsPresetSchema).describe("Target selectors used to locate the element.")
+});
+var MouseUpStepSchema = StepBaseSchema.extend({
+  type: z4.literal("mouseUp").describe("Release the mouse button on the targeted element."),
+  interactionPosition: InteractionPositionSchema.describe("Mouse-up position relative to the target element."),
+  selectorsPresets: z4.array(SelectorsPresetSchema).describe("Target selectors used to locate the element.")
+});
+var NewTabStepSchema = StepBaseSchema.extend({
+  type: z4.literal("newTab").describe("Open a new browser tab."),
+  url: z4.string().nullable().optional().describe("URL to open in the new tab."),
+  username: z4.string().nullable().optional().describe("Optional username for basic authentication."),
+  password: z4.string().nullable().optional().describe("Optional password for basic authentication.")
+});
+var ReloadPageStepSchema = StepBaseSchema.extend({
+  type: z4.literal("reloadPage").describe("Reload the current page.")
+});
+var ScrollStepSchema = StepBaseSchema.extend({
+  type: z4.literal("scroll").describe("Scroll the page or target element."),
+  scrollX: z4.number().nullable().optional().describe("Horizontal scroll coordinate."),
+  scrollY: z4.number().nullable().optional().describe("Vertical scroll coordinate."),
+  scrollEdge: ScrollEdgeSchema.optional(),
+  scrollDirection: ScrollDirectionSchema.optional().describe("Scroll direction."),
+  scrollTo: ScrollToSchema,
+  scrollInside: ScrollInsideSchema
+});
+var SelectStepSchema = StepBaseSchema.extend({
+  type: z4.literal("select").describe("Select an option in the targeted select element."),
+  value: z4.string().describe("Option value or label to select."),
+  selectType: SelectTypeSchema,
+  selectIsMultiple: z4.boolean().describe("Whether the target select allows multiple values.")
+});
+var SetLocalVariableStepSchema = StepBaseSchema.extend({
+  type: z4.literal("setLocalVariable").describe("Store a value in a local BugBug variable."),
+  value: z4.string().optional().describe("Literal value to store when using the value source."),
+  code: z4.string().nullable().optional().describe("JavaScript source used when evaluating a variable value."),
+  localVariableName: z4.string().describe("Variable name to assign."),
+  localVariableSource: z4.enum(["element", "value", "evaluate"]).describe("Source used to populate the variable.")
+});
+var SwitchContextStepSchema = StepBaseSchema.extend({
+  type: z4.literal("switchContext").describe("Switch execution context to another browser tab."),
+  tabNo: z4.number().describe("Tab index to activate.")
+});
+var TypeStepSchema = StepBaseSchema.extend({
+  type: z4.literal("type").describe("Type text into the targeted element."),
+  value: z4.string().describe("Text to type.")
+});
+var UploadStepSchema = StepBaseSchema.extend({
+  type: z4.literal("uploadFile").describe("Upload a project artifact into the targeted file input."),
+  projectArtifactId: UuidSchema.describe("Project artifact UUID to upload.")
+});
+var GoBackStepSchema = StepBaseSchema.extend({
+  type: z4.literal("goBack").describe("Navigate the browser back in history.")
+});
+var GoForwardStepSchema = StepBaseSchema.extend({
+  type: z4.literal("goForward").describe("Navigate the browser forward in history.")
+});
+var IfConditionStepSchema = StepBaseSchema.extend({
+  type: z4.literal("ifCondition").describe("Branch execution based on an assertion condition."),
+  selectorsPresets: z4.array(SelectorsPresetSchema).optional().describe("Target selectors used to locate the element for the condition."),
+  assertionProperty: AssertionPropertySchema.describe("Assertion property to inspect for the branch condition."),
+  assertionType: AssertionTypeSchema.describe("Assertion operator used to evaluate the branch condition."),
+  assertionExpectedValue: z4.string().nullable().describe("Expected assertion value when applicable."),
+  assertionJavaScript: z4.string().nullable().describe("Custom JavaScript used by script-based conditions."),
+  assertionVariableName: z4.string().nullable().describe("Variable name used by variable-based conditions.")
+});
+var ElementVisualRegressionStepSchema = StepBaseSchema.extend({
+  type: z4.literal("elementVisualRegression").describe("Perform a visual regression check on a targeted element."),
+  selectorsPresets: z4.array(SelectorsPresetSchema).describe("Target selectors used to locate the element for comparison."),
+  visualRegressionMaxDiff: z4.number().nullable().optional().describe("Maximum allowed pixel difference percentage (0\u2013100).")
+});
+var PageVisualRegressionStepSchema = StepBaseSchema.extend({
+  type: z4.literal("pageVisualRegression").describe("Perform a visual regression check on the full page."),
+  visualRegressionMaxDiff: z4.number().nullable().optional().describe("Maximum allowed pixel difference percentage (0\u2013100).")
+});
+var allStepsSchemas = [
+  AnswerPromptStepSchema,
+  AssertStepSchema,
+  PasteFromClipboardStepSchema,
+  ChangeStepSchema,
+  ClearStepSchema,
+  ClickStepSchema,
+  DoubleClickStepSchema,
+  RightClickStepSchema,
+  CloseTabStepSchema,
+  DragAndDropStepSchema,
+  ElementVisualRegressionStepSchema,
+  ExecuteStepSchema,
+  GotoStepSchema,
+  GoBackStepSchema,
+  GoForwardStepSchema,
+  HoverStepSchema,
+  IfConditionStepSchema,
+  MouseDownStepSchema,
+  MouseUpStepSchema,
+  NewTabStepSchema,
+  PageVisualRegressionStepSchema,
+  ReloadPageStepSchema,
+  ScrollStepSchema,
+  SelectStepSchema,
+  SetLocalVariableStepSchema,
+  SwitchContextStepSchema,
+  TypeStepSchema,
+  UploadStepSchema
+];
+var StepSchema = z4.discriminatedUnion("type", allStepsSchemas);
+var CREATE_STEP_SCHEMA_OPTIONS = asNonEmptyDiscriminatedOptions(allStepsSchemas.map((schema) => omitStepRuntimeFields(schema)));
+var UPDATE_STEP_SCHEMA_OPTIONS = asNonEmptyDiscriminatedOptions(allStepsSchemas.map((schema) => toStepPatchSchema(schema)));
+var StepCreateSchema = z4.discriminatedUnion("type", CREATE_STEP_SCHEMA_OPTIONS);
+var StepUpdateSchema = z4.discriminatedUnion("type", UPDATE_STEP_SCHEMA_OPTIONS);
+var StepRunSchema = z4.object({
+  id: UuidSchema.describe("Step run UUID."),
+  stepId: UuidSchema.nullable().optional().describe("Original step UUID associated with this run, if available."),
+  type: z4.string().optional().describe("Executed step type."),
+  status: StatusSchema.optional().describe("Execution status of the step run."),
+  screenshotUrl: z4.string().optional().describe("Screenshot URL captured for this step run, when available."),
+  errorCode: StepErrorCodeSchema.nullable().optional().describe("Structured BugBug error code for the failed step run, if any."),
+  error: z4.string().nullable().optional().describe("Human-readable error message for the step run, if any."),
+  duration: z4.string().nullable().optional().describe("Execution duration reported by the API."),
+  waitingConditions: z4.array(WaitingConditionSchema.extend({
+    isSuccess: z4.boolean().describe("Whether the condition passed."),
+    isSoftSuccess: z4.boolean().optional().describe("Whether the condition passed softly with warnings."),
+    isIgnored: z4.boolean().optional().describe("Whether the condition result is ignored."),
+    current: z4.string().nullable().optional().describe("Observed value for the waiting condition, if any.")
+  })).describe("Waiting conditions evaluated during the step run.")
+}).passthrough();
+
+// ../api-schema/dist/schemas/tests.js
+import { z as z6 } from "zod";
+
+// ../api-schema/dist/schemas/_paginated.js
+import { z as z5 } from "zod";
+var makePaginatedSchema = (itemSchema) => z5.object({
+  count: z5.number().optional().describe("Total number of items matching the query."),
+  nextToken: z5.string().nullable().optional().describe("Opaque cursor token for the next page, if one exists."),
+  results: z5.array(itemSchema).describe("Items returned for the current page.")
+});
+
+// ../api-schema/dist/schemas/tests.js
+var TestSchema = z6.object({
+  id: UuidSchema.describe("Test UUID."),
+  name: z6.string().optional().describe("Test name."),
+  groups: z6.string().describe("Serialized group structure returned by the API."),
+  notes: z6.string().nullable().describe("Optional test notes."),
+  screenSizeType: ScreenSizeTypeSchema,
+  webappUrl: z6.string().describe("BugBug web app URL for the test details page.")
+}).passthrough();
+var TestListItemSchema = z6.object({
+  id: UuidSchema.describe("Test UUID."),
+  name: z6.string().optional().describe("Test name.")
+}).passthrough();
+var TestsListSchema = makePaginatedSchema(TestListItemSchema);
+
+// ../api-schema/dist/schemas/suites.js
+import { z as z7 } from "zod";
+var SuiteSchema = z7.object({
+  id: UuidSchema.describe("Suite UUID."),
+  name: z7.string().nullable().describe("Suite name."),
+  testsCount: z7.number().describe("Number of tests included in the suite."),
+  tests: z7.array(z7.record(z7.unknown())).describe("Raw test entries included in the suite response."),
+  autoAddNewTests: z7.boolean().describe("Whether newly created tests are automatically added to the suite."),
+  autoRetry: z7.number().describe("Number of automatic retries configured for failed tests in the suite."),
+  notes: z7.string().nullable().describe("Optional suite notes."),
+  runInParallel: z7.boolean().describe("Whether suite tests run in parallel."),
+  runProfileId: z7.string().nullable().describe("Run profile UUID used by default for the suite, if configured.")
+}).passthrough();
+var SuiteDetailsSchema = SuiteSchema.extend({
+  webappUrl: z7.string().describe("BugBug web app URL for the suite details page.")
+});
+var SuitesListSchema = makePaginatedSchema(SuiteSchema);
+
+// ../api-schema/dist/schemas/profiles.js
+import { z as z8 } from "zod";
+var ProfileSchema = z8.object({
+  id: UuidSchema.describe("Run profile UUID."),
+  name: z8.string().describe("Run profile name."),
+  isDefault: z8.boolean().optional().describe("Whether this is the default run profile.")
+}).passthrough();
+var ProfilesListSchema = makePaginatedSchema(ProfileSchema);
+
+// ../api-schema/dist/schemas/projects.js
+import { z as z9 } from "zod";
+var ProjectSchema = z9.object({
+  id: UuidSchema.describe("Project UUID."),
+  name: z9.string().nullable().describe("Project name."),
+  homepageUrl: z9.string().nullable().describe("Project homepage URL."),
+  organizationId: z9.string().nullable().describe("Owning organization UUID."),
+  organizationName: z9.string().describe("Owning organization name.")
+}).passthrough();
+var ProjectsListSchema = makePaginatedSchema(ProjectSchema);
+
+// ../api-schema/dist/schemas/runs.js
+import { z as z10 } from "zod";
+var RunResultSchema = z10.object({
+  id: UuidSchema.describe("Run UUID."),
+  status: StatusSchema.describe("Current status of the run."),
+  webappUrl: z10.string().describe("BugBug web app URL for the run details page."),
+  modified: DateTimeSchema.optional().describe("Last modification timestamp reported by the API.")
+}).passthrough();
+var StepRunScreenshotSchema = z10.object({
+  id: UuidSchema.describe("Step run UUID."),
+  stepId: UuidSchema.nullable().describe("Original step UUID associated with the screenshot, if available."),
+  screenshotUrl: z10.string().describe("Screenshot URL for the step run.")
+}).passthrough();
+var TestRunSchema = z10.object({
+  id: UuidSchema.describe("Test run UUID."),
+  name: z10.string().min(1).describe("Test run name."),
+  queued: DateTimeSchema.nullable().describe("Queue timestamp, if the run waited before execution."),
+  status: StatusSchema.describe("Current status of the test run."),
+  sequence: z10.number().nullable().describe("Sequence number assigned by BugBug, if available."),
+  webappUrl: z10.string().describe("BugBug web app URL for the test run."),
+  errorCode: StepErrorCodeSchema.nullable().describe("Structured BugBug error code for the test run, if any."),
+  duration: z10.string().nullable().describe("Execution duration reported by the API."),
+  started: DateTimeSchema.nullable().describe("Run start timestamp, if available."),
+  ended: DateTimeSchema.nullable().describe("Run end timestamp, if available."),
+  stepsRuns: z10.string().describe("API reference or serialized value containing the step runs payload."),
+  runProfileId: UuidSchema.nullable().describe("Run profile UUID used for this execution, if available."),
+  testId: UuidSchema.nullable().describe("Original test UUID associated with this run, if available."),
+  suiteRunId: UuidSchema.nullable().describe("Parent suite run UUID when the test run belongs to a suite run."),
+  triggeredBy: TriggeredBySchema
+}).passthrough();
+var TestRunStateSchema = z10.object({
+  id: UuidSchema.describe("Test run UUID."),
+  modified: DateTimeSchema.describe("Last modification timestamp reported by the API."),
+  status: StatusSchema.optional().describe("Current status of the test run."),
+  webappUrl: z10.string().describe("BugBug web app URL for the test run."),
+  duration: z10.string().nullable().optional().describe("Execution duration reported by the API."),
+  started: DateTimeSchema.nullable().optional().describe("Run start timestamp, if available."),
+  ended: DateTimeSchema.nullable().optional().describe("Run end timestamp, if available.")
+}).passthrough();
+var TestRunScreenshotsSchema = z10.object({
+  id: UuidSchema.describe("Test run UUID."),
+  stepsRuns: z10.array(StepRunScreenshotSchema).describe("Screenshots captured for step runs within the test run.")
+}).passthrough();
+var SuiteRunSchema = z10.object({
+  id: UuidSchema.describe("Suite run UUID."),
+  name: z10.string().min(1).describe("Suite run name."),
+  queued: DateTimeSchema.nullable().describe("Queue timestamp, if the suite run waited before execution."),
+  status: StatusSchema.describe("Current status of the suite run."),
+  sequence: z10.number().nullable().describe("Sequence number assigned by BugBug, if available."),
+  webappUrl: z10.string().describe("BugBug web app URL for the suite run."),
+  errorCode: StepErrorCodeSchema.nullable().describe("Structured BugBug error code for the suite run, if any."),
+  duration: z10.string().nullable().describe("Execution duration reported by the API."),
+  started: DateTimeSchema.nullable().describe("Run start timestamp, if available."),
+  ended: DateTimeSchema.nullable().describe("Run end timestamp, if available."),
+  profileId: UuidSchema.describe("Run profile UUID used for the suite run."),
+  profileName: z10.string().describe("Run profile name used for the suite run."),
+  testRuns: z10.array(TestRunSchema).describe("Test runs included in the suite run."),
+  triggeredBy: TriggeredBySchema
+}).passthrough();
+var SuiteRunStateSchema = z10.object({
+  id: UuidSchema.describe("Suite run UUID."),
+  modified: DateTimeSchema.describe("Last modification timestamp reported by the API."),
+  status: StatusSchema.describe("Current status of the suite run."),
+  webappUrl: z10.string().describe("BugBug web app URL for the suite run."),
+  duration: z10.string().nullable().optional().describe("Execution duration reported by the API."),
+  started: DateTimeSchema.nullable().optional().describe("Run start timestamp, if available."),
+  ended: DateTimeSchema.nullable().optional().describe("Run end timestamp, if available.")
+}).passthrough();
+var SuiteRunScreenshotsSchema = z10.object({
+  id: UuidSchema.describe("Suite run UUID."),
+  testsRuns: z10.array(TestRunScreenshotsSchema).describe("Screenshot collections grouped by test run within the suite run.")
+}).passthrough();
+var RunVariableSchema = z10.object({
+  key: z10.string().describe("Variable name."),
+  value: z10.string().nullable().optional().describe("Variable value.")
+});
+
+// src/index.ts
+function createBugBug(config) {
+  return new BugBugSDK(config);
+}
+export {
+  ASSERTION_STEP_TYPES,
+  AuthModule,
+  AuthenticationError,
+  AuthorizationError,
+  BUGBUG_CLI_OAUTH_CLIENT_ID,
+  BUGBUG_MCP_OAUTH_CLIENT_ID,
+  BUGBUG_OAUTH_CODE_CHALLENGE_METHOD,
+  BugBugError,
+  BugBugSDK,
+  CancellationError,
+  ComponentsModule,
+  ConfigModule,
+  ConfigurationError,
+  CursorSchema,
+  DebugArtifactByTypeSchema,
+  GroupsModule,
+  HttpError,
+  InternalServerError,
+  MissingProjectIdError,
+  NetworkError,
+  NotFoundError,
+  PageSizeSchema,
+  ProfilesModule,
+  ProjectArtifactsModule,
+  ProjectModule,
+  ProjectsModule,
+  RUN_MODES,
+  RateLimitError,
+  RunModeSchema,
+  SDK_ERROR_CODES,
+  STEP_ERROR_CODES,
+  ScreenSizeTypeSchema,
+  SelectorsPresetSchema,
+  ServiceUnavailableError,
+  StatusSchema,
+  StepCreateSchema,
+  StepErrorCodeSchema,
+  StepRunsModule,
+  StepSchema,
+  StepTypeSchema,
+  StepUpdateSchema,
+  StepsModule,
+  SuitesModule,
+  TestsModule,
+  TimeoutError,
+  UnexpectedResponseError,
+  UuidSchema,
+  VISUAL_REGRESSION_RESOLUTION_ACTIONS,
+  VISUAL_REGRESSION_RESOLUTION_TYPE_BY_ACTION,
+  VISUAL_REGRESSION_STEP_TYPES,
+  ValidationError,
+  VariablesModule,
+  VisualRegressionModule,
+  createBugBug,
+  createOAuthCodeChallenge,
+  createOAuthCodeVerifier,
+  createOAuthState,
+  isAssertionStepType,
+  isAuthenticationError,
+  isAuthorizationError,
+  isBugBugError,
+  isCancellationError,
+  isCompletedStatus,
+  isConfigurationError,
+  isEditingStatus,
+  isFailedStatus,
+  isHttpError,
+  isInternalServerError,
+  isMissingProjectIdError,
+  isNetworkError,
+  isNotFoundError,
+  isPassedStatus,
+  isRateLimitError,
+  isRunningStatus,
+  isServiceUnavailableError,
+  isTimeoutError,
+  isUnexpectedResponseError,
+  isValidationError,
+  isVisualRegressionStepType
+};