@lifi/composer-sdk/src/authoring/raw.ts

Public Composer SDK for building and submitting flows

import type { AppliedGuard } from '@lifi/compose-spec';

import type { 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,
 *   },
 * });
 * ```
 */
export const ref = <T extends OutputKind>(path: string): TypedRef<T> =>
  ({ $ref: path }) as TypedRef<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.
 */
export const rawGuard = (
  kind: string,
  config: Record<string, unknown> = {},
): AppliedGuard => {
  if ('kind' in config) {
    throw new Error(
      `rawGuard: 'kind' must not appear in config (got "${String(
        config.kind,
      )}"). Pass it as the first argument instead.`,
    );
  }
  return { ...config, kind };
};