npm package: @moveflow-dev/moveflow-evm-sdk
Description: TypeScript SDK for Moveflow EVM payment streaming protocol
Author: Moveflow
Latest version: 1.0.1

# Moveflow SDK (EVM)

A comprehensive TypeScript SDK for interacting with the Moveflow payment streaming protocol on EVM-compatible networks.

## Features

- 🚀 **Easy Integration**: Simple, intuitive API for payment streaming
- 🏗️ **Type Safety**: Full TypeScript support with comprehensive type definitions
- 🔧 **Multi-Network Support**: Built-in support for multiple EVM networks
- ⚡ **Batch Operations**: Efficient batch processing for multiple streams
- 📊 **Real-time Monitoring**: Event listeners and stream tracking
- 💰 **Token Management**: Built-in ERC20 token utilities

## Installation

```bash
npm install moveflow-sdk-evm
# or
yarn add moveflow-sdk-evm
# or
pnpm add moveflow-sdk-evm
```

## Quick Start

### Basic Usage

```typescript
import { MoveflowSDK } from 'moveflow-sdk-evm';

// Initialize SDK
const sdk = MoveflowSDK.create('edu_mainnet');

// Get stream details
const stream = await sdk.streamClient.getStream('123');
console.log('Stream:', stream);

// Get user streams
const userStreams = await sdk.streamClient.getRecipientStreams('0x...');
```

### Create a Stream

```typescript
import { MoveflowSDK } from 'moveflow-sdk-evm';
import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider('https://rpc.edu-chain.raas.gelato.cloud');
const signer = new ethers.Wallet('your-private-key', provider);

const sdk = new MoveflowSDK({
  network: 'edu_mainnet',
  signer,
});

// Create a simple payment stream
const streamId = await sdk.createSimpleStream({
  sender: await signer.getAddress(),
  recipient: '0xrecipient-address',
  deposit: ethers.parseUnits('1000', 6), // 1000 USDC
  tokenAddress: '0xA0b86a33E6441b171DFe8AB681D8f0Bc3c3ceAE5', // USDC
  startTime: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
  stopTime: Math.floor(Date.now() / 1000) + 86400 * 30, // 30 days
  interval: 86400, // Daily payments
});

console.log('Stream created:', streamId);
```

## API Reference

### MoveflowSDK

The main SDK class that provides high-level access to all functionality.

#### Constructor

```typescript
const sdk = new MoveflowSDK({
  network: 'edu_mainnet',
  provider?, // Optional: ethers.JsonRpcProvider
  signer?,   // Optional: ethers.Signer
  customNetworkConfig? // Optional: Custom network configuration
});
```

#### Factory Methods

```typescript
// Create with default provider
const sdk = MoveflowSDK.create('edu_mainnet');

// Create with custom provider
const sdk = MoveflowSDK.withProvider('edu_mainnet', provider);

// Create with signer
const sdk = MoveflowSDK.withSigner('edu_mainnet', signer);
```

### StreamClient

Handles all stream-related operations.

#### Create Streams

```typescript
// Single stream
const streamId = await sdk.streamClient.createStream({
  sender: '0x...',
  recipient: '0x...',
  deposit: ethers.parseUnits('1000', 6),
  tokenAddress: '0x...',
  startTime: 1234567890,
  stopTime: 1234567890,
  interval: 86400,
  cliffAmount: 0,
  cliffTime: 0,
  autoWithdrawInterval: 0,
  autoWithdraw: false,
  pauseable: 1,
  closeable: 1,
  recipientModifiable: 0,
});

// Batch create streams
const streamIds = await sdk.streamClient.batchCreateStreams([
  { /* stream params */ },
  { /* stream params */ }
]);
```

#### Manage Streams

```typescript
// Close stream
await sdk.streamClient.closeStream(streamId);

// Pause/Resume streams
await sdk.streamClient.pauseStream(streamId);
await sdk.streamClient.resumeStream(streamId);

// Extend stream duration
await sdk.streamClient.extendStream(streamId, newStopTime);

// Change recipient
await sdk.streamClient.setNewRecipient(streamId, newRecipient);

// Withdraw funds
await sdk.streamClient.withdrawFromStream(streamId);
```

#### Get Stream Information

```typescript
// Get single stream
const stream = await sdk.streamClient.getStream(streamId);

// Get balance in stream
const balance = await sdk.streamClient.balanceOf(streamId, address);

// Get streams by filter
const senderStreams = await sdk.streamClient.getSenderStreams(senderAddress);
const recipientStreams = await sdk.streamClient.getRecipientStreams(recipientAddress);
const activeStreams = await sdk.streamClient.getActiveStreams();
```

### TokenClient

Handles ERC20 token operations.

```typescript
// Get token information
const tokenInfo = await sdk.tokenClient.getTokenInfo(tokenAddress);

// Get balance
const balance = await sdk.tokenClient.getBalance(tokenAddress, address);

// Check allowance
const allowance = await sdk.tokenClient.getAllowance(tokenAddress, owner, spender);

// Approve tokens
const tx = await sdk.tokenClient.approve(tokenAddress, spender, amount);

// Transfer tokens
const tx = await sdk.tokenClient.transfer(tokenAddress, recipient, amount);
```

## Network Configuration

### Supported Networks

- **edu_mainnet**: Open Campus mainnet
- **arbitrum_mainnet**: Arbitrum One

### Custom Networks

```typescript
const customConfig = {
  name: 'custom_network',
  chainId: '12345',
  StreamProxy: '0x...',
  StreamGatewayProxy: '0x...',
};

const sdk = new MoveflowSDK({
  network: 'custom_network',
  customNetworkConfig: customConfig,
});
```

## Error Handling

All methods include proper error handling and validation:

```typescript
try {
  const validation = await sdk.validateCreateStreamParams(params);
  if (!validation.valid) {
    console.error('Validation errors:', validation.errors);
    return;
  }
  
  const streamId = await sdk.createSimpleStream(params);
} catch (error) {
  console.error('Error creating stream:', error);
}
```

## Batch Operations

Efficiently handle multiple streams:

```typescript
// Batch create
const streamIds = await sdk.streamClient.batchCreateStreams([params1, params2, params3]);

// Batch close
await sdk.streamClient.batchCloseStreams(['1', '2', '3']);

// Batch pause/resume
await sdk.streamClient.batchPauseStreams(['1', '2', '3']);
await sdk.streamClient.batchResumeStreams(['1', '2', '3']);

// Batch withdraw
await sdk.streamClient.batchWithdrawFromStreams(['1', '2', '3']);
```

## Event Monitoring

Listen for contract events:

```typescript
// Listen for stream creation
sdk.streamClient.onCreateStream((streamId, sender, recipient, deposit) => {
  console.log('New stream created:', streamId);
});

// Listen for token transfers
sdk.tokenClient.onTransfer(tokenAddress, (from, to, value) => {
  console.log('Token transfer:', from, '→', to, value);
});
```

## Examples

Check the `examples/` directory for complete usage examples:

- `basic-usage.ts` - Basic SDK initialization and queries
- `create-stream.ts` - Creating payment streams
- `batch-operations.ts` - Batch operations example
- `monitoring.ts` - Event monitoring and real-time updates

## Development

### Building

```bash
npm run build
```

### Testing

```bash
npm test
```

### Development Mode

```bash
npm run dev
```

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions, please visit our [GitHub repository](https://github.com/moveflow/sdk-evm).