API_DOCS.md

# Sweety.dev API Documentation

Base URL: `https://your-space.hf.space`

Storage: `/data` (HF Spaces persistent storage)

---

## Build APIs

### POST /api/build
Create a new build for a React project.

**Request Body:**
```json
{
  "user_id": "user123",
  "project_id": "proj456",  // optional, auto-generated if omitted
  "files": {
    "src/App.jsx": "export default function App() { return <div>Hello</div> }",
    "src/components/Button.jsx": "export const Button = () => <button>Click</button>",
    "public/logo.png": "base64_encoded_image"
  },
  "dependencies": {
    "lucide-react": "^0.300",
    "framer-motion": "^10.0"
  },
  "framework": "react"
}
```

**Response:**
```json
{
  "project_id": "proj456",
  "user_id": "user123",
  "status": "pending"
}
```

**Build Status Values:**
- `pending` - Build queued
- `installing` - npm install running
- `building` - vite build running
- `success` - Build complete, preview ready
- `failed` - Build failed (check error field)

---

### GET /api/status/{user_id}/{project_id}
Check build status.

**Response:**
```json
{
  "project_id": "proj456",
  "user_id": "user123",
  "status": "success",
  "url": "/preview/user123/proj456/",
  "error": null
}
```

---

### DELETE /api/build/{user_id}/{project_id}
Delete a build and its artifacts.

**Response:**
```json
{
  "deleted": true
}
```

---

## File Management APIs

### POST /api/file
Create or upload a file to user storage.

**Request Body:**
```json
{
  "user_id": "user123",
  "project_id": "proj456",
  "filename": "src/components/Header.jsx",
  "content": "export const Header = () => <header>Header</header>"
}
```

**Response:**
```json
{
  "created": true,
  "path": "/data/users/user123/files/src/components/Header.jsx"
}
```

---

### GET /api/file/{user_id}/{filename:path}
Read a file from user storage.

**Response:**
```json
{
  "content": "export const Header = () => <header>Header</header>"
}
```

---

### PUT /api/file
Update an existing file.

**Request Body:**
```json
{
  "user_id": "user123",
  "project_id": "proj456",
  "filename": "src/components/Header.jsx",
  "content": "export const Header = () => <header>New Header</header>"
}
```

**Response:**
```json
{
  "updated": true
}
```

---

### DELETE /api/file/{user_id}/{filename:path}
Delete a file.

**Response:**
```json
{
  "deleted": true
}
```

---

### GET /api/files/{user_id}
List all files for a user.

**Response:**
```json
[
  {
    "filename": "src/App.jsx",
    "size": 1234
  },
  {
    "filename": "src/components/Header.jsx",
    "size": 567
  }
]
```

---

## Project Management APIs

### GET /api/projects/{user_id}
List all projects for a user.

**Response:**
```json
[
  {
    "project_id": "proj456",
    "files": ["src/App.jsx", "src/components/Button.jsx"],
    "dependencies": {"lucide-react": "^0.300"},
    "created_at": "123456.789"
  },
  {
    "project_id": "proj789",
    "files": ["src/App.jsx"],
    "dependencies": {},
    "created_at": "123457.890"
  }
]
```

---

## Preview

### GET /preview/{user_id}/{project_id}/{path:path}
Serve built static files.

**Examples:**
- `/preview/user123/proj456/` - Main index.html
- `/preview/user123/proj456/assets/index.abc123.js` - JavaScript bundle
- `/preview/user123/proj456/assets/index.def456.css` - CSS

**Note:** SPA routing automatically falls back to index.html for non-existent paths.

---

## Storage Structure

```
/data/
├── users/
│   └── {user_id}/
│       ├── files/              # User file storage
│       │   ├── src/
│       │   │   ├── App.jsx
│       │   │   └── components/
│       │   │       └── Header.jsx
│       │   └── public/
│       │       └── logo.png
│       └── projects/           # Project metadata
│           ├── proj456.json
│           └── proj789.json
└── builds/
    └── {user_id}/
        └── {project_id}/       # React build artifacts
            ├── src/
            ├── package.json
            ├── vite.config.js
            ├── index.html
            └── dist/           # Built static files
                ├── index.html
                └── assets/
```

---

## Example Usage

### 1. Create a Build

```javascript
const response = await fetch('/api/build', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    user_id: 'user123',
    files: {
      'src/App.jsx': `export default function App() {
        return (
          <div className="p-8">
            <h1>Hello Sweety!</h1>
          </div>
        )
      }`,
      'src/components/Button.jsx': `export const Button = () => <button>Click</button>`
    },
    dependencies: {
      'lucide-react': '^0.300'
    }
  })
});

const { project_id, user_id, status } = await response.json();
```

### 2. Poll Build Status

```javascript
const checkStatus = async () => {
  const res = await fetch(`/api/status/${user_id}/${project_id}`);
  const data = await res.json();
  
  if (data.status === 'success') {
    console.log('Preview ready:', data.url);
    // Load in iframe: <iframe src={data.url} />
  } else if (data.status === 'failed') {
    console.error('Build failed:', data.error);
  }
};

setInterval(checkStatus, 1000);
```

### 3. Store Files Before Build

```javascript
// Save individual files
await fetch('/api/file', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    user_id: 'user123',
    project_id: 'proj456',
    filename: 'src/App.jsx',
    content: 'export default function App() { return <div>Hello</div> }'
  })
});

// List files
const files = await fetch(`/api/files/${user_id}`).then(r => r.json());
```

---

## Rate Limits & Concurrency

- **Concurrent Builds:** 5 per user
- **File Size:** 10MB per file
- **Build Timeout:** 2 minutes
- **Storage:** 1GB per user (HF Spaces limit)

Upgrade to CPU Upgrade for higher limits and faster builds.