@gearbox-protocol/cli-utils 6.16.2 → 9.0.0-beta.12

package/dist/index.d.ts

@@ -1,19 +1,436 @@
-export * from "./CensoredString.js";
-export * from "./CensoredURL.js";
-export * from "./compressedConfig.js";
-export * from "./createPinoCensor.js";
-export * from "./fetchRetry.js";
-export * from "./getFirstHttpTransportOptions.js";
-export * from "./getProviders.js";
-export * from "./notifications/index.js";
-export * from "./providers.js";
-export * from "./providers-schema.js";
-export * from "./resolveYamlFiles.js";
-export * from "./SecretsManager.js";
-export * from "./SSMManager.js";
-export * from "./schema-primitives.js";
-export * from "./sleep.js";
-export * from "./uncensorMap.js";
-export * from "./Whitelist.js";
-export * from "./whitelist-schema.js";
-export * from "./Zommand.js";
+import { HttpTransportConfig, Address } from 'viem';
+import { z } from 'zod/v4';
+import { ILogger, NetworkType } from '@gearbox-protocol/sdk';
+import { ProviderConfig } from '@gearbox-protocol/sdk/dev';
+import { Markdown } from '@vlad-yakovlev/telegram-md';
+import YAML from 'yaml';
+import { Command } from '@commander-js/extra-typings';
+import * as z4 from 'zod/v4/core';
+
+declare class CensoredString<V extends string = string> {
+    #private;
+    static transform<T extends string>(value: T | CensoredString<T>): CensoredString<T>;
+    constructor(value: V);
+    get value(): V;
+    toString(): string;
+    toJSON(): string;
+}
+
+/**
+ * Assumes that host is always visible, and the secret part is in path or query
+ */
+declare class CensoredURL {
+    #private;
+    static transform(value: string | CensoredURL): CensoredURL;
+    constructor(url: string);
+    get value(): string;
+    toString(): string;
+    toJSON(): string;
+}
+
+/**
+ * Compress a plain JS object into a base64url string
+ * suitable for env vars.
+ */
+declare function compressObject(obj: unknown): string;
+/**
+ * Decompress a base64url string back into a JS object
+ * Allows to pass template data to resolve promises/env
+ */
+declare function decompressObject<T = unknown>(value: string, templateData?: Record<string, unknown>): Promise<T>;
+
+/**
+ * Gathers known secrets from a config and returns a function that replaces each raw secret with its masked representation.
+ * Intended for pino's `hooks.streamWrite`
+ */
+declare function createPinoCensor(config: unknown): (s: string) => string;
+
+interface RetrySettings {
+    retries?: number;
+    retryInterval?: number;
+    validateResponse?: (response: Response) => void;
+}
+declare function fetchRetry(input: string | URL, init?: RequestInit & RetrySettings): Promise<Response>;
+
+declare const RpcProvider: z.ZodEnum<{
+    custom: "custom";
+    alchemy: "alchemy";
+    drpc: "drpc";
+    ankr: "ankr";
+    thirdweb: "thirdweb";
+    erpc: "erpc";
+}>;
+type RpcProvider = z.infer<typeof RpcProvider>;
+declare const ProvidersSchema: z.ZodObject<{
+    network: z.ZodEnum<{
+        Mainnet: "Mainnet";
+        Arbitrum: "Arbitrum";
+        Optimism: "Optimism";
+        Base: "Base";
+        Sonic: "Sonic";
+        MegaETH: "MegaETH";
+        Monad: "Monad";
+        Berachain: "Berachain";
+        Avalanche: "Avalanche";
+        BNB: "BNB";
+        WorldChain: "WorldChain";
+        Etherlink: "Etherlink";
+        Hemi: "Hemi";
+        Lisk: "Lisk";
+        Plasma: "Plasma";
+        Somnia: "Somnia";
+    }>;
+    jsonRpcProviders: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>]>, z.ZodArray<z.ZodPipe<z.ZodURL, z.ZodTransform<CensoredURL, string>>>>, z.ZodTransform<CensoredURL[] | undefined, CensoredURL[]>>>;
+    enabledProviders: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>]>, z.ZodArray<z.ZodEnum<{
+        custom: "custom";
+        alchemy: "alchemy";
+        drpc: "drpc";
+        ankr: "ankr";
+        thirdweb: "thirdweb";
+        erpc: "erpc";
+    }>>>>;
+    alchemyKeys: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>]>, z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<CensoredString<string>, string>>>>, z.ZodTransform<CensoredString<string>[] | undefined, CensoredString<string>[]>>>;
+    drpcKeys: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>]>, z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<CensoredString<string>, string>>>>, z.ZodTransform<CensoredString<string>[] | undefined, CensoredString<string>[]>>>;
+    ankrKeys: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>]>, z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<CensoredString<string>, string>>>>, z.ZodTransform<CensoredString<string>[] | undefined, CensoredString<string>[]>>>;
+    thirdwebKeys: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>]>, z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<CensoredString<string>, string>>>>, z.ZodTransform<CensoredString<string>[] | undefined, CensoredString<string>[]>>>;
+    erpcProjectId: z.ZodOptional<z.ZodString>;
+    erpcUrl: z.ZodDefault<z.ZodURL>;
+    jsonRpcTimeout: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+type ProvidersSchema = z.infer<typeof ProvidersSchema>;
+
+interface HttpTransportOptions {
+    url?: string | undefined;
+    config: HttpTransportConfig;
+}
+declare function getFirstHttpTransportOptions(config: ProvidersSchema): HttpTransportOptions;
+
+declare function getProviders(config: ProvidersSchema, logger?: ILogger): ProviderConfig[];
+
+declare const TelegramConfig: z.ZodObject<{
+    type: z.ZodLiteral<"telegram">;
+    token: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<CensoredString<string>, CensoredString<string>>]>, z.ZodTransform<CensoredString<string>, string | CensoredString<string>>>;
+    alertsChannel: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<CensoredString<string>, CensoredString<string>>]>, z.ZodTransform<CensoredString<string>, string | CensoredString<string>>>;
+    notificationsChannel: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<CensoredString<string>, CensoredString<string>>]>, z.ZodTransform<CensoredString<string>, string | CensoredString<string>>>>;
+    prefix: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type TelegramConfig = z.infer<typeof TelegramConfig>;
+declare const SlackConfig: z.ZodObject<{
+    type: z.ZodLiteral<"slack">;
+    webhookUrl: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<CensoredString<string>, CensoredString<string>>]>, z.ZodTransform<CensoredString<string>, string | CensoredString<string>>>;
+    alertsOnly: z.ZodOptional<z.ZodPipe<z.ZodAny, z.ZodTransform<boolean, any>>>;
+}, z.core.$strip>;
+type SlackConfig = z.infer<typeof SlackConfig>;
+declare const NotificationConfig: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"telegram">;
+    token: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<CensoredString<string>, CensoredString<string>>]>, z.ZodTransform<CensoredString<string>, string | CensoredString<string>>>;
+    alertsChannel: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<CensoredString<string>, CensoredString<string>>]>, z.ZodTransform<CensoredString<string>, string | CensoredString<string>>>;
+    notificationsChannel: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<CensoredString<string>, CensoredString<string>>]>, z.ZodTransform<CensoredString<string>, string | CensoredString<string>>>>;
+    prefix: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"slack">;
+    webhookUrl: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<CensoredString<string>, CensoredString<string>>]>, z.ZodTransform<CensoredString<string>, string | CensoredString<string>>>;
+    alertsOnly: z.ZodOptional<z.ZodPipe<z.ZodAny, z.ZodTransform<boolean, any>>>;
+}, z.core.$strip>], "type">;
+type NotificationConfig = z.infer<typeof NotificationConfig>;
+declare const SignlConfig: z.ZodObject<{
+    apiKey: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<CensoredString<string>, CensoredString<string>>]>, z.ZodTransform<CensoredString<string>, string | CensoredString<string>>>;
+    teamId: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<CensoredString<string>, CensoredString<string>>]>, z.ZodTransform<CensoredString<string>, string | CensoredString<string>>>;
+}, z.core.$strip>;
+type SignlConfig = z.infer<typeof SignlConfig>;
+
+type NotificationSeverity = "alert" | "notification";
+/**
+ * Notification that can be deduplicated
+ */
+interface IDedupableNotification {
+    /**
+     * Messages with the same dedupe key will be throttled to avoid spam
+     * If not provided, the message will not be throttled
+     */
+    dedupeKey?: string;
+    /**
+     * Function to calculate the wait time between deduped messages
+     * If not provided, the default backoff will be used
+     */
+    throttleFn?: ThrottleFn;
+    /**
+     * Plaintext notification message
+     */
+    plain: string;
+    /**
+     * Optional markdown verison of notification message
+     */
+    md?: Markdown;
+}
+/**
+ * Function to calculate the wait time between deduped messages
+ * @param prevWaitMs The wait time of the previous message, 0 for the first message
+ * @returns The wait time for the next message in milliseconds
+ */
+type ThrottleFn = (prevWaitMs: number) => number;
+/**
+ * Implement this interface for your notification classes
+ */
+interface INotification {
+    /**
+     * Function to generate the message for a recipient. Undefined means global message (gearbox notifications)
+     * This allows us to put the logic to fan out message to different recipients inside the class that implements INotificationMessage,
+     * and not to put this logic into the service that sends the notifications (you can still put it there, though)
+     *
+     * @param recipient The recipient to generate the message for, or undefined for the default/global recipient (gearbox notifications)
+     * @returns The message for the recipient, or undefined for no message
+     */
+    messageFor: (recipient?: Address) => string | IDedupableNotification | undefined;
+}
+/**
+ * A notification message, dumb strings and markdowns are treated as global notifications
+ */
+type NotificationLike = string | IDedupableNotification | INotification;
+/**
+ * Notification service with deduplication and fan out logic
+ */
+interface INotificationService {
+    /**
+     * Send an alert to Signl
+     * @param message
+     * @param dedupeKey
+     *   Messages with the same dedupe key will be throttled to avoid spam
+     *   If not provided, the message will not be throttled
+     * @returns
+     */
+    signl: (message: string, dedupeKey?: string) => void;
+    /**
+     * Sends high priority notification
+     * @param message
+     * @returns
+     */
+    alert: (message: NotificationLike) => void;
+    /**
+     * Sends low priority notification
+     * @param message
+     * @returns
+     */
+    notify: (message: NotificationLike) => void;
+    /**
+     * Register a recipient for notifications
+     * @param address The address of the recipient
+     * @param options The options for the recipient
+     */
+    registerRecipient: (address: Address, options: NotificationConfig) => void;
+}
+interface INotifier {
+    /**
+     * Sends notification
+     * @param message
+     * @returns
+     */
+    notify: (message: IDedupableNotification, severity: NotificationSeverity) => void;
+}
+
+declare function createNotifier(config: NotificationConfig, logger?: ILogger): INotifier | undefined;
+
+type SignlServiceOptions = SignlConfig & {
+    retryInterval?: number;
+    retryCount?: number;
+    throttleFn?: ThrottleFn;
+};
+
+interface NotificationsServiceOptions {
+    notifications: Array<NotificationConfig & {
+        recipient?: Address;
+    }>;
+    signl?: SignlServiceOptions;
+}
+declare class NotificationsService implements INotificationService {
+    #private;
+    constructor(options: NotificationsServiceOptions, logger?: ILogger);
+    registerRecipient(address: Address, options: NotificationConfig): void;
+    signl(message: string, dedupeKey?: string): void;
+    alert(msg: NotificationLike): void;
+    notify(msg: NotificationLike): void;
+}
+
+declare function getAlchemyUrl(network: NetworkType, apiKey: string, protocol?: "http" | "ws"): string | undefined;
+declare function getDrpcUrl(network: NetworkType, apiKey: string, protocol?: "http" | "ws"): string | undefined;
+declare function getAnkrUrl(network: NetworkType, apiKey: string, protocol?: "http" | "ws"): string | undefined;
+declare function getThirdWebUrl(network: NetworkType, apiKey: string, protocol?: "http" | "ws"): string | undefined;
+declare function getErpcKey(network: NetworkType, projectId?: string, urlBase?: string): string | undefined;
+
+type TemplateData = Record<string, unknown>;
+/**
+ * Merges yaml files, respecting .extends references.
+ * Performs env variable substitution on the config.
+ * Respects YAML anchors and aliases, and merge keys - so that they can be shared across two files
+ *
+ * x-* anchors are removed from resulting document (a-la docker compose yaml)
+ *
+ * @param file
+ * @param templateData
+ * @returns
+ */
+declare function resolveYamlFiles(file: string, templateData?: TemplateData): Promise<object>;
+/**
+ * Merges yaml documents, respecting .extends references.
+ * Optionally, performs env-style variable substitution on the config.
+ * Respects YAML anchors and aliases, and merge keys - so that they can be shared across two files
+ * Supports s3 links for file
+ *
+ * @param file
+ * @param templateData
+ * @returns
+ */
+declare function resolveYamlDoc(file: string, templateData?: TemplateData): Promise<YAML.Document>;
+/**
+ * Helper function that gets object with templated values
+ * Just because async ast already exists in yaml, but not in json reviver
+ * @param json
+ * @param templateData
+ * @returns
+ */
+declare function resolveFromObject(json: object, templateData?: TemplateData): Promise<object>;
+/**
+ * Given file and a relative file path, returns full path of the relative file
+ * Supports s3 links for base file
+ * @param file
+ * @param relativeFile
+ */
+declare function getRelativePath(baseFile: string, relativeFile: string): string;
+
+declare class SecretsManager {
+    #private;
+    secret(key: string): Promise<string>;
+    secretRaw(key: string): Promise<unknown>;
+}
+declare const secretsManagerProxy: (mgr?: SecretsManager) => Record<string, Promise<unknown>>;
+
+declare class SSMManager {
+    #private;
+    parameter(name: string): Promise<string>;
+}
+declare const ssmManagerProxy: (mgr?: SSMManager) => Record<string, Promise<unknown>>;
+
+declare const boolLike: () => z.ZodPipe<z.ZodAny, z.ZodTransform<boolean, any>>;
+declare const stringArrayLike: () => z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>]>;
+declare const optionalStringArrayLike: () => z.ZodPipe<z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>]>>, z.ZodTransform<string[] | undefined, string[] | undefined>>;
+/**
+ * Like Address from abitype/zod, but converts an address into an address that is checksum encoded.
+ */
+declare const addressLike: () => z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+declare const addressArrayLike: () => z.ZodPipe<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>]>, z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>>>;
+declare const optionalAddressArrayLike: () => z.ZodPipe<z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>]>, z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>>>>, z.ZodTransform<`0x${string}`[] | undefined, `0x${string}`[] | undefined>>;
+
+declare function sleep(ms: number): Promise<unknown>;
+
+interface IValue<V extends string = string> {
+    value: V;
+}
+declare function uncensorMap<V extends string = string>(map: Record<string, IValue<V>>): Record<string, V>;
+
+declare const WhitelistItemsSchema: z.ZodObject<{
+    network: z.ZodEnum<{
+        Mainnet: "Mainnet";
+        Arbitrum: "Arbitrum";
+        Optimism: "Optimism";
+        Base: "Base";
+        Sonic: "Sonic";
+        MegaETH: "MegaETH";
+        Monad: "Monad";
+        Berachain: "Berachain";
+        Avalanche: "Avalanche";
+        BNB: "BNB";
+        WorldChain: "WorldChain";
+        Etherlink: "Etherlink";
+        Hemi: "Hemi";
+        Lisk: "Lisk";
+        Plasma: "Plasma";
+        Somnia: "Somnia";
+    }>;
+    addresses: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>>;
+    reason: z.ZodDefault<z.ZodString>;
+    issue: z.ZodOptional<z.ZodString>;
+    expiresAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type WhitelistItemsSchema = z.infer<typeof WhitelistItemsSchema>;
+declare const WhitelistItemSchema: z.ZodObject<{
+    network: z.ZodEnum<{
+        Mainnet: "Mainnet";
+        Arbitrum: "Arbitrum";
+        Optimism: "Optimism";
+        Base: "Base";
+        Sonic: "Sonic";
+        MegaETH: "MegaETH";
+        Monad: "Monad";
+        Berachain: "Berachain";
+        Avalanche: "Avalanche";
+        BNB: "BNB";
+        WorldChain: "WorldChain";
+        Etherlink: "Etherlink";
+        Hemi: "Hemi";
+        Lisk: "Lisk";
+        Plasma: "Plasma";
+        Somnia: "Somnia";
+    }>;
+    category: z.ZodString;
+    address: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    reason: z.ZodDefault<z.ZodString>;
+    issue: z.ZodOptional<z.ZodString>;
+    contractType: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodNumber;
+    expiresAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type WhitelistItemSchema = z.infer<typeof WhitelistItemSchema>;
+
+interface WhitelistOptions {
+    url: string;
+    network: NetworkType;
+    logger?: ILogger;
+}
+/**
+ * Fetches a network-scoped whitelist from the deploy-tools backend and keeps
+ * it in memory with a 10-minute refresh interval.
+ *
+ * On fetch failure the previous in-memory copy is retained; if no successful
+ * fetch has occurred yet the whitelist is considered empty.
+ */
+declare class Whitelist {
+    #private;
+    constructor({ url, network, logger }: WhitelistOptions);
+    /**
+     * Performs the initial fetch and starts the periodic refresh timer.
+     * Failure of the initial fetch is non-fatal: the whitelist stays empty.
+     */
+    start(): Promise<void>;
+    /** Stops the refresh timer. */
+    stop(): void;
+    /**
+     * Returns the matching whitelist entry for the given address, or
+     * `undefined` if absent or expired.
+     */
+    has(address: string): WhitelistItemSchema | undefined;
+}
+
+declare const zommandRegistry: z4.$ZodRegistry<{
+    flags: string;
+    env?: string;
+    description?: string;
+}, z4.$ZodType<unknown, unknown, z4.$ZodTypeInternals<unknown, unknown>>>;
+interface ZommandOptions<T extends z4.$ZodTypes> {
+    schema: T;
+    templateData?: TemplateData;
+    /**
+     * If value is string, it's used as default value for config file
+     */
+    configFile?: boolean | string;
+    /**
+     * If true, allows to pass config zlib compressed config as --inline-config=... or INLINE_CONFIG env var
+     */
+    inlineConfig?: boolean;
+}
+declare class Zommand<T extends z4.$ZodTypes, Args extends any[] = []> extends Command<Args, z4.output<T>> {
+    #private;
+    constructor(name: string, opts: ZommandOptions<T>);
+    action(fn: (this: this, ...args: [...Args, z4.output<T>, this]) => void | Promise<void>): this;
+}
+
+export { CensoredString, CensoredURL, type HttpTransportOptions, type IDedupableNotification, type INotification, type INotificationService, type INotifier, type IValue, NotificationConfig, type NotificationLike, type NotificationSeverity, NotificationsService, type NotificationsServiceOptions, ProvidersSchema, RpcProvider, SSMManager, SecretsManager, SignlConfig, SlackConfig, TelegramConfig, type TemplateData, type ThrottleFn, Whitelist, WhitelistItemSchema, WhitelistItemsSchema, type WhitelistOptions, Zommand, type ZommandOptions, addressArrayLike, addressLike, boolLike, compressObject, createNotifier, createPinoCensor, decompressObject, fetchRetry, getAlchemyUrl, getAnkrUrl, getDrpcUrl, getErpcKey, getFirstHttpTransportOptions, getProviders, getRelativePath, getThirdWebUrl, optionalAddressArrayLike, optionalStringArrayLike, resolveFromObject, resolveYamlDoc, resolveYamlFiles, secretsManagerProxy, sleep, ssmManagerProxy, stringArrayLike, uncensorMap, zommandRegistry };