# Rainfall Devkit

Official TypeScript SDK for the Rainfall API - 200+ tools for building AI-powered applications. Secure distributed edge mesh for AI agents.

## Overview

Rainfall Devkit is a comprehensive SDK that provides programmatic access to 200+ tools across multiple integrations including GitHub, Notion, Linear, Slack, Figma, Stripe, and more. 

**Key differentiator**: Rainfall turns your local functions into secure, encrypted, ACL'd edge nodes with one CLI command. No more gluing 17 different tools together. Built-in usage credits, MCP proxy hub, and daemon routing.

**Use cases**: AI agents, workflow automation, data processing, semantic memory systems, content generation, and API integration.

## Key Features

### Extensive Tool Library
- **200+ Tools** across major SaaS platforms and AI services
- **Semantic Memory** - Store and recall information with vector search
- **Web Search** - Exa and Perplexity integration for real-time search
- **AI Tools** - Embeddings, image generation, OCR, vision, chat completion
- **Data Processing** - CSV operations, scripts, similarity search
- **Utilities** - Mermaid diagrams, document conversion, regex, JSON extraction

### Integrations
- **GitHub** - Issues, repositories, pull requests
- **Notion** - Pages, databases, blocks
- **Linear** - Issues and teams
- **Slack** - Messages, channels, users, reactions
- **Figma** - Files, projects, comments
- **Stripe** - Customers, payment intents, subscriptions

### Developer Experience
- **TypeScript** - Full type safety and IntelliSense support
- **Retry Logic** - Automatic exponential backoff for failed requests
- **Error Handling** - Custom error classes (RateLimitError, AuthenticationError, NotFoundError)
- **CLI** - Command-line interface for quick operations
- **Daemon** - Local WebSocket/MCP server and OpenAI-compatible API
- **MCP Support** - Native Model Context Protocol server for AI assistants

## Installation

```bash
npm install @rainfall-devkit/sdk
# or
yarn add @rainfall-devkit/sdk
# or
bun add @rainfall-devkit/sdk
```

## Quick Start

### Basic Usage

```typescript
import { Rainfall } from '@rainfall-devkit/sdk';

const rainfall = new Rainfall({
  apiKey: process.env.RAINFALL_API_KEY!
});

// Web search
const results = await rainfall.web.search.exa({
  query: 'latest AI breakthroughs'
});

// GitHub operations
await rainfall.integrations.github.issues.create({
  owner: 'facebook',
  repo: 'react',
  title: 'Bug: Something is broken',
  body: 'Detailed description...'
});

// Memory operations
await rainfall.memory.create({
  content: 'User prefers dark mode',
  keywords: ['preference', 'ui']
});

const memories = await rainfall.memory.recall({
  query: 'user preferences',
  topK: 5
});
```

### CLI Usage

```bash
# Global installation
bun add -g @rainfall-devkit/sdk

# Authentication
rainfall auth login <your-api-key>

# List available tools
rainfall tools list

# Execute a tool
rainfall run exa-web-search -p '{"query": "AI news"}'

# Pipe support
echo '{"query": "hello"}' | rainfall run exa-web-search
```

### Daemon Mode

Run a local daemon with WebSocket (MCP) and OpenAI-compatible API endpoints:

```bash
# Start daemon
rainfall daemon start

# Start with custom ports
rainfall daemon start --port 8765 --openai-port 8787

# Check status
rainfall daemon status

# Stop daemon
rainfall daemon stop
```

**Daemon Endpoints:**
- WebSocket (MCP): `ws://localhost:8765`
- OpenAI-compatible API: `http://localhost:8787/v1/chat/completions`

### MCP Server

Use Rainfall with Claude, Cursor, and other MCP-compatible assistants:

```typescript
import { createRainfallMCPServer } from '@rainfall/sdk/mcp';

const server = createRainfallMCPServer({
  apiKey: process.env.RAINFALL_API_KEY!
});

await server.start();
```

## Namespaces

### Integrations

```typescript
// GitHub
await rainfall.integrations.github.issues.create({ owner, repo, title });
await rainfall.integrations.github.repos.get({ owner, repo });

// Notion
await rainfall.integrations.notion.pages.create({ parent, properties });
await rainfall.integrations.notion.databases.query({ databaseId });

// Linear
await rainfall.integrations.linear.issues.create({ title, teamId });
await rainfall.integrations.linear.teams.list();

// Slack
await rainfall.integrations.slack.messages.send({ channelId, text });
await rainfall.integrations.slack.channels.list();

// Figma
await rainfall.integrations.figma.files.get({ fileKey });
await rainfall.integrations.figma.files.getImages({ fileKey, nodeIds });

// Stripe
await rainfall.integrations.stripe.customers.create({ email });
await rainfall.integrations.stripe.paymentIntents.create({ amount, currency });
```

### Memory

```typescript
// Create memory
await rainfall.memory.create({
  content: 'Important information',
  keywords: ['key', 'info'],
  metadata: { source: 'user' }
});

// Recall by similarity
const memories = await rainfall.memory.recall({
  query: 'important information',
  topK: 10
});

// CRUD operations
await rainfall.memory.get({ memoryId: '...' });
await rainfall.memory.update({ memoryId: '...', content: 'Updated' });
await rainfall.memory.delete({ memoryId: '...' });
await rainfall.memory.list();
```

### Web

```typescript
// Search
const exaResults = await rainfall.web.search.exa({ query: '...' });
const perplexityResults = await rainfall.web.search.perplexity({ query: '...' });

// Fetch and convert
const html = await rainfall.web.fetch({ url: 'https://example.com' });
const markdown = await rainfall.web.htmlToMarkdown({ html });

// Extract elements
const links = await rainfall.web.extractHtml({
  html,
  selector: 'a[href]'
});
```

### AI

```typescript
// Embeddings
const docEmbedding = await rainfall.ai.embeddings.document({ text });
const queryEmbedding = await rainfall.ai.embeddings.query({ text });
const imageEmbedding = await rainfall.ai.embeddings.image({ imageBase64 });

// Image generation
const image = await rainfall.ai.image.generate({
  prompt: 'A serene mountain landscape',
  size: '1024x1024'
});

// OCR and Vision
const text = await rainfall.ai.ocr({ imageBase64 });
const analysis = await rainfall.ai.vision({
  imageBase64,
  prompt: 'Describe this image'
});

// Chat and completion
const response = await rainfall.ai.chat({
  messages: [{ role: 'user', content: 'Hello!' }],
  model: 'grok-2'
});
```

### Data

```typescript
// CSV operations
const results = await rainfall.data.csv.query({
  sql: 'SELECT * FROM data WHERE value > 100'
});

await rainfall.data.csv.convert({
  data: csvData,
  fromFormat: 'csv',
  toFormat: 'json'
});

// Scripts
await rainfall.data.scripts.create({
  name: 'process-data',
  code: 'return input.map(x => x * 2);',
  language: 'javascript'
});

const result = await rainfall.data.scripts.execute({
  name: 'process-data',
  params: { input: [1, 2, 3] }
});
```

### Utils

```typescript
// Mermaid diagrams
const diagram = await rainfall.utils.mermaid({
  diagram: 'graph TD\n  A[Start] --> B[End]'
});

// Document conversion
const pdf = await rainfall.utils.documentConvert({
  document: markdownContent,
  mimeType: 'text/markdown',
  format: 'pdf'
});

// Regex
const matches = await rainfall.utils.regex.match({
  text: 'Hello 123 world',
  pattern: '\\d+',
  flags: 'g'
});
```

## Configuration

```typescript
const rainfall = new Rainfall({
  apiKey: 'your-api-key',
  baseUrl: 'https://custom-endpoint.com/v1', // Optional
  timeout: 60000,  // Request timeout in ms (default: 30000)
  retries: 5,      // Number of retries (default: 3)
  retryDelay: 2000 // Initial retry delay in ms (default: 1000)
});
```

## Error Handling

```typescript
import { Rainfall, RateLimitError, AuthenticationError, NotFoundError } from '@rainfall/sdk';

try {
  await rainfall.integrations.github.issues.get({ owner, repo, issue_number: 999999 });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
    console.log(`Remaining: ${error.remaining}/${error.limit}`);
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof NotFoundError) {
    console.log(`Resource not found: ${error.message}`);
  }
}
```

## Rate Limiting

The SDK automatically handles rate limiting with exponential backoff:

```typescript
// Check rate limit info
const info = rainfall.getRateLimitInfo();
console.log(info);
// { limit: 1000, remaining: 950, resetAt: Date }
```

## Examples

### GitHub to Notion Sync

```typescript
// Get GitHub issues
const issues = await rainfall.integrations.github.issues.list({
  owner: 'myorg',
  repo: 'myrepo',
  state: 'open'
});

// Create Notion pages for each issue
for (const issue of issues) {
  await rainfall.integrations.notion.pages.create({
    parent: { database_id: 'my-database-id' },
    properties: {
      Name: { title: [{ text: { content: issue.title } }] },
      'Issue URL': { url: issue.html_url },
      Status: { select: { name: issue.state } }
    }
  });
}
```

### PDF to Estimate

```typescript
// Fetch PDF
const response = await fetch('https://example.com/quote.pdf');
const buffer = await response.arrayBuffer();
const base64 = Buffer.from(buffer).toString('base64');

// Extract text with OCR
const { text } = await rainfall.ai.ocr({ imageBase64: base64 });

// Extract structured data
const estimate = await rainfall.ai.complete({
  prompt: `Extract line items from this quote:\n\n${text}\n\nJSON format:`,
  suffix: ''
});

console.log(JSON.parse(estimate));
```

### Memory Agent

```typescript
// Store conversation context
await rainfall.memory.create({
  content: `User asked about pricing. Explained $9/mo for 100k calls.`,
  keywords: ['pricing', 'conversation'],
  metadata: { userId: 'user-123', timestamp: Date.now() }
});

// Later, recall relevant context
const context = await rainfall.memory.recall({
  query: 'What did I tell the user about pricing?',
  topK: 3
});

// Use context in response
const response = await rainfall.ai.chat({
  messages: [
    { role: 'system', content: 'Previous context: ' + JSON.stringify(context) },
    { role: 'user', content: 'What was our pricing again?' }
  ]
});
```

## Architecture

### Package Structure

```
rainfall-devkit/
├── src/
│   ├── index.ts           # Main SDK entry point
│   ├── client.ts          # Core HTTP client
│   ├── sdk.ts            # Rainfall class and namespaces
│   ├── types.ts          # TypeScript types
│   ├── errors.ts         # Custom error classes
│   ├── mcp.ts            # MCP server implementation
│   ├── daemon/           # Daemon server
│   │   └── index.ts      # WebSocket + OpenAI API server
│   ├── cli/              # Command-line interface
│   │   ├── index.ts      # CLI entry point
│   │   └── config.ts     # Config management
│   ├── namespaces/       # Tool namespaces
│   │   ├── integrations.ts
│   │   ├── memory.ts
│   │   ├── articles.ts
│   │   ├── web.ts
│   │   ├── ai.ts
│   │   ├── data.ts
│   │   └── utils.ts
│   ├── services/         # Core services
│   │   ├── context.ts    # Daemon context/memory
│   │   ├── listeners.ts # Event listeners
│   │   ├── mcp-proxy.ts  # MCP proxy for external servers
│   │   └── networked.ts  # Network utilities
│   └── security/         # Security features
│       ├── edge-client.ts # Secure edge node client
│       └── edge-node.ts  # JWT and encryption
└── examples/            # Example scripts
    ├── mcp-chrome-example.js
    ├── pdf-watcher.js
    └── pdf-watcher.ts
```

### Core Components

- **RainfallClient** - HTTP client with retry logic and error handling
- **Rainfall** - Main SDK class exposing all namespaces
- **Namespaces** - Organized tool groups (integrations, memory, web, AI, etc.)
- **Daemon** - Local server with WebSocket/MCP and OpenAI-compatible endpoints
- **MCP Server** - Model Context Protocol server for AI assistant integration
- **Security** - JWT authentication, ACL validation, encryption for edge nodes

## Related Projects

- **Rainyday** - Core Rainfall backend platform (Bun-based API)
- **Olympic-2** - Rainfall SDK Studio - Testing interface for workflow nodes
- **Harmonic** - Live dance studio SaaS (built with Rainfall)
- **Majestic** - AEC draft build application
- **Polymorphic** - AI self-mutating sites platform

## Technical Specifications

- **Version**: 0.2.2
- **License**: MIT
- **Node Version**: >= 18
- **Package Name**: @rainfall-devkit/sdk
- **Repository**: https://github.com/Holistic-Dogma/rainfall-devkit
- **Maintainer**: Pragma Digital Solutions

## Team

- **Mina** - Visuals, positioning, design direction
- **Fall/Sekeol Kim** - Backend architecture, API wizardry, core infrastructure

## Support & Documentation

- **Documentation**: See Rainfall-SDK-README.md in the devkit package
- **Examples**: Check the examples/ directory for practical implementations
- **Issues**: https://github.com/Holistic-Dogma/rainfall-devkit/issues

## API Endpoints

Base URL: `https://rainfall.pragma-digital.org/v1` (customizable via baseUrl config)

Authentication: API key via `X-Api-Key` header or `x-api-key` query parameter

Rate limits are automatically handled by the SDK with exponential backoff.

## Use Cases

- **AI Agents** - Build agents that can interact with GitHub, Notion, Slack, etc.
- **Workflow Automation** - Create automated workflows between SaaS platforms
- **Data Processing** - Process documents, images, and structured data
- **Memory Systems** - Implement semantic memory for conversational AI
- **Content Generation** - Generate images, text, and documents
- **API Integration** - Quickly integrate multiple SaaS APIs through unified SDK