@layr-labs/ecloud-sdk 0.1.1-dev → 0.2.0-dev

package/dist/index.d.cts

@@ -2,10 +2,142 @@ import { C as ComputeModule } from './compute-B_ibIORD.cjs';
 export { e as ComputeModuleConfig, a as CreateAppOpts, L as LogsOptions, P as PRIMARY_LANGUAGES, S as SDKCreateAppOpts, b as SDKLogsOptions, c as createApp, d as createComputeModule, f as encodeStartAppData, h as encodeStopAppData, i as encodeTerminateAppData, g as getAvailableTemplates, l as logs } from './compute-B_ibIORD.cjs';
 import { BillingModule } from './billing.cjs';
 export { BillingModuleConfig, createBillingModule } from './billing.cjs';
-import { E as EnvironmentConfig, L as Logger, D as DeployResult, S as SubscriptionStatus } from './index-D-SUX3IG.cjs';
+import { E as EnvironmentConfig, S as SubscriptionStatus, L as Logger, D as DeployResult } from './index-D-SUX3IG.cjs';
 export { m as AlreadyActiveResponse, A as AppId, f as AppProfile, g as AppProfileResponse, c as AppRecord, B as BillingEnvironmentConfig, q as CancelResponse, p as CancelSuccessResponse, C as ChainID, k as CheckoutCreatedResponse, j as CreateSubscriptionResponse, a as DeployAppOpts, d as DeployOptions, e as DockerImageConfig, I as ImageDigestResult, b as LifecycleOpts, N as NoActiveSubscriptionResponse, P as ParsedEnvironment, n as PaymentIssueResponse, h as ProductID, r as ProductSubscriptionResponse, R as Release, o as SubscribeResponse, i as SubscriptionLineItem, s as SubscriptionOpts, U as UpgradeAppOpts, l as logVisibility } from './index-D-SUX3IG.cjs';
 import { Address, Hex, WalletClient, PublicClient, PrivateKeyAccount } from 'viem';
 
+interface SubmitBuildRequest {
+    repoUrl: string;
+    gitRef: string;
+    dockerfilePath?: string;
+    /**
+     * Path to a Caddyfile within the repository (relative to buildContextPath).
+     * If omitted, the build service will not copy a Caddyfile into the image.
+     */
+    caddyfilePath?: string;
+    buildContextPath?: string;
+    dependencies?: string[];
+}
+interface SubmitBuildResponse {
+    buildId: string;
+}
+declare const BUILD_STATUS: {
+    readonly BUILDING: "building";
+    readonly SUCCESS: "success";
+    readonly FAILED: "failed";
+};
+type BuildStatus = (typeof BUILD_STATUS)[keyof typeof BUILD_STATUS];
+interface Build {
+    buildId: string;
+    billingAddress: string;
+    repoUrl: string;
+    gitRef: string;
+    status: BuildStatus;
+    /** 'application' | 'dependency' (as returned by the API) */
+    buildType: string;
+    imageName: string;
+    imageUrl?: string;
+    imageDigest?: string;
+    provenanceJson?: Record<string, unknown>;
+    provenanceSignature?: string;
+    errorMessage?: string;
+    createdAt: string;
+    updatedAt: string;
+    dependencies?: Record<string, Build>;
+}
+type VerifyProvenanceResult = VerifyProvenanceSuccess | VerifyProvenanceFailure;
+interface VerifyProvenanceSuccess {
+    status: "verified";
+    buildId: string;
+    imageUrl: string;
+    imageDigest: string;
+    repoUrl: string;
+    gitRef: string;
+    provenanceJson: Record<string, unknown>;
+    provenanceSignature: string;
+    payloadType: string;
+    payload: string;
+}
+interface VerifyProvenanceFailure {
+    status: "failed";
+    error: string;
+    buildId?: string;
+}
+interface LogChunk {
+    content: string;
+    totalLength: number;
+    isComplete: boolean;
+    finalStatus?: BuildStatus;
+}
+interface BuildProgress {
+    build: Build;
+    logs: string;
+}
+
+declare class BuildError extends Error {
+    constructor(message: string);
+}
+declare class AuthRequiredError extends BuildError {
+    constructor(message?: string);
+}
+declare class BuildFailedError extends BuildError {
+    readonly buildId: string;
+    constructor(message: string, buildId: string);
+}
+declare class ConflictError extends BuildError {
+    constructor(message?: string);
+}
+declare class NotFoundError extends BuildError {
+    constructor(message?: string);
+}
+declare class ForbiddenError extends BuildError {
+    constructor(message?: string);
+}
+declare class TimeoutError extends BuildError {
+    constructor(message?: string);
+}
+declare class BadRequestError extends BuildError {
+    constructor(message?: string);
+}
+
+/**
+ * Build module entry point (verifiable builds + provenance)
+ */
+
+interface BuildModuleConfig {
+    privateKey?: string;
+    environment?: string;
+    verbose?: boolean;
+    clientId?: string;
+    skipTelemetry?: boolean;
+}
+interface BuildModule {
+    submit(request: SubmitBuildRequest): Promise<SubmitBuildResponse>;
+    getLogs(buildId: string): Promise<string>;
+    list(options: {
+        billingAddress: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<Build[]>;
+    get(buildId: string): Promise<Build>;
+    getByDigest(digest: string): Promise<Build>;
+    verify(identifier: string): Promise<VerifyProvenanceResult>;
+    submitAndWait(request: SubmitBuildRequest, options?: {
+        onLog?: (chunk: string) => void;
+        onProgress?: (progress: BuildProgress) => void;
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<Build>;
+    waitForBuild(buildId: string, options?: {
+        onLog?: (chunk: string) => void;
+        onProgress?: (progress: BuildProgress) => void;
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<Build>;
+    streamLogs(buildId: string, pollIntervalMs?: number): AsyncGenerator<LogChunk, void, unknown>;
+}
+declare function createBuildModule(config: BuildModuleConfig): BuildModule;
+
 /**
  * Non-interactive validation utilities for SDK
  *
@@ -170,6 +302,145 @@ interface LogsParams {
  */
 declare function validateLogsParams(params: Partial<LogsParams>): void;
 
+/**
+ * UserAPI Client to manage interactions with the coordinator
+ */
+
+interface AppProfileInfo {
+    name: string;
+    website?: string;
+    description?: string;
+    xURL?: string;
+    imageURL?: string;
+}
+interface AppMetrics {
+    cpu_utilization_percent?: number;
+    memory_utilization_percent?: number;
+    memory_used_bytes?: number;
+    memory_total_bytes?: number;
+}
+interface DerivedAddress {
+    address: string;
+    derivationPath: string;
+}
+interface AppInfo {
+    address: Address;
+    status: string;
+    ip: string;
+    machineType: string;
+    profile?: AppProfileInfo;
+    metrics?: AppMetrics;
+    evmAddresses: DerivedAddress[];
+    solanaAddresses: DerivedAddress[];
+}
+type AppContractStatus = "STARTED" | "STOPPED" | "TERMINATED" | "SUSPENDED" | string;
+interface AppReleaseBuild {
+    buildId?: string;
+    billingAddress?: string;
+    repoUrl?: string;
+    gitRef?: string;
+    status?: string;
+    buildType?: string;
+    imageName?: string;
+    imageDigest?: string;
+    imageUrl?: string;
+    provenanceJson?: unknown;
+    provenanceSignature?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    errorMessage?: string;
+    dependencies?: Record<string, AppReleaseBuild>;
+}
+interface AppRelease {
+    appId?: string;
+    rmsReleaseId?: string;
+    imageDigest?: string;
+    registryUrl?: string;
+    publicEnv?: string;
+    encryptedEnv?: string;
+    upgradeByTime?: number;
+    createdAt?: string;
+    createdAtBlock?: string;
+    build?: AppReleaseBuild;
+}
+interface AppResponse {
+    id: string;
+    creator?: string;
+    contractStatus?: AppContractStatus;
+    releases: AppRelease[];
+}
+declare class UserApiClient {
+    private readonly config;
+    private readonly account?;
+    private readonly rpcUrl?;
+    private readonly clientId;
+    constructor(config: EnvironmentConfig, privateKey?: string | Hex, rpcUrl?: string, clientId?: string);
+    getInfos(appIDs: Address[], addressCount?: number): Promise<AppInfo[]>;
+    /**
+     * Get app details from UserAPI (includes releases and build/provenance info when available).
+     *
+     * Endpoint: GET /apps/:appAddress
+     */
+    getApp(appAddress: Address): Promise<AppResponse>;
+    /**
+     * Get available SKUs (instance types) from UserAPI
+     */
+    getSKUs(): Promise<{
+        skus: Array<{
+            sku: string;
+            description: string;
+        }>;
+    }>;
+    /**
+     * Get logs for an app
+     */
+    getLogs(appID: Address): Promise<string>;
+    /**
+     * Get statuses for apps
+     */
+    getStatuses(appIDs: Address[]): Promise<Array<{
+        address: Address;
+        status: string;
+    }>>;
+    /**
+     * Upload app profile information with optional image
+     */
+    uploadAppProfile(appAddress: Address, name: string, website?: string, description?: string, xURL?: string, imagePath?: string): Promise<{
+        name: string;
+        website?: string;
+        description?: string;
+        xURL?: string;
+        imageURL?: string;
+    }>;
+    private makeAuthenticatedRequest;
+    /**
+     * Generate authentication headers for UserAPI requests
+     */
+    private generateAuthHeaders;
+}
+
+/**
+ * Billing utility functions
+ */
+
+/**
+ * Check if subscription status allows deploying apps
+ */
+declare function isSubscriptionActive(status: SubscriptionStatus): boolean;
+
+/**
+ * General utility helpers
+ */
+
+/**
+ * Ensure hex string has 0x prefix
+ */
+declare function addHexPrefix(value: string): `0x${string}`;
+/**
+ * Remove 0x prefix from hex string if present
+ */
+declare function stripHexPrefix(value: string): string;
+
 /**
  * Contract interactions
  *
@@ -343,6 +614,23 @@ interface PrepareDeployResult {
     /** Gas estimate for the batch transaction */
     gasEstimate: GasEstimate;
 }
+/**
+ * Prepare a deployment from a pre-built image (already layered) without using Docker locally.
+ *
+ * This is intended for verifiable builds where the build service outputs:
+ * - imageRef (tagged image URL)
+ * - imageDigest (sha256:... digest)
+ *
+ * Flow is the same as prepareDeploy, except:
+ * - Skips ensureDockerIsRunning()
+ * - Skips prepareRelease() image layering and digest extraction
+ * - Uses provided imageDigest + derived registry name to construct the Release struct
+ */
+declare function prepareDeployFromVerifiableBuild(options: Omit<SDKDeployOptions, "gas" | "dockerfilePath" | "imageRef"> & {
+    imageRef: string;
+    imageDigest: string;
+    skipTelemetry?: boolean;
+}, logger?: Logger): Promise<PrepareDeployResult>;
 /**
  * Prepare deployment - does all work up to the transaction
  *
@@ -449,6 +737,19 @@ interface PrepareUpgradeResult {
     /** Gas estimate for the batch transaction */
     gasEstimate: GasEstimate;
 }
+/**
+ * Prepare an upgrade from a pre-built image (already layered) without using Docker locally.
+ *
+ * Intended for verifiable builds: build service provides imageRef + imageDigest (sha256:...).
+ * This skips:
+ * - ensureDockerIsRunning()
+ * - prepareRelease() layering/digest extraction
+ */
+declare function prepareUpgradeFromVerifiableBuild(options: Omit<SDKUpgradeOptions, "gas" | "dockerfilePath" | "imageRef"> & {
+    imageRef: string;
+    imageDigest: string;
+    skipTelemetry?: boolean;
+}, logger?: Logger): Promise<PrepareUpgradeResult>;
 /**
  * Prepare upgrade - does all work up to the transaction
  *
@@ -503,15 +804,6 @@ declare function isEnvironmentAvailable(environment: string): boolean;
  */
 declare function isMainnet(environmentConfig: EnvironmentConfig): boolean;
 
-/**
- * Billing utility functions
- */
-
-/**
- * Check if subscription status allows deploying apps
- */
-declare function isSubscriptionActive(status: SubscriptionStatus): boolean;
-
 /**
  * OS Keyring Integration
  *
@@ -936,81 +1228,6 @@ interface PreflightContext {
  */
 declare function getCurrentInstanceType(preflightCtx: PreflightContext, appID: Address, logger: Logger, clientId?: string): Promise<string>;
 
-/**
- * UserAPI Client to manage interactions with the coordinator
- */
-
-interface AppProfileInfo {
-    name: string;
-    website?: string;
-    description?: string;
-    xURL?: string;
-    imageURL?: string;
-}
-interface AppMetrics {
-    cpu_utilization_percent?: number;
-    memory_utilization_percent?: number;
-    memory_used_bytes?: number;
-    memory_total_bytes?: number;
-}
-interface DerivedAddress {
-    address: string;
-    derivationPath: string;
-}
-interface AppInfo {
-    address: Address;
-    status: string;
-    ip: string;
-    machineType: string;
-    profile?: AppProfileInfo;
-    metrics?: AppMetrics;
-    evmAddresses: DerivedAddress[];
-    solanaAddresses: DerivedAddress[];
-}
-declare class UserApiClient {
-    private readonly config;
-    private readonly account?;
-    private readonly rpcUrl?;
-    private readonly clientId;
-    constructor(config: EnvironmentConfig, privateKey?: string | Hex, rpcUrl?: string, clientId?: string);
-    getInfos(appIDs: Address[], addressCount?: number): Promise<AppInfo[]>;
-    /**
-     * Get available SKUs (instance types) from UserAPI
-     */
-    getSKUs(): Promise<{
-        skus: Array<{
-            sku: string;
-            description: string;
-        }>;
-    }>;
-    /**
-     * Get logs for an app
-     */
-    getLogs(appID: Address): Promise<string>;
-    /**
-     * Get statuses for apps
-     */
-    getStatuses(appIDs: Address[]): Promise<Array<{
-        address: Address;
-        status: string;
-    }>>;
-    /**
-     * Upload app profile information with optional image
-     */
-    uploadAppProfile(appAddress: Address, name: string, website?: string, description?: string, xURL?: string, imagePath?: string): Promise<{
-        name: string;
-        website?: string;
-        description?: string;
-        xURL?: string;
-        imageURL?: string;
-    }>;
-    private makeAuthenticatedRequest;
-    /**
-     * Generate authentication headers for UserAPI requests
-     */
-    private generateAuthHeaders;
-}
-
 /**
  * Main SDK Client entry point
  */
@@ -1028,4 +1245,4 @@ interface ECloudClient {
 }
 declare function createECloudClient(cfg: ClientConfig): ECloudClient;
 
-export { type AppEnvironment, type AppInfo, type AppMetrics, type AppProfileInfo, BillingModule, type ClientConfig, ComputeModule, type CreateAppParams, type DeployParams, DeployResult, type ECloudClient, type Environment, EnvironmentConfig, type EstimateBatchGasOptions, type EstimateGasOptions, type GasEstimate, type GeneratedKey, type LegacyKey, type LogVisibility, Logger, type LogsParams, type Metric, type MetricsContext, NoopClient, PostHogClient, type PrepareDeployResult, type PrepareUpgradeResult, type PreparedDeploy, type PreparedUpgrade, type PrivateKeySource, type ResourceUsageMonitoring, type SDKDeployOptions, type SDKUpgradeOptions, type StoredKey, SubscriptionStatus, type TelemetryClient, type TelemetryClientOptions, type TelemetryWrapperOptions, type UpgradeParams, UserApiClient, addMetric, addMetricWithDimensions, assertValidFilePath, assertValidImageReference, assertValidPrivateKey, checkERC7702Delegation, createAppEnvironment, createECloudClient, createMetricsContext, createTelemetryClient, deleteLegacyPrivateKey, deletePrivateKey, emitMetrics, estimateBatchGas, estimateTransactionGas, executeDeploy, executeUpgrade, extractAppNameFromImage, fetchTemplateCatalog, formatETH, generateNewPrivateKey, getAddressFromPrivateKey, getAllAppsByDeveloper, getAppLatestReleaseBlockNumbers, getAvailableEnvironments, getBlockTimestamps, getBuildType, getCategoryDescriptions, getCurrentInstanceType, getEnvironmentConfig, getLegacyKeys, getLegacyPrivateKey, getPostHogAPIKey, getPostHogEndpoint, getPrivateKey, getPrivateKeyWithSource, getTemplate, isEnvironmentAvailable, isMainnet, isNoopClient, isSubscriptionActive, keyExists, listStoredKeys, prepareDeploy, prepareUpgrade, requirePrivateKey, sanitizeString, sanitizeURL, sanitizeXURL, storePrivateKey, validateAppID, validateAppName, validateCreateAppParams, validateDeployParams, validateDescription, validateFilePath, validateImagePath, validateImageReference, validateInstanceTypeSKU, validateLogVisibility, validateLogsParams, validatePrivateKey, validatePrivateKeyFormat, validateResourceUsageMonitoring, validateURL, validateUpgradeParams, validateXURL, watchDeployment, watchUpgrade, withSDKTelemetry };
+export { type AppEnvironment, type AppInfo, type AppMetrics, type AppProfileInfo, type AppRelease, type AppReleaseBuild, type AppResponse, AuthRequiredError, BUILD_STATUS, BadRequestError, BillingModule, type Build, BuildError, BuildFailedError, type BuildModule, type BuildModuleConfig, type BuildProgress, type BuildStatus, type ClientConfig, ComputeModule, ConflictError, type CreateAppParams, type DeployParams, DeployResult, type ECloudClient, type Environment, EnvironmentConfig, type EstimateBatchGasOptions, type EstimateGasOptions, ForbiddenError, type GasEstimate, type GeneratedKey, type LegacyKey, type LogChunk, type LogVisibility, Logger, type LogsParams, type Metric, type MetricsContext, NoopClient, NotFoundError, PostHogClient, type PrepareDeployResult, type PrepareUpgradeResult, type PreparedDeploy, type PreparedUpgrade, type PrivateKeySource, type ResourceUsageMonitoring, type SDKDeployOptions, type SDKUpgradeOptions, type StoredKey, type SubmitBuildRequest, type SubmitBuildResponse, SubscriptionStatus, type TelemetryClient, type TelemetryClientOptions, type TelemetryWrapperOptions, TimeoutError, type UpgradeParams, UserApiClient, type VerifyProvenanceFailure, type VerifyProvenanceResult, type VerifyProvenanceSuccess, addHexPrefix, addMetric, addMetricWithDimensions, assertValidFilePath, assertValidImageReference, assertValidPrivateKey, checkERC7702Delegation, createAppEnvironment, createBuildModule, createECloudClient, createMetricsContext, createTelemetryClient, deleteLegacyPrivateKey, deletePrivateKey, emitMetrics, estimateBatchGas, estimateTransactionGas, executeDeploy, executeUpgrade, extractAppNameFromImage, fetchTemplateCatalog, formatETH, generateNewPrivateKey, getAddressFromPrivateKey, getAllAppsByDeveloper, getAppLatestReleaseBlockNumbers, getAvailableEnvironments, getBlockTimestamps, getBuildType, getCategoryDescriptions, getCurrentInstanceType, getEnvironmentConfig, getLegacyKeys, getLegacyPrivateKey, getPostHogAPIKey, getPostHogEndpoint, getPrivateKey, getPrivateKeyWithSource, getTemplate, isEnvironmentAvailable, isMainnet, isNoopClient, isSubscriptionActive, keyExists, listStoredKeys, prepareDeploy, prepareDeployFromVerifiableBuild, prepareUpgrade, prepareUpgradeFromVerifiableBuild, requirePrivateKey, sanitizeString, sanitizeURL, sanitizeXURL, storePrivateKey, stripHexPrefix, validateAppID, validateAppName, validateCreateAppParams, validateDeployParams, validateDescription, validateFilePath, validateImagePath, validateImageReference, validateInstanceTypeSKU, validateLogVisibility, validateLogsParams, validatePrivateKey, validatePrivateKeyFormat, validateResourceUsageMonitoring, validateURL, validateUpgradeParams, validateXURL, watchDeployment, watchUpgrade, withSDKTelemetry };