import { AppliedGuard, SolType } from '@lifi/compose-spec';
import { TypedLiteral, OutputKind, TypedRef } from '../types.js';

/**
 * Creates a typed `$ref` pointer for use in bind slots.
 *
 * This is an **escape hatch** for referencing values that the typed builder
 * API doesn't cover — for example, outputs of an `untypedOp` node or custom
 * context paths. The caller is responsible for choosing the correct type
 * parameter; no runtime validation occurs.
 *
 * Prefer typed handles (`OutputHandle`, `InputHandle`) and `builder.context`
 * whenever possible. Use `ref` only when you need to construct a `$ref` path
 * manually and want it accepted by a `Bindable<T>` slot.
 *
 * @typeParam T - The output kind this ref represents (e.g. `'address'`, `'uint256'`, `'resource'`).
 * @param path - The `$ref` path (e.g. `"context.sender"`, `"myNode.result"`).
 * @returns A {@link TypedRef} accepted by `Bindable<T>` slots matching `T`.
 *
 * @example
 * ```ts
 * import { raw } from '@lifi/composer-sdk';
 *
 * // Reference an untypedOp output in a typed operation:
 * builder.untypedOp('custom', 'some.op', {
 *   bind: { x: { $ref: 'input.token' } },
 *   config: {},
 * });
 * builder.core.add('sum', {
 *   bind: {
 *     a: raw.ref<'uint256'>('custom.result'),
 *     b: someTypedHandle,
 *   },
 * });
 * ```
 */
declare const ref: <T extends OutputKind>(path: string) => TypedRef<T>;
/**
 * Creates a typed literal for use in bind slots: a constant baked into the
 * flow document rather than supplied at run time.
 *
 * Prefer a declared flow input and `builder.inputs.<name>` — a value the
 * caller supplies per run stays out of the document. Use a literal when the
 * flow has no run of its own to take the value from: the `continuationFlow`
 * of a `continuation.settle` node is stored by the settlement backend and
 * re-run later against the deferred proceeds, so its delivery address has to
 * be part of the committed document.
 *
 * @typeParam T - The Solidity type of the literal (e.g. `'address'`).
 * @param kind - The literal's Solidity type.
 * @param value - The literal value, as the wire format carries it: a string.
 * @returns A {@link TypedLiteral} accepted by `Bindable<T>` slots matching `T`.
 *
 * @example
 * ```ts
 * import { raw } from '@lifi/composer-sdk';
 *
 * builder.core.transfer('deliver', {
 *   bind: {
 *     amount: zap.amountOut,
 *     recipient: raw.literal('address', '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'),
 *   },
 *   config: {},
 * });
 * ```
 */
declare const literal: <T extends SolType>(kind: T, value: string) => TypedLiteral<T>;
/**
 * Creates a raw guard object for use in the `guards` array of an operation call.
 *
 * @param kind - The guard type (e.g. `"slippage"`).
 * @param config - Guard-specific configuration (e.g. `{ toleranceBps: 300 }`).
 * @returns An {@link AppliedGuard} object.
 */
declare const rawGuard: (kind: string, config?: Record<string, unknown>) => AppliedGuard;

export { literal, rawGuard, ref };