@lifi/composer-sdk/src/types.ts

Public Composer SDK for building and submitting flows

import type { Ref } from '@lifi/compose-spec';
import {
  InputSpec,
  MaterialiserInput,
  Resource,
  SolType,
} from '@lifi/compose-spec';

/**
 * A string that represents a non-negative integer (e.g. "1000000000").
 * Uses a template literal type so that only numeric-looking strings
 * are assignable at compile time.
 */
export type IntegerString = `${bigint}`;

/**
 * Accepted input for integer-string config fields.
 * Callers may pass either a numeric string ("1000000000") or a native bigint
 * (1000000000n). Bigint values are stringified automatically during JSON
 * serialization via the SDK's `bigintReplacer`.
 */
export type IntegerStringInput = IntegerString | bigint;

/**
 * A `0x`-prefixed hex string representing an Ethereum address.
 * Template literal type catches obviously wrong values at compile time.
 */
export type Address = `0x${string}`;

/** The universe of output port kinds: Solidity scalar types plus `'resource'`. */
export type OutputKind = SolType | 'resource';

/**
 * Maps an ABI parameter type string (from abitype's `ParseAbiItem`) to the
 * closest `OutputKind`. When the ABI type is one of the supported `SolType`
 * scalars, the mapping is exact; for all other Solidity types (e.g. tuples,
 * fixed-point decimals) it falls back to `SolType` — accepting any scalar
 * handle but not `'resource'` handles.
 *
 * The fallback excludes `'resource'` because every Solidity type is a scalar;
 * resource handles carry token-amount semantics that should only flow into
 * slots explicitly declared as resources.
 *
 * Extending `SolType` with new members automatically widens the exact-match
 * branch — no changes needed here.
 */
export type AbiTypeToOutputKind<T extends string> = T extends SolType
  ? T
  : SolType;

/**
 * A typed `$ref` pointer carrying a phantom type parameter.
 * Extends `Ref` so it is accepted anywhere a plain `Ref` is.
 * The `__outputKind` field is never set at runtime — it exists only
 * for TypeScript's structural type checker to distinguish typed refs.
 */
export interface TypedRef<T extends OutputKind = OutputKind> extends Ref {
  readonly __outputKind?: T;
}

/**
 * An input declaration in a flow schema.
 * `Resource` values become resource inputs (token amounts);
 * `SolType` strings become handle inputs (scalars like addresses).
 */
export type InputDecl = Resource | SolType;

/**
 * A record mapping input names to their declarations.
 * Used as the type parameter for generic flow builders and requests.
 */
export type InputSchema = Record<string, InputDecl>;

/**
 * Maps an input declaration to the allowed runtime value type.
 * Resource inputs accept materialisers or literal amounts.
 * Handle inputs accept the scalar type matching their SolType.
 */
export type InputSpecOf<D> = D extends Resource
  ? MaterialiserInput | IntegerStringInput
  : D extends 'address'
    ? Address
    : D extends 'bool'
      ? boolean
      : D extends `${'u' | ''}int${string}`
        ? IntegerStringInput
        : D extends `bytes${string}`
          ? `0x${string}`
          : D extends 'string'
            ? string
            : InputSpec;

/**
 * A guard applied to an operation, with the `port` field constrained
 * to a specific set of output port names.
 */
export interface TypedGuard<Port extends string = string> {
  readonly kind: string;
  readonly port: Port;
  readonly [key: string]: unknown;
}