@caatinga/core 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,575 @@
+import { z } from 'zod';
+
+declare const CaatingaErrorCode: {
+    readonly CONFIG_NOT_FOUND: "CAATINGA_CONFIG_NOT_FOUND";
+    readonly INVALID_CONFIG: "CAATINGA_INVALID_CONFIG";
+    readonly COMMAND_FAILED: "CAATINGA_COMMAND_FAILED";
+    readonly UNEXPECTED_ERROR: "CAATINGA_UNEXPECTED_ERROR";
+    readonly STELLAR_CLI_NOT_FOUND: "CAATINGA_STELLAR_CLI_NOT_FOUND";
+    readonly STELLAR_CLI_VERSION_PARSE_FAILED: "CAATINGA_STELLAR_CLI_VERSION_PARSE_FAILED";
+    readonly UNSUPPORTED_CLI_VERSION: "CAATINGA_UNSUPPORTED_CLI_VERSION";
+    readonly UNTESTED_CLI_VERSION: "CAATINGA_UNTESTED_CLI_VERSION";
+    readonly RUST_NOT_FOUND: "CAATINGA_RUST_NOT_FOUND";
+    readonly RUST_TARGET_NOT_FOUND: "CAATINGA_RUST_TARGET_NOT_FOUND";
+    readonly DEPLOY_FAILED: "CAATINGA_DEPLOY_FAILED";
+    readonly BUILD_FAILED: "CAATINGA_BUILD_FAILED";
+    readonly BINDINGS_FAILED: "CAATINGA_BINDINGS_FAILED";
+    readonly INVOKE_FAILED: "CAATINGA_INVOKE_FAILED";
+    readonly CONTRACT_NOT_FOUND: "CAATINGA_CONTRACT_NOT_FOUND";
+    readonly NETWORK_NOT_FOUND: "CAATINGA_NETWORK_NOT_FOUND";
+    readonly ARTIFACT_NOT_FOUND: "CAATINGA_ARTIFACT_NOT_FOUND";
+    readonly ARTIFACT_INVALID: "CAATINGA_ARTIFACT_INVALID";
+    readonly CONTRACT_ID_NOT_FOUND: "CAATINGA_CONTRACT_ID_NOT_FOUND";
+    readonly CONTRACT_ARTIFACT_NOT_FOUND: "CAATINGA_CONTRACT_ARTIFACT_NOT_FOUND";
+    readonly CONTRACT_DEPENDENCY_NOT_FOUND: "CAATINGA_CONTRACT_DEPENDENCY_NOT_FOUND";
+    readonly CONTRACT_DEPENDENCY_CYCLE: "CAATINGA_CONTRACT_DEPENDENCY_CYCLE";
+    readonly CONTRACT_DEPENDENCY_ARTIFACT_NOT_FOUND: "CAATINGA_CONTRACT_DEPENDENCY_ARTIFACT_NOT_FOUND";
+    readonly DEPLOY_ARG_PLACEHOLDER_INVALID: "CAATINGA_DEPLOY_ARG_PLACEHOLDER_INVALID";
+    readonly DEPLOY_ARG_PLACEHOLDER_UNRESOLVED: "CAATINGA_DEPLOY_ARG_PLACEHOLDER_UNRESOLVED";
+    readonly BINDING_CLIENT_NOT_FOUND: "CAATINGA_BINDING_CLIENT_NOT_FOUND";
+    readonly BINDING_METHOD_NOT_FOUND: "CAATINGA_BINDING_METHOD_NOT_FOUND";
+    readonly XDR_BUILD_FAILED: "CAATINGA_XDR_BUILD_FAILED";
+    readonly XDR_PREPARE_FAILED: "CAATINGA_XDR_PREPARE_FAILED";
+    readonly XDR_SIGN_FAILED: "CAATINGA_XDR_SIGN_FAILED";
+    readonly XDR_SUBMIT_FAILED: "CAATINGA_XDR_SUBMIT_FAILED";
+    readonly XDR_RESULT_FAILED: "CAATINGA_XDR_RESULT_FAILED";
+    readonly WALLET_NOT_CONNECTED: "CAATINGA_WALLET_NOT_CONNECTED";
+    readonly SOURCE_ACCOUNT_REQUIRED: "CAATINGA_SOURCE_ACCOUNT_REQUIRED";
+    readonly UNSAFE_SOURCE_ACCOUNT: "CAATINGA_UNSAFE_SOURCE_ACCOUNT";
+    readonly INVOKE_TARGET_INVALID: "CAATINGA_INVOKE_TARGET_INVALID";
+    readonly TEMPLATE_NOT_FOUND: "CAATINGA_TEMPLATE_NOT_FOUND";
+    readonly INVALID_TEMPLATE_MANIFEST: "CAATINGA_INVALID_TEMPLATE_MANIFEST";
+    readonly TEMPLATE_MANIFEST_NOT_FOUND: "CAATINGA_TEMPLATE_MANIFEST_NOT_FOUND";
+    readonly TEMPLATE_INCOMPATIBLE: "CAATINGA_TEMPLATE_INCOMPATIBLE";
+};
+type CaatingaErrorCodeValue = typeof CaatingaErrorCode[keyof typeof CaatingaErrorCode];
+
+declare class CaatingaError extends Error {
+    readonly code: CaatingaErrorCodeValue;
+    readonly hint?: string | undefined;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: CaatingaErrorCodeValue, hint?: string | undefined, cause?: unknown | undefined);
+}
+declare function toCaatingaError(error: unknown): CaatingaError;
+
+declare const CAATINGA_CORE_VERSION = "0.2.0";
+
+declare const ContractConfigSchema: z.ZodObject<{
+    path: z.ZodString;
+    wasm: z.ZodString;
+    dependsOn: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    deployArgs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    wasm: string;
+    dependsOn: string[];
+    deployArgs: Record<string, string | number | boolean>;
+}, {
+    path: string;
+    wasm: string;
+    dependsOn?: string[] | undefined;
+    deployArgs?: Record<string, string | number | boolean> | undefined;
+}>;
+declare const NetworkConfigSchema: z.ZodObject<{
+    rpcUrl: z.ZodString;
+    networkPassphrase: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    rpcUrl: string;
+    networkPassphrase: string;
+}, {
+    rpcUrl: string;
+    networkPassphrase: string;
+}>;
+declare const CaatingaConfigSchema: z.ZodObject<{
+    project: z.ZodString;
+    defaultNetwork: z.ZodDefault<z.ZodString>;
+    contracts: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodObject<{
+        path: z.ZodString;
+        wasm: z.ZodString;
+        dependsOn: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        deployArgs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        wasm: string;
+        dependsOn: string[];
+        deployArgs: Record<string, string | number | boolean>;
+    }, {
+        path: string;
+        wasm: string;
+        dependsOn?: string[] | undefined;
+        deployArgs?: Record<string, string | number | boolean> | undefined;
+    }>>, Record<string, {
+        path: string;
+        wasm: string;
+        dependsOn: string[];
+        deployArgs: Record<string, string | number | boolean>;
+    }>, Record<string, {
+        path: string;
+        wasm: string;
+        dependsOn?: string[] | undefined;
+        deployArgs?: Record<string, string | number | boolean> | undefined;
+    }>>;
+    networks: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodObject<{
+        rpcUrl: z.ZodString;
+        networkPassphrase: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        rpcUrl: string;
+        networkPassphrase: string;
+    }, {
+        rpcUrl: string;
+        networkPassphrase: string;
+    }>>, Record<string, {
+        rpcUrl: string;
+        networkPassphrase: string;
+    }>, Record<string, {
+        rpcUrl: string;
+        networkPassphrase: string;
+    }>>;
+    frontend: z.ZodObject<{
+        framework: z.ZodDefault<z.ZodEnum<["vite-react", "next", "astro"]>>;
+        bindingsOutput: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        framework: "vite-react" | "next" | "astro";
+        bindingsOutput: string;
+    }, {
+        bindingsOutput: string;
+        framework?: "vite-react" | "next" | "astro" | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    project: string;
+    defaultNetwork: string;
+    contracts: Record<string, {
+        path: string;
+        wasm: string;
+        dependsOn: string[];
+        deployArgs: Record<string, string | number | boolean>;
+    }>;
+    networks: Record<string, {
+        rpcUrl: string;
+        networkPassphrase: string;
+    }>;
+    frontend: {
+        framework: "vite-react" | "next" | "astro";
+        bindingsOutput: string;
+    };
+}, {
+    project: string;
+    contracts: Record<string, {
+        path: string;
+        wasm: string;
+        dependsOn?: string[] | undefined;
+        deployArgs?: Record<string, string | number | boolean> | undefined;
+    }>;
+    networks: Record<string, {
+        rpcUrl: string;
+        networkPassphrase: string;
+    }>;
+    frontend: {
+        bindingsOutput: string;
+        framework?: "vite-react" | "next" | "astro" | undefined;
+    };
+    defaultNetwork?: string | undefined;
+}>;
+type CaatingaConfig = z.infer<typeof CaatingaConfigSchema>;
+type ContractConfig = z.infer<typeof ContractConfigSchema>;
+type NetworkConfig = z.infer<typeof NetworkConfigSchema>;
+
+declare function defineConfig(config: CaatingaConfig): CaatingaConfig;
+
+type LoadConfigOptions = {
+    cwd?: string;
+    configPath?: string;
+};
+declare function loadConfig(options?: LoadConfigOptions): Promise<CaatingaConfig>;
+
+declare const ContractArtifactSchema: z.ZodObject<{
+    contractId: z.ZodString;
+    wasmHash: z.ZodString;
+    deployedAt: z.ZodString;
+    sourcePath: z.ZodString;
+    wasmPath: z.ZodString;
+    dependencies: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    resolvedDeployArgs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+}, "strip", z.ZodTypeAny, {
+    contractId: string;
+    wasmHash: string;
+    deployedAt: string;
+    sourcePath: string;
+    wasmPath: string;
+    dependencies: string[];
+    resolvedDeployArgs: Record<string, string | number | boolean>;
+}, {
+    contractId: string;
+    wasmHash: string;
+    deployedAt: string;
+    sourcePath: string;
+    wasmPath: string;
+    dependencies?: string[] | undefined;
+    resolvedDeployArgs?: Record<string, string | number | boolean> | undefined;
+}>;
+declare const CaatingaArtifactsSchema: z.ZodObject<{
+    project: z.ZodString;
+    version: z.ZodLiteral<1>;
+    networks: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        contracts: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            contractId: z.ZodString;
+            wasmHash: z.ZodString;
+            deployedAt: z.ZodString;
+            sourcePath: z.ZodString;
+            wasmPath: z.ZodString;
+            dependencies: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+            resolvedDeployArgs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        }, "strip", z.ZodTypeAny, {
+            contractId: string;
+            wasmHash: string;
+            deployedAt: string;
+            sourcePath: string;
+            wasmPath: string;
+            dependencies: string[];
+            resolvedDeployArgs: Record<string, string | number | boolean>;
+        }, {
+            contractId: string;
+            wasmHash: string;
+            deployedAt: string;
+            sourcePath: string;
+            wasmPath: string;
+            dependencies?: string[] | undefined;
+            resolvedDeployArgs?: Record<string, string | number | boolean> | undefined;
+        }>>>;
+        dependencyGraph: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+    }, "strip", z.ZodTypeAny, {
+        contracts: Record<string, {
+            contractId: string;
+            wasmHash: string;
+            deployedAt: string;
+            sourcePath: string;
+            wasmPath: string;
+            dependencies: string[];
+            resolvedDeployArgs: Record<string, string | number | boolean>;
+        }>;
+        dependencyGraph: Record<string, string[]>;
+    }, {
+        contracts?: Record<string, {
+            contractId: string;
+            wasmHash: string;
+            deployedAt: string;
+            sourcePath: string;
+            wasmPath: string;
+            dependencies?: string[] | undefined;
+            resolvedDeployArgs?: Record<string, string | number | boolean> | undefined;
+        }> | undefined;
+        dependencyGraph?: Record<string, string[]> | undefined;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    project: string;
+    networks: Record<string, {
+        contracts: Record<string, {
+            contractId: string;
+            wasmHash: string;
+            deployedAt: string;
+            sourcePath: string;
+            wasmPath: string;
+            dependencies: string[];
+            resolvedDeployArgs: Record<string, string | number | boolean>;
+        }>;
+        dependencyGraph: Record<string, string[]>;
+    }>;
+    version: 1;
+}, {
+    project: string;
+    version: 1;
+    networks?: Record<string, {
+        contracts?: Record<string, {
+            contractId: string;
+            wasmHash: string;
+            deployedAt: string;
+            sourcePath: string;
+            wasmPath: string;
+            dependencies?: string[] | undefined;
+            resolvedDeployArgs?: Record<string, string | number | boolean> | undefined;
+        }> | undefined;
+        dependencyGraph?: Record<string, string[]> | undefined;
+    }> | undefined;
+}>;
+type ContractArtifact = z.infer<typeof ContractArtifactSchema>;
+type CaatingaArtifacts = z.infer<typeof CaatingaArtifactsSchema>;
+
+declare function readArtifacts(cwd?: string): Promise<CaatingaArtifacts>;
+
+declare function writeArtifacts(artifacts: CaatingaArtifacts, cwd?: string): Promise<string>;
+declare function createInitialArtifacts(project: string): CaatingaArtifacts;
+
+declare function updateArtifact(artifacts: CaatingaArtifacts, networkName: string, contractName: string, contractArtifact: ContractArtifact, networkExtras?: {
+    dependencyGraph?: Record<string, string[]>;
+}): CaatingaArtifacts;
+
+declare const WELL_KNOWN_NETWORKS: Record<string, NetworkConfig>;
+
+type ResolvedNetwork = {
+    name: string;
+    config: NetworkConfig;
+};
+declare function resolveNetwork(config: CaatingaConfig, networkName?: string): ResolvedNetwork;
+
+type RunCommandResult = {
+    stdout: string;
+    stderr: string;
+    all: string;
+};
+type RunCommandOptions = {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    allowUntestedStellarCli?: boolean;
+    skipStellarVersionCheck?: boolean;
+    failureCode?: CaatingaErrorCodeValue;
+};
+declare function runCommand(command: string, args: string[], options?: RunCommandOptions): Promise<RunCommandResult>;
+
+type CheckBinaryOptions = {
+    allowUntestedStellarCli?: boolean;
+    skipStellarVersionCheck?: boolean;
+};
+declare function checkBinary(binary: string, hint: string, options?: CheckBinaryOptions): Promise<void>;
+
+declare function parseContractId(output: string): string;
+
+declare const STELLAR_CLI_MIN_VERSION = "22.0.0";
+declare const STELLAR_CLI_TESTED_MAX_VERSION = "25.2.0";
+declare function parseStellarCliVersion(output: string): string;
+declare function assertSupportedStellarCliVersion(input: {
+    version: string;
+    allowUntested: boolean;
+}): string;
+
+type ResolvedContract = {
+    name: string;
+    config: ContractConfig;
+    sourcePath: string;
+    wasmPath: string;
+};
+declare function resolveContract(config: CaatingaConfig, contractName: string, cwd?: string): ResolvedContract;
+
+type BuildContractOptions = {
+    config: CaatingaConfig;
+    contractName: string;
+    cwd?: string;
+    allowUntestedStellarCli?: boolean;
+};
+declare function buildContract(options: BuildContractOptions): Promise<{
+    contract: ResolvedContract;
+    output: string;
+}>;
+
+type DeployArgValue = string | number | boolean;
+declare function resolveDeployArgs(input: {
+    deployArgs: Record<string, DeployArgValue>;
+    artifacts: CaatingaArtifacts;
+    network: string;
+}): Record<string, DeployArgValue>;
+
+type DeployContractOptions = {
+    config: CaatingaConfig;
+    contractName: string;
+    networkName?: string;
+    source?: string;
+    cwd?: string;
+    allowUntestedStellarCli?: boolean;
+    force?: boolean;
+    resolvedDeployArgs?: Record<string, DeployArgValue>;
+    dependencies?: string[];
+};
+declare function deployContract(options: DeployContractOptions): Promise<{
+    contract: ResolvedContract;
+    network: ResolvedNetwork;
+    contractId: string;
+    artifactsPath: string;
+    output: string;
+    skipped: true;
+} | {
+    contract: ResolvedContract;
+    network: ResolvedNetwork;
+    contractId: string;
+    artifactsPath: string;
+    output: string;
+    skipped: false;
+}>;
+
+declare function deployContractGraph(options: {
+    config: CaatingaConfig;
+    contractName?: string;
+    networkName?: string;
+    source?: string;
+    cwd?: string;
+    includeDependencies: boolean;
+    force: boolean;
+    allowUntestedStellarCli?: boolean;
+}): Promise<{
+    network: ResolvedNetwork;
+    deployedContracts: {
+        name: string;
+        contractId: string;
+    }[];
+}>;
+
+declare function buildDependencyGraph(contracts: Record<string, ContractConfig>): Record<string, string[]>;
+
+declare function resolveDeployOrder(input: {
+    contracts: Record<string, ContractConfig>;
+    selectedContract?: string;
+    includeDependencies: boolean;
+}): string[];
+
+type GenerateBindingsOptions = {
+    config: CaatingaConfig;
+    contractName: string;
+    networkName?: string;
+    cwd?: string;
+    allowUntestedStellarCli?: boolean;
+};
+declare function generateBindings(options: GenerateBindingsOptions): Promise<{
+    contractName: string;
+    network: ResolvedNetwork;
+    outputDir: string;
+    output: string;
+}>;
+
+type InvokeTarget = {
+    contractName: string;
+    method: string;
+};
+type InvokeContractOptions = {
+    config: CaatingaConfig;
+    target: string;
+    args?: string[];
+    networkName?: string;
+    source?: string;
+    cwd?: string;
+    allowUntestedStellarCli?: boolean;
+};
+declare function parseInvokeTarget(target: string): InvokeTarget;
+declare function invokeContract(options: InvokeContractOptions): Promise<{
+    target: InvokeTarget;
+    network: ResolvedNetwork;
+    result: string;
+}>;
+
+type CreateProjectFromTemplateOptions = {
+    projectName: string;
+    targetDir: string;
+    templateDir: string;
+};
+declare function createProjectFromTemplate(options: CreateProjectFromTemplateOptions): Promise<{
+    targetDir: string;
+    template: {
+        contracts: {
+            path: string;
+            default?: string | undefined;
+        };
+        frontend: {
+            framework: "vite-react" | "next" | "astro";
+            packageManager: "npm" | "pnpm" | "yarn" | "bun";
+        };
+        version: string;
+        name: string;
+        caatinga: {
+            compatibleCore: string;
+            templateVersion: number;
+        };
+        files: {
+            config: string;
+            artifacts: string;
+        };
+        description?: string | undefined;
+    };
+}>;
+
+declare const TemplateManifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    caatinga: z.ZodObject<{
+        compatibleCore: z.ZodString;
+        templateVersion: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        compatibleCore: string;
+        templateVersion: number;
+    }, {
+        compatibleCore: string;
+        templateVersion: number;
+    }>;
+    frontend: z.ZodObject<{
+        framework: z.ZodEnum<["vite-react", "next", "astro"]>;
+        packageManager: z.ZodDefault<z.ZodEnum<["npm", "pnpm", "yarn", "bun"]>>;
+    }, "strip", z.ZodTypeAny, {
+        framework: "vite-react" | "next" | "astro";
+        packageManager: "npm" | "pnpm" | "yarn" | "bun";
+    }, {
+        framework: "vite-react" | "next" | "astro";
+        packageManager?: "npm" | "pnpm" | "yarn" | "bun" | undefined;
+    }>;
+    contracts: z.ZodObject<{
+        path: z.ZodString;
+        default: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        default?: string | undefined;
+    }, {
+        path: string;
+        default?: string | undefined;
+    }>;
+    files: z.ZodObject<{
+        config: z.ZodDefault<z.ZodString>;
+        artifacts: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        config: string;
+        artifacts: string;
+    }, {
+        config?: string | undefined;
+        artifacts?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    contracts: {
+        path: string;
+        default?: string | undefined;
+    };
+    frontend: {
+        framework: "vite-react" | "next" | "astro";
+        packageManager: "npm" | "pnpm" | "yarn" | "bun";
+    };
+    version: string;
+    name: string;
+    caatinga: {
+        compatibleCore: string;
+        templateVersion: number;
+    };
+    files: {
+        config: string;
+        artifacts: string;
+    };
+    description?: string | undefined;
+}, {
+    contracts: {
+        path: string;
+        default?: string | undefined;
+    };
+    frontend: {
+        framework: "vite-react" | "next" | "astro";
+        packageManager?: "npm" | "pnpm" | "yarn" | "bun" | undefined;
+    };
+    version: string;
+    name: string;
+    caatinga: {
+        compatibleCore: string;
+        templateVersion: number;
+    };
+    files: {
+        config?: string | undefined;
+        artifacts?: string | undefined;
+    };
+    description?: string | undefined;
+}>;
+type TemplateManifest = z.infer<typeof TemplateManifestSchema>;
+
+declare function isTransientTestnetSmokeFailure(logText: string): boolean;
+
+export { type BuildContractOptions, CAATINGA_CORE_VERSION, type CaatingaArtifacts, CaatingaArtifactsSchema, type CaatingaConfig, CaatingaConfigSchema, CaatingaError, CaatingaErrorCode, type ContractArtifact, type ContractConfig, type CreateProjectFromTemplateOptions, type DeployArgValue, type DeployContractOptions, type GenerateBindingsOptions, type InvokeContractOptions, type InvokeTarget, type LoadConfigOptions, type NetworkConfig, type ResolvedContract, type ResolvedNetwork, type RunCommandResult, STELLAR_CLI_MIN_VERSION, STELLAR_CLI_TESTED_MAX_VERSION, type TemplateManifest, TemplateManifestSchema, WELL_KNOWN_NETWORKS, assertSupportedStellarCliVersion, buildContract, buildDependencyGraph, checkBinary, createInitialArtifacts, createProjectFromTemplate, defineConfig, deployContract, deployContractGraph, generateBindings, invokeContract, isTransientTestnetSmokeFailure, loadConfig, parseContractId, parseInvokeTarget, parseStellarCliVersion, readArtifacts, resolveContract, resolveDeployArgs, resolveDeployOrder, resolveNetwork, runCommand, toCaatingaError, updateArtifact, writeArtifacts };