npm package: @rsemihkoca/fal-extended
Description: Extended fal.ai client and server proxy with upload progress tracking and React Native support
Author: rsemihkoca
Latest version: 1.2.0

# @rsemihkoca/fal-extended

All-in-one fal.ai package with **client** and **server proxy** including upload progress tracking.

## 📦 One Package, Two Powers

```bash
npm install @rsemihkoca/fal-extended
```

This single package includes:
- 🎯 **Client** - Browser/Node.js client with upload progress
- 🔒 **Proxy** - Server proxy with storage handlers

## 🚀 Quick Start

### Client-Side (Browser/React/Vue/etc)

```typescript
import { fal } from '@rsemihkoca/fal-extended';

// Configure with your proxy
fal.config({
  proxyUrl: 'http://localhost:3000/api/fal/proxy'
});

// Upload with progress
const url = await fal.storage.upload(file, {
  onProgress: (e) => {
    console.log(`${e.progress}% - ${e.type}`);
    if (e.currentPart) {
      console.log(`Part ${e.currentPart}/${e.totalParts}`);
    }
  }
});
```

### Server-Side (Express/Next.js/etc)

```typescript
import express from 'express';
import * as fal from '@rsemihkoca/fal-extended/proxy/express';

const app = express();
app.use(express.json());

// Single line setup!
app.use(`${fal.route}/storage/upload`, fal.storageHandler);
app.use(fal.route, fal.handler);

app.listen(3000);
```

## 📚 Import Paths

```typescript
// Client
import { fal } from '@rsemihkoca/fal-extended';
// or
import { fal } from '@rsemihkoca/fal-extended/client';

// Proxy - Express
import * as fal from '@rsemihkoca/fal-extended/proxy/express';

// Proxy - Next.js
import * as fal from '@rsemihkoca/fal-extended/proxy/nextjs';

// Proxy - Hono
import * as fal from '@rsemihkoca/fal-extended/proxy/hono';

// Proxy - Core
import * as fal from '@rsemihkoca/fal-extended/proxy';
```

## ✨ Features

### Client Features
- ✅ All original fal.ai client APIs
- 🆕 Upload progress callbacks
- 🆕 Multipart upload progress (>90MB files)
- 🆕 Real-time upload tracking
- 🆕 Part-by-part progress for large files

### Proxy Features
- ✅ All original proxy features
- 🆕 Storage upload handlers
- 🆕 Single handler design
- 🆕 Automatic multipart detection
- 🆕 Secure credential handling
- 🆕 Framework support (Express, Next.js, Hono, Remix, SvelteKit)

## 📖 Examples

### React with Progress Bar

```typescript
import { fal } from '@rsemihkoca/fal-extended';
import { useState } from 'react';

function FileUploader() {
  const [progress, setProgress] = useState(0);
  const [status, setStatus] = useState('');

  const handleUpload = async (file: File) => {
    const url = await fal.storage.upload(file, {
      onProgress: (e) => {
        setProgress(e.progress);
        setStatus(e.currentPart
          ? `Uploading part ${e.currentPart}/${e.totalParts}`
          : e.type
        );
      }
    });

    return url;
  };

  return (
    <div>
      <progress value={progress} max={100} />
      <p>{status}</p>
    </div>
  );
}
```

### Complete Server Setup

```typescript
import express from 'express';
import cors from 'cors';
import * as fal from '@rsemihkoca/fal-extended/proxy/express';

const app = express();

// Middleware
app.use(cors());
app.use(express.json());

// Logging (optional)
app.use((req, res, next) => {
  console.log(`${req.method} ${req.url}`);
  next();
});

// fal.ai routes
app.use(`${fal.route}/storage/upload`, fal.storageHandler);
app.use(fal.route, fal.handler);

// Start server
app.listen(3000, () => {
  console.log('🚀 Proxy server running on http://localhost:3000');
  console.log(`📡 Storage endpoint: ${fal.route}/storage/upload`);
  console.log(`📡 General proxy: ${fal.route}`);
});
```

### Environment Variables

```bash
# .env
FAL_KEY=your-fal-key-here

# Or use separate key ID and secret
FAL_KEY_ID=your-key-id
FAL_KEY_SECRET=your-key-secret
```

## 🔐 Security

**NEVER expose FAL_KEY in the browser!**

✅ **Correct:**
```typescript
// Client - uses proxy (credentials stay on server)
fal.config({ proxyUrl: 'https://your-server.com/api/fal/proxy' });
```

❌ **Wrong:**
```typescript
// Client - exposes credentials!
fal.config({ credentials: 'fal-key-xxx' });
```

## 📊 Upload Flow

```
┌──────────┐                  ┌─────────┐                 ┌────────┐
│  Client  │─────────────────▶│  Proxy  │────────────────▶│ fal.ai │
│ (Browser)│  No credentials  │ (Server)│  With FAL_KEY  │   API  │
└──────────┘                  └─────────┘                 └────────┘
     │                              │
     │  ◀───── signed URL ──────────┤
     │
     ▼
┌──────────┐
│  Storage │  Direct upload (S3/CDN)
│  (Fast!) │  No proxy overhead!
└──────────┘
```

## 📄 Documentation

- [Client README](./libs/client/README.md)
- [Proxy README](./libs/proxy/README.md)
- [Storage Upload Guide](./libs/proxy/STORAGE_UPLOAD.md)

## 🔗 Framework Examples

### Next.js App Router

```typescript
// app/api/fal/[[...path]]/route.ts
export { GET, POST, PUT, DELETE } from '@rsemihkoca/fal-extended/proxy/nextjs';
```

### Hono

```typescript
import { Hono } from 'hono';
import * as fal from '@rsemihkoca/fal-extended/proxy/hono';

const app = new Hono();
app.use(`${fal.route}/storage/upload/*`, fal.storageHandler);
app.use(`${fal.route}/*`, fal.handler);
```

## 📦 Package Size

This package includes both client and proxy code. If you only need one:

```typescript
// Tree-shaking will remove unused code in production builds

// Only import what you need
import { fal } from '@rsemihkoca/fal-extended/client';  // Client only
import * as fal from '@rsemihkoca/fal-extended/proxy/express';  // Proxy only
```

## 🆚 Comparison

| Feature | Original fal.ai | @rsemihkoca/fal-extended |
|---------|----------------|--------------------------|
| Basic client | ✅ | ✅ |
| Server proxy | ✅ | ✅ |
| Upload progress | ❌ | ✅ |
| Multipart progress | ❌ | ✅ |
| Storage handlers | ❌ | ✅ |
| Single handler | ❌ | ✅ |

## 📜 License

MIT

## 🤝 Contributing

Based on [@fal-ai/client](https://github.com/fal-ai/fal-js). Contributions welcome!

## 🐛 Issues

Report issues at: https://github.com/rsemihkoca/fal-extended/issues