@efe136/legacychain-sdk/README.md

Official SDK for interacting with LegacyChain smart contracts and APIs

# LegacyChain SDK

Official TypeScript SDK for interacting with LegacyChain smart contracts and services.

[![npm version](https://badge.fury.io/js/%40efe136%2Flegacychain-sdk.svg)](https://www.npmjs.com/package/@efe136/legacychain-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🚀 New in v1.1.0

- ✨ **Multi-signature support** - Collaborative capsule management with threshold-based signing
- 🪝 **Webhooks** - Real-time event notifications for all capsule activities  
- 📊 **Advanced Analytics** - AI-powered insights, custom dashboards, retention analytics (Pro+)
- 🎨 **Custom Branding** - White-label your integration with custom logos and colors (Pro+)
- 🎯 **Priority Support** - Tiered support with SLA guarantees for Enterprise

## Installation

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

## Quick Start

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

// Initialize the SDK
const client = new LegacyChainClient({
  apiKey: 'your-api-key',
  network: 'mainnet' // or 'testnet'
});

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

// Set up webhooks for notifications
const webhook = await client.webhooks.create({
  url: 'https://your-app.com/webhook',
  events: ['capsule.created', 'capsule.unlocked']
});
```

## Features

### 📦 Time Capsules
Create and manage time-locked digital content:

```typescript
// Create a capsule
const capsule = await client.timeCapsules.create({
  title: 'Future Message',
  content: 'Secret message',
  unlockTime: new Date('2030-01-01'),
  authorizedAddresses: ['0x...'], // Optional: specific addresses that can unlock
  encrypt: true,
  password: 'optional-password'
});

// List your capsules
const myCapsules = await client.timeCapsules.list({
  owner: '0xYourAddress'
});

// Unlock a capsule (when time has passed)
const unlockedContent = await client.timeCapsules.unlock(capsuleId);
```

### 💰 Payment Capsules
Send time-locked payments:

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

### 📄 Legal Documents
Create legally binding documents with multi-signature:

```typescript
const document = await client.legalDocuments.create({
  file: documentFile,
  documentType: 'CONTRACT',
  signers: ['0xSigner1', '0xSigner2'],
  requiredSignatures: 2,
  selfDestruct: {
    type: 'time',
    value: new Date('2026-01-01')
  }
});
```

### 🎨 Specialized NFT Capsules (New!)
Create advanced NFT capsules with unique unlocking mechanisms:

#### 🎬 Film Capsules
Time-locked exclusive films and video content:
```typescript
const filmCapsule = await client.specializedCapsules.createFilmCapsule({
  recipient: '0xRecipient',
  title: 'The Lost Chapter',
  director: 'Christopher Nolan',
  premiereDate: new Date('2025-12-25'),
  trailerURI: 'ipfs://QmTrailer',
  encryptedFilmURI: 'ipfs://QmEncryptedFilm'
});
```

#### 📝 Creator Message Capsules
Hidden messages from creators revealed to NFT buyers:
```typescript
const messageCapsule = await client.specializedCapsules.createCreatorMessageCapsule({
  recipient: '0xCollector',
  creator: 'Banksy',
  message: 'The story behind this piece...',
  publicTeaser: 'What inspired this artwork?',
  revealTime: new Date('2024-12-01'),
  encrypt: true
});
```

#### 🧬 Mystery Trait Capsules
NFTs with evolving traits that unlock over time:
```typescript
const traitCapsule = await client.specializedCapsules.createMysteryTraitCapsule({
  recipient: '0xPlayer',
  name: 'Shadow Warrior',
  hiddenTraits: ['Legendary Sword', 'Dragon Armor', 'Phoenix Pet'],
  unlockTimes: [
    new Date('2024-02-01'),
    new Date('2024-03-01'),
    new Date('2024-04-01')
  ]
});
```

#### 💎 VIP Access Capsules
NFTs granting exclusive access to events and content:
```typescript
const vipCapsule = await client.specializedCapsules.createVIPAccessCapsule({
  recipient: '0xFan',
  eventId: 'metaverse-concert-2024',
  description: 'Backstage access to Travis Scott concert',
  encryptedAccessData: 'encrypted-url-and-code',
  expiryTime: new Date('2024-12-31'),
  usageLimit: 1
});
```

#### 📜 Art Provenance Capsules
Artwork that reveals new layers over time:
```typescript
const artCapsule = await client.specializedCapsules.createArtProvenanceCapsule({
  recipient: '0xCollector',
  artist: 'Digital Picasso',
  baseArtworkURI: 'ipfs://QmBaseArt',
  layerURIs: ['ipfs://QmLayer1', 'ipfs://QmLayer2'],
  layerDescriptions: ['The beginning...', 'The revelation...'],
  revealTimes: [new Date('2024-06-01'), new Date('2024-12-01')]
});
```

#### More Capsule Types
- 🗳️ **Voting Capsules**: DAO governance with time-based voting
- 🎵 **Music Capsules**: Exclusive tracks unlocking on special dates
- 🏆 **Achievement Capsules**: Gaming achievements that evolve
- 📚 **Educational Capsules**: Progressive learning content
- 🌟 **Memory Capsules**: Multi-generational family messages

### 🔐 Multi-Signature (New in v1.1.0)
Create proposals requiring multiple signatures:

```typescript
// Create a multi-sig proposal
const proposal = await client.multiSig.createProposal({
  capsuleId: 'capsule-id',
  signers: ['0xAddr1', '0xAddr2', '0xAddr3'],
  requiredSignatures: 2,
  action: 'unlock',
  duration: 72 // hours
});

// Sign the proposal
await client.multiSig.signProposal(proposal.id);

// Check proposal status
const status = await client.multiSig.getProposal(proposal.id);
```

### 🪝 Webhooks (New in v1.1.0)
Receive real-time notifications:

```typescript
// Register webhook endpoint
const webhook = await client.webhooks.create({
  url: 'https://your-app.com/webhook',
  events: [
    'capsule.created',
    'capsule.unlocked',
    'payment.claimed',
    'document.signed'
  ],
  secret: 'your-webhook-secret'
});

// Verify incoming webhooks
const isValid = client.webhooks.verifySignature(
  payload,
  signature,
  secret
);
```

### 📊 Analytics
Track usage and get insights:

```typescript
// Basic analytics (Starter+)
const overview = await client.analytics.getOverview();

// Advanced analytics (Pro+)
const insights = await client.analytics.getInsights({
  focus: 'retention',
  timeframe: 'month'
});

// Custom dashboards (Pro+)
const dashboard = await client.analytics.createCustomDashboard({
  name: 'Executive Overview',
  widgets: [/* widget configs */]
});
```

## Rate Limits & Plans

| Plan | Rate Limit | Capsules/Month | Storage | Price |
|------|------------|----------------|---------|--------|
| Free | 10 req/min | 5 | 50MB | $0 |
| Starter | 30 req/min | 50 | 500MB | $29/mo |
| Pro | 100 req/min | 500 | 5GB | $99/mo |
| Enterprise | Unlimited | Unlimited | Unlimited | Custom |

## Configuration

### API Keys
Get your API key from the [LegacyChain Dashboard](https://legacychain.net/dashboard).

### Networks
- `mainnet`: Production network
- `testnet`: Sepolia testnet for development
- `localhost`: Local development

### Contract Addresses (Mainnet)
- **LegacyNFT**: `0x1CDccb98155c963152C1C36Dd9d4B73A13ae5A17`
- **LegacyPayments**: `0xaBb7673d8DeD965545FF2d9437Bbc393dfa880b1`
- **LegacyLegalDocs**: `0x90B0fb2f0f6c637077b4e0fc69b14221e72094c9`
- **LegacyMultiSig**: `0xcb481E0Df628eEe515768Ae8B2B83Aa0B6d4Cc9b` ✨

## Advanced Usage

### Connect Wallet
```typescript
// For browser environments
await client.connectWallet(window.ethereum);

// Sign messages
const signature = await client.getSigner().signMessage('Hello');
```

### Custom RPC
```typescript
const client = new LegacyChainClient({
  apiKey: 'your-api-key',
  network: 'mainnet',
  rpcUrl: 'https://your-custom-rpc.com'
});
```

### Error Handling
```typescript
try {
  await client.timeCapsules.create({...});
} catch (error) {
  if (error.code === 'RATE_LIMIT_EXCEEDED') {
    console.log('Please upgrade your plan');
  }
}
```

## Support

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

## License

MIT