@no-witness-labs/midday-sdk 0.2.0 → 0.2.2

package/dist/Client.d.ts

@@ -1,80 +1,223 @@
 /**
  * High-level client for interacting with Midnight Network contracts.
  *
- * Provides a simple API for deploying, joining, and calling contracts.
+ * ## API Design
+ *
+ * This module uses a **module-function pattern**:
+ *
+ * - **Stateless**: Functions operate on Client/Contract data
+ * - **Module functions**: `Client.contractFrom(client, options)`, `Contract.deploy(builder)`
+ * - **Data-oriented**: Client/Contract are plain data, not instances with methods
+ *
+ * ### Usage Patterns
+ *
+ * ```typescript
+ * // Promise user
+ * const client = await Client.create(config);
+ * const builder = await Client.contractFrom(client, { module });
+ * const contract = await ContractBuilder.deploy(builder);
+ * const result = await Contract.call(contract, 'increment');
+ *
+ * // Effect user
+ * const client = yield* Client.effect.create(config);
+ * const builder = yield* Client.effect.contractFrom(client, { module });
+ * const contract = yield* ContractBuilder.effect.deploy(builder);
+ * const result = yield* Contract.effect.call(contract, 'increment');
+ * ```
  *
  * @since 0.1.0
  * @module
  */
-import { type Logger } from 'pino';
+import { Context, Effect, Layer } from 'effect';
+import type { ZKConfigProvider, PrivateStateProvider } from '@midnight-ntwrk/midnight-js-types';
 import type { NetworkConfig } from './Config.js';
 import type { ContractProviders, StorageConfig } from './Providers.js';
 import type { WalletContext } from './Wallet.js';
+import type { WalletConnection } from './wallet/connector.js';
+declare const ClientError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ClientError";
+} & Readonly<A>;
+/**
+ * Error during client initialization or operation.
+ *
+ * @since 0.3.0
+ * @category errors
+ */
+export declare class ClientError extends ClientError_base<{
+    readonly cause: unknown;
+    readonly message: string;
+}> {
+}
+declare const ContractError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ContractError";
+} & Readonly<A>;
+/**
+ * Error during contract deployment or calls.
+ *
+ * @since 0.3.0
+ * @category errors
+ */
+export declare class ContractError extends ContractError_base<{
+    readonly cause: unknown;
+    readonly message: string;
+}> {
+}
+/**
+ * Logger interface for client operations.
+ *
+ * @since 0.2.0
+ * @category model
+ */
+export interface Logger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    debug(message: string): void;
+}
+/**
+ * Configuration for creating a client.
+ *
+ * @since 0.2.0
+ * @category model
+ */
 export interface ClientConfig {
     /** Network to connect to (default: 'local') */
     network?: string;
     /** Custom network configuration (overrides network preset) */
     networkConfig?: NetworkConfig;
-    /** Wallet seed (defaults to dev wallet for local) */
+    /** Wallet seed (required for non-local networks) */
     seed?: string;
+    /** ZK configuration provider (required) */
+    zkConfigProvider: ZKConfigProvider<string>;
+    /** Private state provider (required) */
+    privateStateProvider: PrivateStateProvider;
     /** Storage configuration */
     storage?: StorageConfig;
     /** Enable logging (default: true) */
     logging?: boolean;
 }
+/**
+ * Options for loading a contract.
+ *
+ * @since 0.2.0
+ * @category model
+ */
 export interface ContractFromOptions {
-    /**
-     * Base for path resolution:
-     * - undefined/'cwd': relative to process.cwd() (default)
-     * - 'project': relative to project root (finds package.json)
-     * - string (URL): relative to caller's import.meta.url
-     */
-    from?: string | 'project' | 'cwd';
+    /** Contract module (required in browser) */
+    module?: ContractModule;
+    /** URL to fetch ZK config from (for HttpZkConfigProvider) */
+    zkConfigUrl?: string;
     /** Witnesses for the contract */
     witnesses?: Record<string, unknown>;
-    /** Override privateStateId (defaults to directory name) */
+    /** Override privateStateId (defaults to contract name) */
     privateStateId?: string;
 }
+/**
+ * Options for deploying a contract.
+ *
+ * @since 0.2.0
+ * @category model
+ */
 export interface DeployOptions {
     /** Initial private state (defaults to {}) */
     initialPrivateState?: unknown;
 }
+/**
+ * Options for joining a contract.
+ *
+ * @since 0.2.0
+ * @category model
+ */
 export interface JoinOptions {
     /** Initial private state (defaults to {}) */
     initialPrivateState?: unknown;
 }
-export interface MidnightClient {
-    /** Raw wallet context for advanced use */
-    readonly wallet: WalletContext;
-    /** Network configuration */
-    readonly networkConfig: NetworkConfig;
-    /** Logger instance */
-    readonly logger: Logger;
-    /** Load a contract from a build directory path */
-    contractFrom(basePath: string, options?: ContractFromOptions): Promise<ContractBuilder>;
-    /** Wait for a transaction to be finalized on-chain by its hash */
-    waitForTx(txHash: string): Promise<FinalizedTxData>;
-}
+/**
+ * Data about a finalized transaction.
+ *
+ * @since 0.2.0
+ * @category model
+ */
 export interface FinalizedTxData {
     txHash: string;
     blockHeight: number;
     blockHash: string;
 }
-export interface ContractBuilder {
-    /** The loaded contract module */
-    readonly module: LoadedContractModule;
-    /** Deploy a new instance */
-    deploy(options?: DeployOptions): Promise<ConnectedContract>;
-    /** Join an existing deployed contract */
-    join(address: string, options?: JoinOptions): Promise<ConnectedContract>;
+/**
+ * A contract module definition.
+ *
+ * @since 0.2.0
+ * @category model
+ */
+export interface ContractModule {
+    Contract: new (witnesses: unknown) => unknown;
+    ledger: (state: unknown) => unknown;
 }
+/**
+ * A loaded contract module with configuration.
+ *
+ * @since 0.2.0
+ * @category model
+ */
 export interface LoadedContractModule {
     Contract: new (witnesses: unknown) => unknown;
     ledger: (state: unknown) => unknown;
-    zkConfigPath: string;
     privateStateId: string;
     witnesses: Record<string, unknown>;
 }
+/**
+ * Result of a contract call.
+ *
+ * @since 0.2.0
+ * @category model
+ */
+export interface CallResult {
+    txHash: string;
+    blockHeight: number;
+    status: string;
+}
+/**
+ * Represents a Midnight client.
+ *
+ * This is plain data - use module functions to operate on it.
+ *
+ * @since 0.2.0
+ * @category model
+ */
+export interface MidnightClient {
+    /** Raw wallet context for advanced use (null if using wallet connector) */
+    readonly wallet: WalletContext | null;
+    /** Network configuration */
+    readonly networkConfig: NetworkConfig;
+    /** Logger instance */
+    readonly logger: Logger;
+    /** Contract providers */
+    readonly providers: ContractProviders;
+}
+/**
+ * Represents a contract builder for deploying or joining contracts.
+ *
+ * This is plain data - use module functions to operate on it.
+ *
+ * @since 0.2.0
+ * @category model
+ */
+export interface ContractBuilder {
+    /** The loaded contract module */
+    readonly module: LoadedContractModule;
+    /** Contract providers */
+    readonly providers: ContractProviders;
+    /** Logger */
+    readonly logger: Logger;
+}
+/**
+ * Represents a connected contract.
+ *
+ * This is plain data - use module functions to operate on it.
+ *
+ * @since 0.2.0
+ * @category model
+ */
 export interface ConnectedContract {
     /** The deployed contract address */
     readonly address: string;
@@ -86,61 +229,390 @@ export interface ConnectedContract {
     readonly providers: ContractProviders;
     /** Logger */
     readonly logger: Logger;
-    /** Call a contract circuit - waits for transaction to be finalized */
-    call(action: string, ...args: unknown[]): Promise<CallResult>;
-    /** Query contract public state (raw) - latest */
-    state(): Promise<unknown>;
-    /** Query contract public state at specific block height (raw) */
-    stateAt(blockHeight: number): Promise<unknown>;
-    /** Query contract public state (parsed via ledger) - latest */
-    ledgerState(): Promise<unknown>;
-    /** Query contract public state at specific block height (parsed via ledger) */
-    ledgerStateAt(blockHeight: number): Promise<unknown>;
 }
-export interface CallResult {
-    txHash: string;
-    blockHeight: number;
-    status: string;
+declare function createEffect(config: ClientConfig): Effect.Effect<MidnightClient, ClientError>;
+declare function fromWalletEffect(connection: WalletConnection, config: {
+    zkConfigProvider: ZKConfigProvider<string>;
+    privateStateProvider: PrivateStateProvider;
+    logging?: boolean;
+}): Effect.Effect<MidnightClient, ClientError>;
+declare function contractFromEffect(client: MidnightClient, options: ContractFromOptions): Effect.Effect<ContractBuilder, ClientError>;
+declare function waitForTxEffect(client: MidnightClient, txHash: string): Effect.Effect<FinalizedTxData, ClientError>;
+/**
+ * Create a Midnight client for interacting with contracts using a seed.
+ *
+ * @example
+ * ```typescript
+ * const client = await Client.create({
+ *   seed: 'your-64-char-hex-seed',
+ *   networkConfig: Config.NETWORKS.local,
+ *   zkConfigProvider,
+ *   privateStateProvider,
+ * });
+ * ```
+ *
+ * @since 0.2.0
+ * @category constructors
+ */
+export declare function create(config: ClientConfig): Promise<MidnightClient>;
+/**
+ * Create a Midnight client from a connected wallet (browser).
+ *
+ * @since 0.2.0
+ * @category constructors
+ */
+export declare function fromWallet(connection: WalletConnection, config: {
+    zkConfigProvider: ZKConfigProvider<string>;
+    privateStateProvider: PrivateStateProvider;
+    logging?: boolean;
+}): Promise<MidnightClient>;
+/**
+ * Load a contract module for a client.
+ *
+ * @example
+ * ```typescript
+ * const builder = await Client.contractFrom(client, {
+ *   module: await import('./contracts/counter/index.js'),
+ * });
+ * ```
+ *
+ * @since 0.2.0
+ * @category operations
+ */
+export declare function contractFrom(client: MidnightClient, options: ContractFromOptions): Promise<ContractBuilder>;
+/**
+ * Wait for a transaction to be finalized.
+ *
+ * @since 0.2.0
+ * @category operations
+ */
+export declare function waitForTx(client: MidnightClient, txHash: string): Promise<FinalizedTxData>;
+/**
+ * Raw Effect APIs for advanced users.
+ *
+ * @example
+ * ```typescript
+ * const client = yield* Client.effect.create(config);
+ * const builder = yield* Client.effect.contractFrom(client, { module });
+ * ```
+ *
+ * @since 0.2.0
+ * @category effect
+ */
+export declare const effect: {
+    create: typeof createEffect;
+    fromWallet: typeof fromWalletEffect;
+    contractFrom: typeof contractFromEffect;
+    waitForTx: typeof waitForTxEffect;
+};
+declare function deployEffect(builder: ContractBuilder, options?: DeployOptions): Effect.Effect<ConnectedContract, ContractError>;
+declare function joinEffect(builder: ContractBuilder, address: string, options?: JoinOptions): Effect.Effect<ConnectedContract, ContractError>;
+/**
+ * ContractBuilder module functions.
+ *
+ * @since 0.2.0
+ * @category ContractBuilder
+ */
+export declare const ContractBuilder: {
+    /**
+     * Deploy a new contract instance.
+     *
+     * @example
+     * ```typescript
+     * const contract = await ContractBuilder.deploy(builder);
+     * ```
+     *
+     * @since 0.2.0
+     * @category lifecycle
+     */
+    deploy: (builder: ContractBuilder, options?: DeployOptions) => Promise<ConnectedContract>;
+    /**
+     * Join an existing contract.
+     *
+     * @example
+     * ```typescript
+     * const contract = await ContractBuilder.join(builder, '0x...');
+     * ```
+     *
+     * @since 0.2.0
+     * @category lifecycle
+     */
+    join: (builder: ContractBuilder, address: string, options?: JoinOptions) => Promise<ConnectedContract>;
+    /**
+     * Raw Effect APIs for ContractBuilder.
+     *
+     * @since 0.2.0
+     * @category effect
+     */
+    effect: {
+        deploy: typeof deployEffect;
+        join: typeof joinEffect;
+    };
+};
+declare function callEffect(contract: ConnectedContract, action: string, ...args: unknown[]): Effect.Effect<CallResult, ContractError>;
+declare function stateEffect(contract: ConnectedContract): Effect.Effect<unknown, ContractError>;
+declare function stateAtEffect(contract: ConnectedContract, blockHeight: number): Effect.Effect<unknown, ContractError>;
+declare function ledgerStateEffect(contract: ConnectedContract): Effect.Effect<unknown, ContractError>;
+declare function ledgerStateAtEffect(contract: ConnectedContract, blockHeight: number): Effect.Effect<unknown, ContractError>;
+/**
+ * Contract module functions.
+ *
+ * @since 0.2.0
+ * @category Contract
+ */
+export declare const Contract: {
+    /**
+     * Call a contract action.
+     *
+     * @example
+     * ```typescript
+     * const result = await Contract.call(contract, 'increment');
+     * ```
+     *
+     * @since 0.2.0
+     * @category operations
+     */
+    call: (contract: ConnectedContract, action: string, ...args: unknown[]) => Promise<CallResult>;
+    /**
+     * Get contract state.
+     *
+     * @since 0.2.0
+     * @category inspection
+     */
+    state: (contract: ConnectedContract) => Promise<unknown>;
+    /**
+     * Get contract state at a specific block height.
+     *
+     * @since 0.2.0
+     * @category inspection
+     */
+    stateAt: (contract: ConnectedContract, blockHeight: number) => Promise<unknown>;
+    /**
+     * Get ledger state (parsed through ledger function).
+     *
+     * @since 0.2.0
+     * @category inspection
+     */
+    ledgerState: (contract: ConnectedContract) => Promise<unknown>;
+    /**
+     * Get ledger state at a specific block height.
+     *
+     * @since 0.2.0
+     * @category inspection
+     */
+    ledgerStateAt: (contract: ConnectedContract, blockHeight: number) => Promise<unknown>;
+    /**
+     * Raw Effect APIs for Contract.
+     *
+     * @since 0.2.0
+     * @category effect
+     */
+    effect: {
+        call: typeof callEffect;
+        state: typeof stateEffect;
+        stateAt: typeof stateAtEffect;
+        ledgerState: typeof ledgerStateEffect;
+        ledgerStateAt: typeof ledgerStateAtEffect;
+    };
+};
+/**
+ * Service interface for Client operations.
+ *
+ * @since 0.2.0
+ * @category service
+ */
+export interface ClientServiceImpl {
+    readonly create: (config: ClientConfig) => Effect.Effect<MidnightClient, ClientError>;
+    readonly fromWallet: (connection: WalletConnection, config: {
+        zkConfigProvider: ZKConfigProvider<string>;
+        privateStateProvider: PrivateStateProvider;
+        logging?: boolean;
+    }) => Effect.Effect<MidnightClient, ClientError>;
+    readonly contractFrom: (client: MidnightClient, options: ContractFromOptions) => Effect.Effect<ContractBuilder, ClientError>;
+    readonly waitForTx: (client: MidnightClient, txHash: string) => Effect.Effect<FinalizedTxData, ClientError>;
 }
+declare const ClientService_base: Context.TagClass<ClientService, "ClientService", ClientServiceImpl>;
 /**
- * Create a Midnight client for interacting with contracts
+ * Context.Tag for ClientService dependency injection.
  *
  * @example
  * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const clientService = yield* ClientService;
+ *   const client = yield* clientService.create(config);
+ *   return client;
+ * });
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(ClientLive)));
+ * ```
+ *
+ * @since 0.2.0
+ * @category service
+ */
+export declare class ClientService extends ClientService_base {
+}
+/**
+ * Service interface for ContractBuilder operations.
+ *
+ * @since 0.2.0
+ * @category service
+ */
+export interface ContractBuilderServiceImpl {
+    readonly deploy: (builder: ContractBuilder, options?: DeployOptions) => Effect.Effect<ConnectedContract, ContractError>;
+    readonly join: (builder: ContractBuilder, address: string, options?: JoinOptions) => Effect.Effect<ConnectedContract, ContractError>;
+}
+declare const ContractBuilderService_base: Context.TagClass<ContractBuilderService, "ContractBuilderService", ContractBuilderServiceImpl>;
+/**
+ * Context.Tag for ContractBuilderService dependency injection.
+ *
+ * @since 0.2.0
+ * @category service
+ */
+export declare class ContractBuilderService extends ContractBuilderService_base {
+}
+/**
+ * Service interface for Contract operations.
+ *
+ * @since 0.2.0
+ * @category service
+ */
+export interface ContractServiceImpl {
+    readonly call: (contract: ConnectedContract, action: string, ...args: unknown[]) => Effect.Effect<CallResult, ContractError>;
+    readonly state: (contract: ConnectedContract) => Effect.Effect<unknown, ContractError>;
+    readonly stateAt: (contract: ConnectedContract, blockHeight: number) => Effect.Effect<unknown, ContractError>;
+    readonly ledgerState: (contract: ConnectedContract) => Effect.Effect<unknown, ContractError>;
+    readonly ledgerStateAt: (contract: ConnectedContract, blockHeight: number) => Effect.Effect<unknown, ContractError>;
+}
+declare const ContractService_base: Context.TagClass<ContractService, "ContractService", ContractServiceImpl>;
+/**
+ * Context.Tag for ContractService dependency injection.
+ *
+ * @since 0.2.0
+ * @category service
+ */
+export declare class ContractService extends ContractService_base {
+}
+/**
+ * Live Layer for ClientService.
+ *
+ * @since 0.2.0
+ * @category layer
+ */
+export declare const ClientLive: Layer.Layer<ClientService>;
+/**
+ * Live Layer for ContractBuilderService.
+ *
+ * @since 0.2.0
+ * @category layer
+ */
+export declare const ContractBuilderLive: Layer.Layer<ContractBuilderService>;
+/**
+ * Live Layer for ContractService.
+ *
+ * @since 0.2.0
+ * @category layer
+ */
+export declare const ContractLive: Layer.Layer<ContractService>;
+/**
+ * Create a Layer providing all Client-related factory services.
+ *
+ * Use this when you want to create clients on-demand within your Effect programs.
+ * For pre-initialized clients, use `Client.layer(config)` instead.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect';
  * import * as Midday from '@no-witness-labs/midday-sdk';
  *
- * // Simple - local network with dev wallet
- * const client = await Midday.Client.create();
+ * const program = Effect.gen(function* () {
+ *   const clientService = yield* Midday.ClientService;
+ *   const client = yield* clientService.create(config);
+ *   return client;
+ * });
+ *
+ * await Effect.runPromise(program.pipe(Effect.provide(Midday.Client.services())));
+ * ```
  *
- * // Custom seed
- * const client = await Midday.Client.create({
- *   seed: 'your-64-char-hex-seed'
+ * @since 0.3.0
+ * @category layer
+ */
+export declare function services(): Layer.Layer<ClientService | ContractBuilderService | ContractService>;
+declare const MidnightClientService_base: Context.TagClass<MidnightClientService, "MidnightClientService", MidnightClient>;
+/**
+ * Context.Tag for a pre-initialized MidnightClient.
+ *
+ * Use with `Client.layer(config)` for dependency injection of a configured client.
+ *
+ * @since 0.3.0
+ * @category service
+ */
+export declare class MidnightClientService extends MidnightClientService_base {
+}
+/**
+ * Create a Layer that provides a pre-initialized MidnightClient.
+ *
+ * This is the recommended way to inject a client into Effect programs
+ * when you have a known configuration at startup. Follows the same pattern
+ * as `Cluster.layer(config)`.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect';
+ * import * as Midday from '@no-witness-labs/midday-sdk';
+ *
+ * const clientLayer = Midday.Client.layer({
+ *   seed: 'your-64-char-hex-seed',
+ *   networkConfig: Midday.Config.NETWORKS.local,
+ *   zkConfigProvider: new Midday.HttpZkConfigProvider('http://localhost:3000/zk'),
+ *   privateStateProvider: Midday.inMemoryPrivateStateProvider(),
  * });
  *
- * // Custom network endpoints via env vars or config
- * const client = await Midday.Client.create({
- *   networkConfig: {
- *     networkId: 'testnet',
- *     indexer: 'https://indexer.testnet.midnight.network/graphql',
- *     indexerWS: 'wss://indexer.testnet.midnight.network/graphql/ws',
- *     node: 'wss://node.testnet.midnight.network',
- *     proofServer: 'https://proof.testnet.midnight.network',
- *   }
+ * const program = Effect.gen(function* () {
+ *   const client = yield* Midday.MidnightClientService;
+ *   const builder = yield* Midday.Client.effect.contractFrom(client, { module });
+ *   return builder;
  * });
  *
- * // Load and deploy a contract
- * const counter = await (await client.contractFrom('build/simple-counter')).deploy();
+ * await Effect.runPromise(program.pipe(Effect.provide(clientLayer)));
+ * ```
+ *
+ * @since 0.3.0
+ * @category layer
+ */
+export declare function layer(config: ClientConfig): Layer.Layer<MidnightClientService, ClientError>;
+/**
+ * Create a Layer that provides a pre-initialized MidnightClient from a wallet connection.
+ *
+ * Use this for browser environments with Lace wallet integration.
  *
- * // Call actions
- * await counter.call('increment');
+ * @example
+ * ```typescript
+ * import { Effect } from 'effect';
+ * import * as Midday from '@no-witness-labs/midday-sdk';
  *
- * // Read state
- * const state = await counter.ledgerState();
- * console.log(state.counter);
+ * // After connecting wallet
+ * const connection = await Midday.connectWallet('testnet');
  *
- * // Join existing contract
- * const existing = await (await client.contractFrom('build/simple-counter')).join(address);
+ * const clientLayer = Midday.Client.layerFromWallet(connection, {
+ *   zkConfigProvider: new Midday.HttpZkConfigProvider('https://cdn.example.com/zk'),
+ *   privateStateProvider: Midday.indexedDBPrivateStateProvider({ privateStateStoreName: 'my-app' }),
+ * });
+ *
+ * const program = Effect.gen(function* () {
+ *   const client = yield* Midday.MidnightClientService;
+ *   // Use client...
+ * });
+ *
+ * await Effect.runPromise(program.pipe(Effect.provide(clientLayer)));
  * ```
+ *
+ * @since 0.3.0
+ * @category layer
  */
-export declare function create(config?: ClientConfig): Promise<MidnightClient>;
+export declare function layerFromWallet(connection: WalletConnection, config: {
+    zkConfigProvider: ZKConfigProvider<string>;
+    privateStateProvider: PrivateStateProvider;
+    logging?: boolean;
+}): Layer.Layer<MidnightClientService, ClientError>;
+export {};
 //# sourceMappingURL=Client.d.ts.map