@gearbox-protocol/sdk 18.2.0-next.5 → 18.2.0-next.7

package/dist/types/testnets/TestnetsAPI.d.ts

@@ -0,0 +1,108 @@
+import { ILogger } from "../onchain/types/logger.js";
+import { CreateTestnetRequest, Testnet, TestnetFiles, TestnetStatus } from "./types.js";
+//#region src/testnets/TestnetsAPI.d.ts
+/**
+ * Options of a {@link TestnetsAPI}.
+ **/
+export interface TestnetsAPIOptions {
+  /**
+   * Base URL of anvil-manager.
+   *
+   * @defaultValue `"https://anvil.gearbox.foundation"`
+   **/
+  baseUrl?: string;
+  /**
+   * API key sent as a bearer token with every request. Without it the private
+   * routes (create, kill) answer 401, which surfaces as a
+   * {@link TestnetStatusError}.
+   **/
+  apiKey?: string;
+  /**
+   * Timeout of one request, in milliseconds.
+   *
+   * @defaultValue `30_000`
+   **/
+  timeout?: number;
+  logger?: ILogger;
+}
+/**
+ * Options of {@link TestnetsAPI.waitUntilReady}.
+ **/
+export interface WaitUntilReadyOptions {
+  /**
+   * How long to wait for the testnet to become ready, in milliseconds.
+   *
+   * @defaultValue `600_000` (10 minutes)
+   **/
+  timeout?: number;
+  /**
+   * Pause between two status polls, in milliseconds.
+   *
+   * @defaultValue `5_000`
+   **/
+  interval?: number;
+}
+/**
+ * Client for anvil-manager, which runs the anvil forks Gearbox calls
+ * testnets. It manages non-persistent testnets only, addressed by their
+ * execution id.
+ *
+ * ```ts
+ * const testnets = new TestnetsAPI({ apiKey: process.env.ANVIL_MANAGER_API_KEY });
+ * const { executionId } = await testnets.create({ network: "Mainnet", timeout: "2h" });
+ * const status = await testnets.waitUntilReady(executionId);
+ * // ... use status.rpcUrl ...
+ * await testnets.kill(executionId);
+ * ```
+ *
+ * Every method throws a {@link TestnetsError} subclass when it fails, except
+ * when a response body is not JSON: then it rejects with the error of
+ * `response.json()`.
+ **/
+export declare class TestnetsAPI {
+  #private;
+  protected readonly logger?: ILogger;
+  constructor(options?: TestnetsAPIOptions);
+  /**
+   * Base URL every request of this client is sent to.
+   **/
+  get baseUrl(): string;
+  /**
+   * Every testnet anvil-manager knows of, persistent ones included.
+   **/
+  list(): Promise<Testnet[]>;
+  /**
+   * Status of one testnet.
+   *
+   * @param id - Execution id of the testnet.
+   * @throws {@link TestnetNotFoundError} when there is no such testnet.
+   **/
+  get(id: string): Promise<TestnetStatus>;
+  /**
+   * Starts a testnet. It answers as soon as the testnet is created, long
+   * before it is {@link TestnetStatus.ready}.
+   *
+   * @param files - Saved in the testnet's shared dir, where scripts and tasks
+   * can read them.
+   **/
+  create(request: CreateTestnetRequest, files?: TestnetFiles): Promise<TestnetStatus>;
+  /**
+   * Stops a testnet. Stopping one that is already stopped succeeds.
+   *
+   * @param id - Execution id of the testnet.
+   * @throws {@link TestnetNotFoundError} when there is no such testnet.
+   * @throws {@link TestnetStatusError} with status 400 when the testnet is
+   * persistent.
+   **/
+  kill(id: string): Promise<void>;
+  /**
+   * Polls a testnet's status until it is {@link TestnetStatus.ready}.
+   *
+   * @param id - Execution id of the testnet.
+   * @returns The first status that is ready.
+   * @throws {@link TestnetWaitTimeoutError} when the testnet is not ready in
+   * time. Any error of a poll is thrown as is, without retrying.
+   **/
+  waitUntilReady(id: string, options?: WaitUntilReadyOptions): Promise<TestnetStatus>;
+}
+//#endregion

package/dist/types/testnets/errors/TestnetNotFoundError.d.ts

@@ -0,0 +1,12 @@
+import { TestnetStatusError } from "./TestnetStatusError.js";
+//#region src/testnets/errors/TestnetNotFoundError.d.ts
+/**
+ * Thrown when anvil-manager answered 404: there is no testnet with that
+ * execution id.
+ **/
+export declare class TestnetNotFoundError extends TestnetStatusError {
+  name: string;
+  readonly status: 404;
+  constructor(url: string, details?: string);
+}
+//#endregion

package/dist/types/testnets/errors/TestnetRequestFailedError.d.ts

@@ -0,0 +1,11 @@
+import { TestnetsError } from "./TestnetsError.js";
+//#region src/testnets/errors/TestnetRequestFailedError.d.ts
+/**
+ * Thrown when a request to anvil-manager never completed: the network was
+ * down, or it took longer than the client's timeout.
+ **/
+export declare class TestnetRequestFailedError extends TestnetsError {
+  name: string;
+  constructor(url: string, cause: unknown);
+}
+//#endregion

package/dist/types/testnets/errors/TestnetStatusError.d.ts

@@ -0,0 +1,15 @@
+import { TestnetsError } from "./TestnetsError.js";
+//#region src/testnets/errors/TestnetStatusError.d.ts
+/**
+ * Thrown when anvil-manager answered with a status outside the 2xx range. What
+ * it said about it, when it said anything, is the `details` of the error.
+ **/
+export declare class TestnetStatusError extends TestnetsError {
+  name: string;
+  /**
+   * Status anvil-manager answered with.
+   **/
+  readonly status: number;
+  constructor(url: string, status: number, details?: string);
+}
+//#endregion

package/dist/types/testnets/errors/TestnetValidationError.d.ts

@@ -0,0 +1,16 @@
+import { TestnetsError } from "./TestnetsError.js";
+import { z } from "zod/v4";
+//#region src/testnets/errors/TestnetValidationError.d.ts
+/**
+ * Thrown when anvil-manager answered, but with a payload the testnet schemas
+ * do not describe, i.e. the two are of different versions.
+ **/
+export declare class TestnetValidationError extends TestnetsError {
+  name: string;
+  /**
+   * The zod failure itself, e.g. for `z.treeifyError(error.zodError)`.
+   **/
+  readonly zodError: z.core.$ZodError;
+  constructor(url: string, zodError: z.core.$ZodError);
+}
+//#endregion

package/dist/types/testnets/errors/TestnetWaitTimeoutError.d.ts

@@ -0,0 +1,21 @@
+import { TestnetsError } from "./TestnetsError.js";
+//#region src/testnets/errors/TestnetWaitTimeoutError.d.ts
+/**
+ * Thrown when a testnet did not become ready before the wait for it ran out.
+ **/
+export declare class TestnetWaitTimeoutError extends TestnetsError {
+  name: string;
+  /**
+   * Execution id of the testnet that was waited for.
+   **/
+  readonly id: string;
+  /**
+   * How long the wait lasted, in milliseconds.
+   **/
+  readonly timeout: number;
+  /**
+   * @param url - Status URL that was polled.
+   **/
+  constructor(url: string, id: string, timeout: number);
+}
+//#endregion

package/dist/types/testnets/errors/TestnetsError.d.ts

@@ -0,0 +1,47 @@
+import { BaseError } from "viem";
+//#region src/testnets/errors/TestnetsError.d.ts
+/**
+ * What every failure of a testnet API call names, see {@link TestnetsError}.
+ **/
+export interface TestnetsErrorParams {
+  /**
+   * URL that was requested.
+   **/
+  url: string;
+  /**
+   * Status anvil-manager answered with, absent when the request never
+   * completed.
+   **/
+  status?: number;
+  /**
+   * Value that was caught. An `Error` becomes the `cause`, anything else is
+   * stringified into the details.
+   **/
+  cause?: unknown;
+  /**
+   * What anvil-manager itself said. Used only when there is no {@link cause},
+   * whose message viem reports instead.
+   **/
+  details?: string;
+  /**
+   * Extra lines reported after the URL and status.
+   **/
+  metaMessages?: string[];
+}
+/**
+ * Thrown by every testnet API call that fails. Its subclasses say how it
+ * failed; catch this one to catch all of them.
+ **/
+export declare abstract class TestnetsError extends BaseError {
+  /**
+   * URL that was requested.
+   **/
+  readonly url: string;
+  /**
+   * Status anvil-manager answered with, absent when the request never
+   * completed.
+   **/
+  readonly status?: number;
+  protected constructor(summary: string, params: TestnetsErrorParams);
+}
+//#endregion

package/dist/types/testnets/errors/index.d.ts

@@ -0,0 +1,7 @@
+import { TestnetsError, TestnetsErrorParams } from "./TestnetsError.js";
+import { TestnetStatusError } from "./TestnetStatusError.js";
+import { TestnetNotFoundError } from "./TestnetNotFoundError.js";
+import { TestnetRequestFailedError } from "./TestnetRequestFailedError.js";
+import { TestnetValidationError } from "./TestnetValidationError.js";
+import { TestnetWaitTimeoutError } from "./TestnetWaitTimeoutError.js";
+export { TestnetNotFoundError, TestnetRequestFailedError, TestnetStatusError, TestnetValidationError, TestnetWaitTimeoutError, TestnetsError, TestnetsErrorParams };

package/dist/types/testnets/index.d.ts

@@ -0,0 +1,11 @@
+import { CreateTestnetRequest, Testnet, TestnetBackendOptions, TestnetBackendState, TestnetBackendStatus, TestnetBlock, TestnetFiles, TestnetOptions, TestnetScript, TestnetScriptBlock, TestnetScriptOptions, TestnetScriptRequest, TestnetStageStatus, TestnetStatus, TestnetTask, TestnetTaskDefinition, TestnetTaskDefinitionRequest, TestnetTaskProgress } from "./types.js";
+import { TestnetsAPI, TestnetsAPIOptions, WaitUntilReadyOptions } from "./TestnetsAPI.js";
+import { TestnetsError, TestnetsErrorParams } from "./errors/TestnetsError.js";
+import { TestnetStatusError } from "./errors/TestnetStatusError.js";
+import { TestnetNotFoundError } from "./errors/TestnetNotFoundError.js";
+import { TestnetRequestFailedError } from "./errors/TestnetRequestFailedError.js";
+import { TestnetValidationError } from "./errors/TestnetValidationError.js";
+import { TestnetWaitTimeoutError } from "./errors/TestnetWaitTimeoutError.js";
+import "./errors/index.js";
+import { testnetBackendOptionsSchema, testnetBackendStateSchema, testnetBackendStatusSchema, testnetBlockSchema, testnetOptionsSchema, testnetSchema, testnetScriptBlockSchema, testnetScriptOptionsSchema, testnetScriptSchema, testnetStageStatusSchema, testnetStatusSchema, testnetTaskDefinitionSchema, testnetTaskProgressSchema, testnetTaskSchema } from "./schemas.js";
+export { CreateTestnetRequest, Testnet, TestnetBackendOptions, TestnetBackendState, TestnetBackendStatus, TestnetBlock, TestnetFiles, TestnetNotFoundError, TestnetOptions, TestnetRequestFailedError, TestnetScript, TestnetScriptBlock, TestnetScriptOptions, TestnetScriptRequest, TestnetStageStatus, TestnetStatus, TestnetStatusError, TestnetTask, TestnetTaskDefinition, TestnetTaskDefinitionRequest, TestnetTaskProgress, TestnetValidationError, TestnetWaitTimeoutError, TestnetsAPI, TestnetsAPIOptions, TestnetsError, TestnetsErrorParams, WaitUntilReadyOptions, testnetBackendOptionsSchema, testnetBackendStateSchema, testnetBackendStatusSchema, testnetBlockSchema, testnetOptionsSchema, testnetSchema, testnetScriptBlockSchema, testnetScriptOptionsSchema, testnetScriptSchema, testnetStageStatusSchema, testnetStatusSchema, testnetTaskDefinitionSchema, testnetTaskProgressSchema, testnetTaskSchema };