@legacychain/sdk/README.md

Official SDK for interacting with LegacyChain smart contracts and APIs

# LegacyChain SDK

Official TypeScript/JavaScript SDK for interacting with LegacyChain smart contracts and APIs.

## Features

- 🔐 **Time Capsules**: Create and manage time-locked content
- 💰 **Payment Capsules**: Time-locked cryptocurrency payments
- 📄 **Legal Documents**: Blockchain-verified legal documents with multi-signature support
- 🔒 **Encryption**: Client-side encryption for sensitive data
- 📊 **Analytics**: Comprehensive usage metrics and insights
- 🚀 **Rate Limiting**: Built-in rate limiting with freemium/paid tiers
- ⛓️ **Web3 Integration**: Seamless integration with Ethereum wallets

## Installation

```bash
npm install @legacychain/sdk
# or
yarn add @legacychain/sdk
```

## Quick Start

```typescript
import { LegacyChainClient } from '@legacychain/sdk';

// Initialize the SDK
const client = new LegacyChainClient({
  apiKey: 'your-api-key',
  network: 'mainnet', // or 'testnet'
  rpcUrl: 'https://your-rpc-url.com' // optional
});

// Connect wallet (browser only)
await client.connectWallet(window.ethereum);

// Create a time capsule
const capsule = await client.timeCapsules.create({
  title: 'My Time Capsule',
  description: 'A message for the future',
  content: 'Hello future!',
  unlockTime: new Date('2025-01-01'),
  encrypt: true
});
```

## Pricing Plans

### Free Tier
- 10 requests/minute
- 100 requests/hour  
- 500 requests/day
- 5 capsules/month
- 50MB storage
- Basic encryption

### Starter ($29/month)
- 30 requests/minute
- 500 requests/hour
- 5,000 requests/day
- 50 capsules/month
- 500MB storage
- Multi-signature support
- Webhooks

### Pro ($99/month)
- 100 requests/minute
- 2,000 requests/hour
- 20,000 requests/day
- 500 capsules/month
- 5GB storage
- Advanced analytics
- Custom branding
- Priority support

### Enterprise (Custom)
- Unlimited requests
- Unlimited capsules
- Unlimited storage
- All features
- SLA guarantee
- Dedicated support

## API Reference

### Time Capsules

```typescript
// Create a time capsule
const capsule = await client.timeCapsules.create({
  title: string,
  description: string,
  content: string | File | File[],
  unlockTime: Date,
  authorizedAddresses?: string[],
  encrypt?: boolean,
  password?: string
});

// Get a capsule
const capsule = await client.timeCapsules.get(capsuleId);

// List capsules
const { items, total } = await client.timeCapsules.list({
  page: 1,
  limit: 10,
  filters: {
    status: 'locked',
    createdAfter: new Date('2024-01-01')
  }
});

// Unlock a capsule
const content = await client.timeCapsules.unlock(capsuleId, password);
```

### Payment Capsules

```typescript
// Create a payment
const payment = await client.payments.create({
  recipient: '0x...',
  amount: '1.5',
  token: 'ETH', // or 'USDC', 'USDT', 'DAI'
  unlockTime: new Date('2025-01-01'),
  message: 'Happy New Year!',
  encrypt: true
});

// Claim a payment
await client.payments.claim(paymentId);

// Check balance
const balance = await client.payments.getBalance('ETH');
```

### Legal Documents

```typescript
// Create a legal document
const document = await client.legalDocuments.create({
  file: File,
  documentType: 'NDA', // or 'CONTRACT', 'WILL', 'AGREEMENT', 'CERTIFICATE'
  signers: ['0x...', '0x...'],
  requiredSignatures: 2,
  effectiveDate: new Date(),
  expiryDate: new Date('2025-12-31'),
  selfDestruct: {
    type: 'views',
    value: 100
  },
  encrypt: true
});

// Sign a document
const signature = await client.legalDocuments.generateSignature(documentId);
await client.legalDocuments.sign(documentId, signature);

// Download document
const blob = await client.legalDocuments.downloadDocument(document, password);
```

### Analytics

```typescript
// Get overview
const analytics = await client.analytics.getOverview();

// Get usage metrics
const usage = await client.analytics.getUsageMetrics();

// Track custom event
await client.analytics.trackEvent('document_viewed', {
  documentId: '123',
  viewerRole: 'signer'
});

// Export data
const csvBlob = await client.analytics.exportData('csv', 'all');
```

### Events

```typescript
// Listen to events
client.on('capsule:created', (capsule) => {
  console.log('New capsule created:', capsule);
});

client.on('payment:claimed', (paymentId) => {
  console.log('Payment claimed:', paymentId);
});

client.on('rateLimit:exceeded', (limits) => {
  console.log('Rate limit exceeded:', limits);
});
```

## Error Handling

```typescript
try {
  const capsule = await client.timeCapsules.create({...});
} catch (error) {
  if (error.code === 'RATE_LIMIT_EXCEEDED') {
    console.log('Rate limit hit, retry after:', error.details.retryAfter);
  } else if (error.code === 'INSUFFICIENT_STORAGE') {
    console.log('Storage limit reached');
  } else {
    console.error('Unexpected error:', error);
  }
}
```

## Environment Variables

```bash
# Required
NEXT_PUBLIC_LEGACY_NFT_ADDRESS=0x...
NEXT_PUBLIC_LEGACY_PAYMENTS_ADDRESS=0x...
NEXT_PUBLIC_LEGACY_LEGAL_DOCS_ADDRESS=0x...

# Optional
NEXT_PUBLIC_PINATA_JWT=your-pinata-jwt
NEXT_PUBLIC_RPC_URL=https://your-rpc.com
NEXT_PUBLIC_IPFS_GATEWAY=https://your-gateway.com/ipfs/
```

## TypeScript Support

The SDK is written in TypeScript and provides comprehensive type definitions:

```typescript
import { 
  TimeCapsule, 
  PaymentCapsule, 
  LegalDocument,
  PlanType,
  ApiResponse 
} from '@legacychain/sdk';
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Support

- Documentation: https://legacychain.net/docs
- Email: support@legacychain.net
- Discord: https://discord.gg/legacychain