npm package: @relayerfi/action-kit
Description: Action Kit for Relayer.fi
Author: Relayer.fi
Latest version: 0.1.0

# @relayerfi/action-kit

[![npm version](https://img.shields.io/npm/v/@relayerfi/action-kit.svg)](https://www.npmjs.com/package/@relayerfi/action-kit)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.6%2B-blue)](https://www.typescriptlang.org/)

TypeScript SDK for defining on-chain actions as structured metadata. Part of the [Relayer](https://relayer.fi) infrastructure stack.

Action Kit lets integrators declare **what** a widget does (transfer tokens, call a contract, run a multi-step flow) without coupling to any rendering layer. The metadata is consumed by `@relayerfi/widget-kit-core` and `@relayerfi/widget-kit-react` to produce interactive UI.

## Install

```bash
pnpm add @relayerfi/action-kit viem
```

`viem` is a required peer dependency.

## Usage

### Transfer Action

```typescript
import { createMetadata, type Metadata } from '@relayerfi/action-kit';

const metadata: Metadata = {
  url: 'https://myapp.example',
  icon: 'https://example.com/icon.png',
  title: 'Send AVAX',
  description: 'Transfer 0.1 AVAX',
  actions: [
    {
      type: 'transfer',
      label: 'Send 0.1 AVAX',
      to: '0x1234...5678',
      amount: 0.1,
      chains: { source: 43114 },
    },
  ],
};

const validated = createMetadata(metadata);
```

### Blockchain Action (Contract Call)

```typescript
const metadata: Metadata = {
  url: 'https://myapp.example',
  icon: 'https://example.com/icon.png',
  title: 'Approve USDC',
  description: 'Approve spender',
  actions: [
    {
      type: 'blockchain',
      label: 'Approve',
      address: '0xA0b86a33E6417C8D7648D5b1D6fF0F6dB6c15b2a',
      abi: [/* ERC-20 approve ABI */],
      functionName: 'approve',
      chains: { source: 1 },
      params: [
        { name: 'spender', type: 'address', value: '0x...', fixed: true },
        { name: 'amount', type: 'number', required: true },
      ],
    },
  ],
};
```

## Action Types

| Type | Purpose |
|------|---------|
| `transfer` | Native token or ERC-20 transfers |
| `blockchain` | Smart contract read/write calls |
| `http` | Server-side form submissions and API calls |
| `dynamic` | Runtime-generated actions with server logic |
| `flow` | Multi-step nested action workflows |

## Validation

```typescript
import { validateMetadata } from '@relayerfi/action-kit';

const result = validateMetadata(metadata);
if (!result.isValid) {
  console.error(result.errors);
}
```

## Supported Chains

Ethereum, Avalanche, Base, Celo, Mantle (mainnets + testnets). See `src/interface/chains.ts` for the full list.

## API

### Core

- `createMetadata(metadata)` - Validate and process action metadata
- `validateMetadata(input)` - Validate with detailed error reporting

### Type Guards

- `isBlockchainActionMetadata(action)`
- `isTransferAction(action)`
- `isHttpAction(action)`
- `isActionFlow(obj)`
- `isDynamicAction(action)`

### Executors

- `Executor` - Base executor for proxy communication
- `DynamicActionExecutor` - Execute dynamic actions with server-side logic

## Related Packages

| Package | Purpose |
|---------|---------|
| [`@relayerfi/widget-kit-core`](https://www.npmjs.com/package/@relayerfi/widget-kit-core) | Framework-agnostic runtime (directory, metadata fetching, security) |
| [`@relayerfi/widget-kit-react`](https://www.npmjs.com/package/@relayerfi/widget-kit-react) | React components for rendering widgets |

## License

MIT