import { InputDecl, InputSchema, OutputKind, TypedGuard, TypedLiteral, TypedRef } from "../types.js";
import { InputHandle, OutputHandle, ResourceInputHandle } from "./handles.js";
import { AppliedGuard, BindValue, Flow, Ref, Resource, SolType } from "@lifi/compose-spec";
/**
 * Arguments for calling an operation node in a flow.
 */
export interface CallArgs {
  /** Maps parameter names to input/output handles or raw `$ref` pointers. */
  readonly bind: Record<string, AnyBindable>;
  /** Optional operation-specific configuration. */
  readonly config?: object;
  /** Optional guards (e.g. slippage checks) applied to this operation's outputs. */
  readonly guards?: readonly TypedGuard[];
}
/**
 * Any value that can be bound to an operation parameter: an input handle, an
 * output handle from a previous operation, a typed `$ref` pointer, a typed
 * literal, or a bare `{ $ref }` pointer.
 *
 * This is the bind type of {@link FlowBuilderInternal.call}, the entry point
 * every generated operation lowers into — not a public authoring surface. A
 * bare `Ref` belongs here because a generated op resolves its own typed binds
 * to wire refs (`toBindRef` in `./signatureArgs.js`) before calling it. Typed
 * operation slots use `Bindable<T>`, which rejects a bare `Ref`; see
 * `RefBindable` in `./handles.js`.
 *
 * Use `raw.ref<T>()` to create a typed ref from a raw path string, and
 * `raw.literal<T>()` to bake in a constant.
 */
export type AnyBindable = InputHandle | OutputHandle | TypedRef | TypedLiteral | Ref;
/**
 * Provides references to runtime context values available inside a flow.
 * Access via `builder.context`.
 */
export interface ContextAccessor {
  /** A `$ref` pointing to the transaction sender (signer) address. */
  readonly sender: TypedRef<"address">;
  /** A `$ref` pointing to the on-chain execution (proxy) address. */
  readonly executionAddress: TypedRef<"address">;
}
type InputHandleOf<D extends InputDecl> = D extends Resource ? ResourceInputHandle : D extends SolType ? InputHandle<D> : InputHandle;
/**
 * A mapped type that converts an input schema into typed handles.
 * Resource inputs produce {@link ResourceInputHandle}; scalar inputs produce {@link InputHandle}.
 *
 * @typeParam T - The flow's input schema.
 */
export type InputHandles<T extends InputSchema> = { readonly [K in keyof T]: InputHandleOf<T[K]>; };
/**
 * Options for creating a new flow builder.
 *
 * @typeParam T - The flow's input schema.
 */
export interface FlowOptions<T extends InputSchema> {
  /** Optional human-readable name for the flow. Defaults to a random UUID. */
  readonly name?: string;
  /** Input declarations mapping names to resource or scalar types. */
  readonly inputs: T;
}
/**
 * A Flow document branded with its input schema for type-safe request building.
 *
 * The `__inputs` field is a phantom type — it exists only at compile time for
 * TypeScript inference and is never present at runtime.
 */
export type TypedFlow<T extends InputSchema = InputSchema> = Flow & {
  readonly __inputs?: T;
};
/**
 * Core flow builder interface providing low-level access to flow construction.
 *
 * For most use cases, prefer the {@link FlowBuilder} type returned by `sdk.flow()`
 * which adds generated operation methods and a `compile` method.
 *
 * @typeParam T - The flow's input schema.
 */
export interface FlowBuilderCore<T extends InputSchema = InputSchema> {
  /** Runtime context references (sender address, execution address). */
  readonly context: ContextAccessor;
  /** Typed handles for each declared flow input, used to bind inputs to operations. */
  readonly inputs: InputHandles<T>;
  /**
   * Appends an untyped operation node to the flow. This is an escape hatch
   * for operations not yet covered by the generated methods.
   *
   * Use `raw.ref<T>()` to reference this node's outputs in subsequent typed
   * operations.
   *
   * @param id - Unique node identifier within the flow.
   * @param op - The operation name (e.g. `"custom.vaultQuery"`).
   * @param args - Bind map, config, and optional guards for the node.
   * @throws Error if a node with the same `id` already exists in the flow.
   */
  readonly untypedOp: (id: string, op: string, args: {
    readonly bind: Record<string, BindValue>;
    readonly config: Record<string, unknown>;
    readonly guards?: readonly AppliedGuard[];
  }) => void;
  /** Serialises the builder state into a {@link TypedFlow} document. */
  readonly build: () => TypedFlow<T>;
}
/** Maps output port names to their output kind for compile-time and runtime validation. */
export type OutputSpec = Record<string, OutputKind>;
/**
 * Maps each output family's port name to the config key that sizes it: an
 * array (one instance per element) or a non-negative integer count.
 * A family port is also listed in the {@link OutputSpec}, as `'resource'`.
 */
export type FamilySpec = Readonly<Record<string, string>>;
/** The handles `call` returns for an {@link OutputSpec} and its families. */
export type OutputHandles<O extends OutputSpec, F extends FamilySpec> = { readonly [K in keyof O & string]: K extends keyof F ? readonly OutputHandle<"resource">[] : OutputHandle<O[K]>; };
/** Internal interface exposed to bindGeneratedOps — not part of the public API. */
export interface FlowBuilderInternal<T extends InputSchema = InputSchema> extends FlowBuilderCore<T> {
  readonly call: <O extends OutputSpec, F extends FamilySpec = Record<never, string>>(nodeId: string, op: string, args: CallArgs, outputs: O, families?: F) => OutputHandles<O, F>;
}
/**
 * Creates a new flow builder targeting the given chain.
 *
 * @param chainId - The EVM chain ID (e.g. `1` for Ethereum mainnet).
 * @param options - Flow configuration including input declarations.
 * @returns A {@link FlowBuilderInternal} instance.
 * @internal
 */
export declare const createFlowBuilderCore: <T extends InputSchema>(chainId: number, options: FlowOptions<T>) => FlowBuilderInternal<T>;
export {};