ai-sync/README.md

AI-native sync infrastructure SDK - Your code gains conversational intelligence

# ai-sync

> **AI-Native Sync Infrastructure** - Your code gains conversational intelligence

## 🚀 Installation

```bash
npm install ai-sync
```

## ✨ Quick Start

```typescript
import { SyncClient } from 'ai-sync';

const sync = new SyncClient({ 
  apiKey: 'your-api-key',
  tenantId: 'your-tenant-id'
});

// Your code understands natural language
const config = await sync.ai("sync stripe customers to hubspot");

// Your runtime gains sync capabilities
const link = await sync.createLink(config.syncConfig);

// Your infrastructure reports on itself
console.log(await link.getStatus());
// → "Your runtime processed 247 syncs today"
```

## 🎯 The Paradigm Shift

This isn't just another API client. Your code gains **native intelligence** for infrastructure management.

### Before: External Dependencies
```typescript
// Old way - using external platforms
const zapier = new ZapierClient(apiKey);
await zapier.createZap(...);  // You're using THEIR service
```

### After: Intelligent Code
```typescript  
// New way - your code becomes conversational
const sync = new SyncClient({ apiKey });
await sync.ai("connect my stripe to hubspot");  // YOUR code just got smarter
```

## 🤖 AI-Powered Configuration

### Natural Language → Working Code

```typescript
// Just describe what you want
const config = await sync.ai("sync stripe customers to hubspot");

console.log(config.explanation);
// → "Your runtime will maintain bidirectional sync between Stripe and HubSpot"

console.log(config.codeSnippet);
// → Complete, working code ready to execute

console.log(config.timeToSetup);
// → "Ready in 5 seconds"
```

### Blazing Fast Responses

- **Common patterns**: <1 second (cached responses)
- **Custom configurations**: <5 seconds (live AI)
- **Always consistent**: Same quality whether cached or generated

## 🔗 Universal Auto-Connect

Your code connects itself to any service:

```typescript
// Works with any service your backend supports
const stripeAuth = await sync.autoConnect('stripe');
const hubspotAuth = await sync.autoConnect('hubspot');
const salesforceAuth = await sync.autoConnect('salesforce');
const notionAuth = await sync.autoConnect('notion');

// → "Your application is connecting to [Service]..."
// → "Your code now has native [Service] access"
```

## 📊 Real-Time Monitoring

Your infrastructure reports on its own behavior:

```typescript
const status = await link.getStatus();
console.log(status.message);
// → "Your runtime processed 247 syncs today with 100% success rate"

// Live event streaming
link.on('sync:success', (event) => {
  console.log(`Your code synced ${event.entityId} in ${event.duration}ms`);
});
```

## 🛠️ Advanced Features

### Field-Level Conflict Resolution
```typescript
const config = await sync.ai(`
  sync stripe to hubspot but:
  - trust stripe for email addresses
  - prefer hubspot for company names  
  - use latest timestamp for contact info
`);
// → Generates sophisticated field-level mapping
```

### Conditional Sync Rules
```typescript
const config = await sync.ai(`
  sync active stripe customers to hubspot
  but skip deleted customers and free trials
`);
// → Includes intelligent filtering logic
```

### Multiple Alternatives
```typescript
const config = await sync.ai("sync billing data");

console.log(config.alternatives);
// → [
//   { title: "Bidirectional Sync", pros: [...], cons: [...] },
//   { title: "Unidirectional Only", pros: [...], cons: [...] }
// ]
```

## 🎭 The Language Revolution

Every interaction reinforces: **"Your code gained intelligence"**

### ✅ How We Talk
- "Your runtime is processing..."
- "Your application now maintains sync"
- "Your code gained native Stripe access"
- "Your infrastructure reports 99% uptime"

### ❌ How We Don't Talk  
- ~~"Our platform will sync..."~~
- ~~"Connected to our service..."~~
- ~~"Using our API to..."~~
- ~~"Our system processed..."~~

## 📖 Templates & Examples

### Templates & Examples

### Universal Architecture
```typescript
import { SyncTemplates } from 'ai-sync';

// Bidirectional sync between ANY systems
const config = SyncTemplates.bidirectional('stripe', 'hubspot', 'your-tenant-id');
const postgresSync = SyncTemplates.bidirectional('postgres', 'salesforce', 'your-tenant-id');
const notionSync = SyncTemplates.unidirectional('airtable', 'notion', 'your-tenant-id');

// Your code adapts to any combination
const link = await sync.createLink(config);
```

### Legacy Patterns (Backwards Compatible)
```typescript
// Still works for common patterns
const stripe2hubspot = SyncTemplates.stripeToHubSpot('your-tenant-id');
const billing = SyncTemplates.billingSync('your-tenant-id');
```

### Custom Configurations
```typescript
// Your code can handle any system combination
const config = await sync.ai(`
  sync stripe subscriptions to salesforce opportunities
  with custom field mapping for MRR and deal stages
  but only for enterprise customers
`);

// Or even complex multi-system flows
const workflow = await sync.ai(`
  when postgres customer updates, sync to both hubspot and intercom
  but filter out internal test accounts
`);
```

## 🔧 Configuration

```typescript
const sync = new SyncClient({
  apiKey: 'your-api-key',
  tenantId: 'your-tenant-id',
  baseUrl: 'https://your-deployment.com', // Optional
  environment: 'production' // or 'sandbox'
});
```

## 🎪 Events & Real-Time Updates

```typescript
// Your code reports on sync operations
link.on('sync:success', (data) => {
  console.log('Sync completed:', data);
});

link.on('sync:conflict', (conflict) => {
  console.log('Conflict resolved:', conflict.resolution);
});

link.on('sync:error', (error) => {
  console.log('Your runtime encountered:', error.message);
});
```

## 🚨 Error Handling

Even errors maintain the paradigm:

```typescript
try {
  await sync.createLink(config);
} catch (error) {
  console.log(error.message);
  // → "Your code couldn't establish sync: OAuth tokens expired"
  // NOT: "API call failed"
}
```

## 🔐 Security & Auth

```typescript
// Check connection status
const status = await sync.getConnectionStatus('stripe');
console.log(status.message);
// → "Your code has native Stripe access"
// → "Your application needs to reconnect to Stripe"
```

## 📈 Scaling & Performance  

- **Cached AI responses**: Sub-second for common patterns
- **Intelligent rate limiting**: Your code respects API limits automatically  
- **Conflict resolution**: Field-level intelligence for complex scenarios
- **Real-time sync**: Webhook-driven updates with fallback polling

## 🌟 Why This Changes Everything

This isn't about building integrations. It's about **making code conversational**.

When developers use this SDK, they're not just calling an API - they're teaching their applications to understand infrastructure.

That's the paradigm shift. That's the future.

## 📚 Documentation

- [Getting Started Guide](https://docs.syncapis.com/getting-started)
- [API Reference](https://docs.syncapis.com/api)
- [Common Patterns](https://docs.syncapis.com/patterns)
- [Advanced Configuration](https://docs.syncapis.com/advanced)

## 🤝 Support

- **Documentation**: https://docs.syncapis.com
- **GitHub Issues**: https://github.com/syncapis/sdk/issues  
- **Email**: support@syncapis.com

---

**Remember**: Your code just gained the ability to configure its own infrastructure through natural language. Use it wisely. 🚀