puter-sdk/.kilocode/rules/project-overview.md

The Unofficial Puter SDK library for Puter cloud platform

# Puter-SDK

This project is a JavaScript SDK for interacting with the **Puter Cloud Platform**. Users can create an account for free (You'll get a free 1Gb from this link). This SDK provides a simple and consistent interface for working with Puter's APIs, including file management, app deployment, AI services, and more.

## Features

- **File Management**
  - List, upload, download, and manage files
  - Create and manage directories
  - File operations (copy, move, rename, delete)

- **App Management**
  - Create, update, and delete apps
  - Manage app configurations (WIP)
  - Deploy static sites

- **Key-Value Store**
    - Basic Operations: Set, get, and delete key/value pairs
    - Handle various data types (strings, numbers, objects, arrays)
    - Increment/Decrement: Atomic increment/decrement operations with support for custom amounts
    - upport for custom amounts: Flush all keys, list keys with glob pattern support

- **Sites Management**
  - Create, update, and delete sites
  - Deploy static sites from existing directory

- **AI Services**
  - Chat completions (streaming and non-streaming)
  - Image generation
  - Optical Character Recognition (OCR)
  - Text-to-Speech (TTS)

- **User Management**
  - Authentication (login/logout)
  - User information
  - Session management

- **Subdomain Management**
  - Create and manage hosting
  - Link hosting to directories
  - Manage static site hosting

## Installation

Using npm:
```bash
npm install puter-sdk
```

Using yarn:
```bash
yarn add puter-sdk
```

Using pnpm:
```bash
pnpm add puter-sdk
```

## Usage

### Basic Setup

```javascript
import PuterClient from 'puter-sdk';

// Initialize the client
const puter = new PuterClient({
  token: 'your-api-token', // Optional, can be set later
  baseURL: 'https://api.puter.com' // Optional
});
```

### Authentication

```javascript
// Login using your credentials:
const puter = await puter.auth.signIn('username', 'password');
console.log('Logged in with token:', puter.token);

// or just create a new instance:
const puter = new PuterClient();
// P.S. The client will look for `PUTER_API_KEY` in .env file name or provide as a variable environnement.

// Get current user
const userInfo = await puter.auth.getUser();
console.log('User info:', userInfo);

// Logout
await puter.auth.signOut();
```

### File Management

```javascript
// List directory contents
const files = await puter.fs.readdir('/');
console.log('Files:', files);

// Upload a file
const file = new Blob(['Hello, Puter!'], { type: 'text/plain' });
const uploadResult = await puter.fs.upload({
  file,
  path: '/uploads',
  name: 'hello.txt'
});
console.log('Upload result:', uploadResult);

// Create a directory
const dirResult = await puter.fs.mkdir({
  path: '/new-directory'
});
console.log('Directory created:', dirResult);
```

### App Management

```javascript
// List all apps
const apps = await puter.apps.list();
console.log('Apps:', apps);
```


### Key/Value Store

```javascript
// Create a key/value pair
const result = await puter.kv.set('testKey', 'testValue');
const value = await puter.kv.get('testKey');

console.log(`value set: ${value}`);

// Deleting by key
const result = await puter.kv.del('testKey');
console.log(`result of delete operation: ${result}`);
```

### AI Services

```javascript
// Basic chat completion
const chatResponse = await puter.ai.chat([{
  role: 'user',
  content: 'What is Puter?'
}]);
console.log('AI response:', chatResponse.message.content);

// Chat completion with a simple string prompt
const simpleResponse = await puter.ai.chat('Tell me about cloud computing');
console.log('Simple response:', simpleResponse.message.content);

// Chat completion in test mode
const testResponse = await puter.ai.chat('Generate a test response', true);
console.log('Test mode response:', testResponse.message.content);

// Chat completion with parameters
const customResponse = await puter.ai.chat(
  [{
    role: 'user',
    content: 'Write a short poem about technology'
  }],
  {
    model: 'gpt-4o-mini', // Specify model
    temperature: 0.7, // Control randomness
    max_tokens: 150 // Limit response length
  }
);
console.log('Custom AI response:', customResponse.message.content);

// List available AI models
const models = await puter.ai.listModels();
console.log('Available models by provider:', models);
// Example output: { 'openai-completion': ['gpt-4o', 'gpt-4o-mini', ...], ... }

// List models for a specific provider
const openaiModels = await puter.ai.listModels('openai-completion');
console.log('OpenAI models:', openaiModels);

// List all available AI model providers
const providers = await puter.ai.listModelProviders();
console.log('Available providers:', providers);
// Example output: ['openai-completion', 'anthropic', 'openrouter', ...]

// Streaming chat completion
const stream = await puter.ai.chatCompleteStream(
  [{
    role: 'user',
    content: 'Explain quantum computing'
  }],
  {
    temperature: 0.5,
    max_tokens: 500
  }
);

// Process the stream
stream.on('data', (chunk) => {
  const data = JSON.parse(chunk.toString());
  if (data.success && data.result.message) {
    process.stdout.write(data.result.message.content);
  }
});

// Image generation
const image = await puter.ai.txt2img({
  prompt: 'A futuristic cityscape'
});
console.log('Generated image:', image.url);

// OCR
const ocrResult = await puter.ai.img2txt('file-id-123');
console.log('Extracted text:', ocrResult.text);

// Text-to-Speech
const audioStream = await puter.ai.txt2speech({
  text: 'Hello, world!',
  voice: 'voice-1'
});
// Handle the audio stream...
```


### Subdomain Management

```javascript
// List web sites
const sites = await puter.hosting.list();
console.log('sites:', sites);
```

## Error Handling

The SDK uses custom error classes for consistent error handling:

```javascript
try {
  await puter.fs.delete('/protected-file.txt');
} catch (error) {
  if (error.code === 'PERMISSION_DENIED') {
    console.error('Permission denied:', error.message);
  } else {
    console.error('An error occurred:', error.message);
  }
}
```

## Guidelines

- Do not use any third-party libraries or frameworks other than the ones provided unless it's really required.
- Use only the versions of the libraries or packages installed in this project.
- Follow the coding standards and best practices.
- Write clean, readable, and maintainable code.
- Reuse code whenever possible.

## Project Rules:

1. Output only the code without any explanation unless asked.
2. Always try to use the existing code as much as possible.
3. Do not explain what you're going to do unless asked.
4. We always use `pnpm` instead of `npm` for all projects.
5. You don't need to run the app (e.g. `pnpm start`...), because I'm already doing that.
6. Be brief and don't explain in details what you are doing, just focus on doing the task.
7. Do not make assumption about what could be available in the code, you even have to it lookup or ask the user.
8. Do not install any package until you ask for permission first.
9. We use `Vitest` for unit testing of the backend api in isolation from the DB, ORM...etc., and we use the pre-made `pnpm test` script command to check the test output.