@layr-labs/ecloud-sdk 0.0.1-dev-rfc.1

package/dist/index.d.ts

@@ -0,0 +1,566 @@
+import { Address, Hex } from 'viem';
+
+/**
+ * Core types for ECloud SDK
+ */
+
+type AppId = Address;
+type logVisibility = "public" | "private" | "off";
+interface DeployAppOpts {
+    name?: string;
+    dockerfile?: string;
+    envFile?: string;
+    imageRef?: string;
+    instanceType?: string;
+    logVisibility?: logVisibility;
+}
+interface UpgradeAppOpts {
+    /** Path to Dockerfile (if building from Dockerfile) */
+    dockerfile?: string;
+    /** Image reference (registry/path:tag) - optional, will prompt if not provided */
+    imageRef?: string;
+    /** Path to .env file - optional, will use .env if exists or prompt */
+    envFile?: string;
+    /** Instance type - optional, will prompt if not provided */
+    instanceType?: string;
+    /** Log visibility setting - optional, will prompt if not provided */
+    logVisibility?: logVisibility;
+    gas?: {
+        maxFeePerGas?: bigint;
+        maxPriorityFeePerGas?: bigint;
+    };
+}
+interface LifecycleOpts {
+    gas?: {
+        maxFeePerGas?: bigint;
+        maxPriorityFeePerGas?: bigint;
+    };
+    force?: boolean;
+}
+interface AppRecord {
+    id: AppId;
+    owner: `0x${string}`;
+    image: string;
+    status: "starting" | "running" | "stopped" | "terminated";
+    createdAt: number;
+    lastUpdatedAt: number;
+}
+interface DeployOptions {
+    /** Private key for signing transactions (hex string with or without 0x prefix) - optional, will prompt if not provided */
+    privateKey?: string;
+    /** RPC URL for blockchain connection - optional, uses environment default if not provided */
+    rpcUrl?: string;
+    /** Environment name (e.g., 'sepolia', 'mainnet-alpha') - optional, defaults to 'sepolia' */
+    environment?: string;
+    /** Path to Dockerfile (if building from Dockerfile) */
+    dockerfilePath?: string;
+    /** Image reference (registry/path:tag) - optional, will prompt if not provided */
+    imageRef?: string;
+    /** Path to .env file - optional, will use .env if exists or prompt */
+    envFilePath?: string;
+    /** App name - optional, will prompt if not provided */
+    appName?: string;
+    /** Instance type - optional, will prompt if not provided */
+    instanceType?: string;
+    /** Log visibility setting - optional, will prompt if not provided */
+    logVisibility?: logVisibility;
+}
+interface DeployResult {
+    /** App ID (contract address) */
+    appID: string;
+    /** App name */
+    appName: string;
+    /** Final image reference */
+    imageRef: string;
+    /** IP address (if available) */
+    ipAddress?: string;
+    /** Transaction hash */
+    txHash: `0x${string}`;
+}
+interface EnvironmentConfig {
+    name: string;
+    build: "dev" | "prod";
+    chainID: bigint;
+    appControllerAddress: string;
+    permissionControllerAddress: string;
+    erc7702DelegatorAddress: string;
+    kmsServerURL: string;
+    userApiServerURL: string;
+    defaultRPCURL: string;
+}
+interface Release {
+    rmsRelease: {
+        artifacts: Array<{
+            digest: Uint8Array;
+            registry: string;
+        }>;
+        upgradeByTime: number;
+    };
+    publicEnv: Uint8Array;
+    encryptedEnv: Uint8Array;
+}
+interface ParsedEnvironment {
+    public: Record<string, string>;
+    private: Record<string, string>;
+}
+interface ImageDigestResult {
+    digest: Uint8Array;
+    registry: string;
+    platform: string;
+}
+interface DockerImageConfig {
+    cmd: string[];
+    entrypoint: string[];
+    user: string;
+    labels: Record<string, string>;
+}
+interface Logger {
+    debug(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+}
+/**
+ * Profile information for an app
+ */
+interface AppProfile {
+    /** App name (required) */
+    name: string;
+    /** Website URL (optional) */
+    website?: string;
+    /** Description (optional) */
+    description?: string;
+    /** X (Twitter) URL (optional) */
+    xURL?: string;
+    /** Path to image file (optional) */
+    imagePath?: string;
+}
+/**
+ * Profile response from API
+ */
+interface AppProfileResponse {
+    name: string;
+    website?: string;
+    description?: string;
+    xURL?: string;
+    imageURL?: string;
+}
+type ProductID = "compute";
+type ChainID = "ethereum-mainnet" | "ethereum-sepolia";
+type SubscriptionStatus = "incomplete" | "incomplete_expired" | "trialing" | "active" | "past_due" | "canceled" | "unpaid" | "paused" | "inactive";
+interface SubscriptionLineItem {
+    description: string;
+    price: number;
+    quantity: number;
+    currency: string;
+    subtotal: number;
+}
+interface CreateSubscriptionResponse {
+    checkoutUrl: string;
+}
+interface CheckoutCreatedResponse {
+    type: "checkout_created";
+    checkoutUrl: string;
+}
+interface AlreadyActiveResponse {
+    type: "already_active";
+    status: SubscriptionStatus;
+}
+interface PaymentIssueResponse {
+    type: "payment_issue";
+    status: SubscriptionStatus;
+    portalUrl?: string;
+}
+type SubscribeResponse = CheckoutCreatedResponse | AlreadyActiveResponse | PaymentIssueResponse;
+interface CancelSuccessResponse {
+    type: "canceled";
+}
+interface NoActiveSubscriptionResponse {
+    type: "no_active_subscription";
+    status: SubscriptionStatus;
+}
+type CancelResponse = CancelSuccessResponse | NoActiveSubscriptionResponse;
+interface ProductSubscriptionResponse {
+    productId: ProductID;
+    subscriptionStatus: SubscriptionStatus;
+    currentPeriodStart?: string;
+    currentPeriodEnd?: string;
+    lineItems?: SubscriptionLineItem[];
+    upcomingInvoiceSubtotal?: number;
+    upcomingInvoiceTotal?: number;
+    creditsApplied?: number;
+    remainingCredits?: number;
+    nextCreditExpiry?: number;
+    cancelAtPeriodEnd?: boolean;
+    canceledAt?: string;
+    portalUrl?: string;
+}
+interface SubscriptionOpts {
+    productId?: ProductID;
+}
+interface BillingEnvironmentConfig {
+    billingApiServerURL: string;
+}
+interface BillingEnvironmentConfig {
+    billingApiServerURL: string;
+}
+
+/**
+ * Create command
+ *
+ * Creates a new app project from a template
+ */
+
+interface CreateAppOpts {
+    name?: string;
+    language?: string;
+    template?: string;
+    templateVersion?: string;
+    verbose?: boolean;
+}
+/**
+ * Create a new app project from template
+ */
+declare function createApp(options: CreateAppOpts, logger?: Logger): Promise<void>;
+
+/**
+ * Logs command
+ *
+ * View app logs with optional watch mode
+ */
+
+interface LogsOptions {
+    appID?: string | Address;
+    watch?: boolean;
+    environment?: string;
+    privateKey?: string;
+    rpcUrl?: string;
+}
+/**
+ * View app logs
+ */
+declare function logs(options: LogsOptions, logger?: Logger): Promise<void>;
+
+/**
+ * Main App namespace entry point
+ */
+
+interface AppModule {
+    create: (opts: CreateAppOpts) => Promise<void>;
+    deploy: (opts: DeployAppOpts) => Promise<{
+        appID: AppId;
+        tx: `0x${string}`;
+        appName: string;
+        imageRef: string;
+        ipAddress?: string;
+    }>;
+    upgrade: (appID: AppId, opts: UpgradeAppOpts) => Promise<{
+        tx: `0x${string}`;
+        appID: string;
+        imageRef: string;
+    }>;
+    logs: (opts: LogsOptions) => Promise<void>;
+    start: (appId: AppId, opts?: LifecycleOpts) => Promise<{
+        tx: `0x${string}` | false;
+    }>;
+    stop: (appId: AppId, opts?: LifecycleOpts) => Promise<{
+        tx: `0x${string}` | false;
+    }>;
+    terminate: (appId: AppId, opts?: LifecycleOpts) => Promise<{
+        tx: `0x${string}` | false;
+    }>;
+}
+interface AppModuleConfig {
+    verbose?: boolean;
+    privateKey: `0x${string}`;
+    rpcUrl: string;
+    environment: string;
+}
+declare function createAppModule(ctx: AppModuleConfig): AppModule;
+
+/**
+ * Main Billing namespace entry point
+ */
+
+interface BillingModule {
+    subscribe: (opts?: SubscriptionOpts) => Promise<SubscribeResponse>;
+    getStatus: (opts?: SubscriptionOpts) => Promise<ProductSubscriptionResponse>;
+    cancel: (opts?: SubscriptionOpts) => Promise<CancelResponse>;
+}
+interface BillingModuleConfig {
+    verbose?: boolean;
+    privateKey: Hex;
+}
+declare function createBillingModule(config: BillingModuleConfig): BillingModule;
+
+/**
+ * Interactive prompts using @inquirer/prompts
+ */
+
+/**
+ * Prompt for Dockerfile selection
+ */
+declare function getDockerfileInteractive(dockerfilePath?: string): Promise<string>;
+/**
+ * Prompt for image reference
+ */
+declare function getImageReferenceInteractive(imageRef?: string, buildFromDockerfile?: boolean): Promise<string>;
+/**
+ * Prompt for app name
+ */
+declare function getOrPromptAppName(appName: string | undefined, environment: string, imageRef: string): Promise<string>;
+/**
+ * Prompt for environment file
+ */
+declare function getEnvFileInteractive(envFilePath?: string): Promise<string>;
+/**
+ * Prompt for instance type
+ */
+declare function getInstanceTypeInteractive(instanceType: string | undefined, defaultSKU: string, availableTypes: Array<{
+    sku: string;
+    description: string;
+}>): Promise<string>;
+/**
+ * Prompt for app ID (supports app name or address)
+ */
+interface GetAppIDOptions {
+    appID?: string | Address;
+    environment: string;
+    privateKey?: string;
+    rpcUrl?: string;
+    action?: string;
+}
+/**
+ * Prompt for app ID (supports app name or address)
+ */
+declare function getOrPromptAppID(appIDOrOptions: string | Address | GetAppIDOptions | undefined, environment?: string): Promise<Address>;
+/**
+ * Prompt for log settings
+ */
+declare function getLogSettingsInteractive(logVisibility?: "public" | "private" | "off"): Promise<{
+    logRedirect: string;
+    publicLogs: boolean;
+}>;
+declare function extractAppNameFromImage(imageRef: string): string;
+/**
+ * Confirm prompts the user to confirm an action with a yes/no question.
+ */
+declare function confirm(prompt: string): Promise<boolean>;
+/**
+ * ConfirmWithDefault prompts the user to confirm an action with a yes/no question and a default value.
+ */
+declare function confirmWithDefault(prompt: string, defaultValue?: boolean): Promise<boolean>;
+/**
+ * Prompt for RPC URL
+ * Matches Go's getRPCURL() behavior with interactive prompt
+ */
+declare function getRPCUrlInteractive(rpcUrl?: string, defaultRpcUrl?: string): Promise<string>;
+/**
+ * Prompt for environment selection
+ * Matches Go's GetEnvironmentConfig() behavior with interactive prompt
+ */
+declare function getEnvironmentInteractive(environment?: string): Promise<string>;
+/**
+ * Prompt for private key with hidden input
+ * Matches Go's output.InputHiddenString() function
+ */
+declare function getPrivateKeyInteractive(privateKey?: string): Promise<string>;
+
+/**
+ * Collect app profile information interactively
+ * If defaultName is provided, it will be used as the suggested name
+ * If allowRetry is true, user can re-enter information on rejection (deploy flow)
+ * If allowRetry is false, rejection returns an error (profile set flow)
+ */
+declare function getAppProfileInteractive(defaultName?: string, allowRetry?: boolean): Promise<AppProfile | null>;
+
+/**
+ * Environment configuration for different networks
+ */
+
+/**
+ * Get environment configuration
+ */
+declare function getEnvironmentConfig(environment: string, chainID?: bigint): EnvironmentConfig;
+/**
+ * Get available environments based on build type
+ * - dev: only "sepolia-dev"
+ * - prod: "sepolia" and "mainnet-alpha"
+ */
+declare function getAvailableEnvironments(): string[];
+/**
+ * Check if an environment is available in the current build
+ */
+declare function isEnvironmentAvailable(environment: string): boolean;
+
+/**
+ * Billing utility functions
+ */
+
+/**
+ * Check if subscription status allows deploying apps
+ */
+declare function isSubscriptionActive(status: SubscriptionStatus): boolean;
+
+/**
+ * OS Keyring Integration
+ *
+ * Provides secure storage for private keys using native OS keychains:
+ * - macOS: Keychain
+ * - Linux: Secret Service API (libsecret/gnome-keyring)
+ * - Windows: Credential Manager
+ *
+ * Uses a single key for all environments.
+ */
+interface StoredKey {
+    address: string;
+}
+interface LegacyKey {
+    environment: string;
+    address: string;
+    source: "eigenx" | "eigenx-dev";
+}
+/**
+ * Store a private key in OS keyring
+ *
+ * Note: Stores a single key for all environments.
+ * The environment parameter is kept for API compatibility but is ignored.
+ */
+declare function storePrivateKey(privateKey: string): Promise<void>;
+/**
+ * Get a private key from OS keyring
+ *
+ * Note: Returns the single stored key for all environments.
+ * The environment parameter is kept for API compatibility but is ignored.
+ */
+declare function getPrivateKey(): Promise<string | null>;
+/**
+ * Delete a private key from OS keyring
+ * Returns true if deletion was successful, false otherwise
+ *
+ * Note: Deletes the single stored key.
+ * The environment parameter is kept for API compatibility but is ignored.
+ */
+declare function deletePrivateKey(): Promise<boolean>;
+/**
+ * List all stored keys
+ * Returns an array with the single stored key (if it exists)
+ */
+declare function listStoredKeys(): Promise<StoredKey[]>;
+/**
+ * Check if a key exists
+ *
+ * Note: Checks for the single stored key.
+ * The environment parameter is kept for API compatibility but is ignored.
+ */
+declare function keyExists(): Promise<boolean>;
+/**
+ * Get legacy keys from eigenx-cli
+ * Returns an array of keys found in eigenx-cli keyring formats
+ */
+declare function getLegacyKeys(): Promise<LegacyKey[]>;
+/**
+ * Get a specific legacy private key from eigenx-cli keyring
+ */
+declare function getLegacyPrivateKey(environment: string, source: "eigenx" | "eigenx-dev"): Promise<string | null>;
+/**
+ * Delete a specific legacy private key from eigenx-cli keyring
+ * Returns true if deletion was successful, false otherwise
+ */
+declare function deleteLegacyPrivateKey(environment: string, source: "eigenx" | "eigenx-dev"): Promise<boolean>;
+/**
+ * Validate private key format
+ */
+declare function validatePrivateKey(privateKey: string): boolean;
+/**
+ * Get address from private key
+ */
+declare function getAddressFromPrivateKey(privateKey: string): string;
+
+/**
+ * Private Key Resolution
+ *
+ * Implements 3-tier priority system for private key retrieval:
+ * 1. Command-line flag (--private-key)
+ * 2. Environment variable (ECLOUD_PRIVATE_KEY)
+ * 3. OS keyring (stored via `ecloud auth login`)
+ */
+interface PrivateKeySource {
+    key: string;
+    source: string;
+}
+/**
+ * Get private key from any available source
+ *
+ * Priority order:
+ * 1. Direct parameter (from --private-key flag)
+ * 2. Environment variable (ECLOUD_PRIVATE_KEY)
+ * 3. OS keyring (single key for all environments)
+ *
+ * Returns null if no key found
+ */
+declare function getPrivateKeyWithSource(options: {
+    privateKey?: string;
+}): Promise<PrivateKeySource | null>;
+/**
+ * Get private key with source or throw error
+ */
+declare function requirePrivateKey(options: {
+    privateKey?: string;
+}): Promise<PrivateKeySource>;
+
+/**
+ * Security Utilities
+ *
+ * Provides secure display and input handling for sensitive data like private keys
+ */
+/**
+ * Display sensitive content using system pager (less/more)
+ * Returns true if content was displayed, false if user aborted
+ */
+declare function showPrivateKey(content: string): Promise<boolean>;
+/**
+ * Clear terminal screen
+ */
+declare function clearTerminal(): void;
+/**
+ * Get hidden input (password-style)
+ */
+declare function getHiddenInput(message: string): Promise<string>;
+/**
+ * Display multi-line warning for destructive operations
+ */
+declare function displayWarning(lines: string[]): void;
+
+/**
+ * Private Key Generation
+ *
+ * Generate new secp256k1 private keys for Ethereum
+ */
+interface GeneratedKey {
+    privateKey: string;
+    address: string;
+}
+/**
+ * Generate a new secp256k1 private key
+ */
+declare function generateNewPrivateKey(): GeneratedKey;
+
+/**
+ * Main SDK Client entry point
+ */
+
+type Environment = "sepolia" | "sepolia-dev" | "mainnet-alpha";
+interface ClientConfig {
+    verbose: boolean;
+    privateKey: `0x${string}`;
+    environment: Environment | string;
+    rpcUrl?: string;
+}
+interface ECloudClient {
+    app: AppModule;
+    billing: BillingModule;
+}
+declare function createECloudClient(cfg: ClientConfig): ECloudClient;
+
+export { type AlreadyActiveResponse, type AppId, type AppModuleConfig, type AppProfile, type AppProfileResponse, type AppRecord, type BillingEnvironmentConfig, type BillingModuleConfig, type CancelResponse, type CancelSuccessResponse, type ChainID, type CheckoutCreatedResponse, type ClientConfig, type CreateAppOpts, type CreateSubscriptionResponse, type DeployAppOpts, type DeployOptions, type DeployResult, type DockerImageConfig, type ECloudClient, type Environment, type EnvironmentConfig, type GeneratedKey, type GetAppIDOptions, type ImageDigestResult, type LegacyKey, type LifecycleOpts, type Logger, type LogsOptions, type NoActiveSubscriptionResponse, type ParsedEnvironment, type PaymentIssueResponse, type PrivateKeySource, type ProductID, type ProductSubscriptionResponse, type Release, type StoredKey, type SubscribeResponse, type SubscriptionLineItem, type SubscriptionOpts, type SubscriptionStatus, type UpgradeAppOpts, clearTerminal, confirm, confirmWithDefault, createApp, createAppModule, createBillingModule, createECloudClient, deleteLegacyPrivateKey, deletePrivateKey, displayWarning, extractAppNameFromImage, generateNewPrivateKey, getAddressFromPrivateKey, getAppProfileInteractive, getAvailableEnvironments, getDockerfileInteractive, getEnvFileInteractive, getEnvironmentConfig, getEnvironmentInteractive, getHiddenInput, getImageReferenceInteractive, getInstanceTypeInteractive, getLegacyKeys, getLegacyPrivateKey, getLogSettingsInteractive, getOrPromptAppID, getOrPromptAppName, getPrivateKey, getPrivateKeyInteractive, getPrivateKeyWithSource, getRPCUrlInteractive, isEnvironmentAvailable, isSubscriptionActive, keyExists, listStoredKeys, type logVisibility, logs, requirePrivateKey, showPrivateKey, storePrivateKey, validatePrivateKey };