useputer/README.md

A **Zustand store wrapper** for [Puter.js](https://puter.com) that provides **state management and hooks** for authentication, file system operations, AI tools, and key-value storage — all inside your React applications.

# 🚀 Zustand Puter.js Store

A **Zustand store wrapper** for [Puter.js](https://puter.com) that provides **state management and hooks** for authentication, file system operations, AI tools, and key-value storage — all inside your React applications.  

This package simplifies working with the `window.puter` API by handling initialization, error states, and providing a typed Zustand store interface.

---

## ✨ Features

- 🔑 **Authentication**
  - Sign in / Sign out
  - Refresh & check auth status
  - Get current user
- 📂 **File System**
  - Read / Write files
  - Upload files
  - Delete files
  - List directory contents
- 🤖 **AI**
  - Chat with AI models
  - Image-to-text conversion
  - File + message feedback
- 💾 **Key-Value Storage**
  - Get / Set / Delete keys
  - List & flush storage
- 🪝 **React Hook**
  - Powered by Zustand for reactive UI
  - `usePuterStore()` to access state and methods
- ⚡ **Auto Initialization**
  - Includes a `ClientInit` component to auto-detect and initialize Puter.js

---

## 📦 Installation

```bash
npm install useputer

or with yarn 

yarn add useputer
```

## SETUP
```
import ClientInit, { usePuterStore } from "useputer";

export default function App() {
  return (
    <>
      <ClientInit />
      <YourApp />
    </>
  );
}
```
## USAGE
```
import { usePuterStore } from "useputer";

function AuthStatus() {
  const { auth, isLoading, error } = usePuterStore();

  if (isLoading) return <p>Loading...</p>;
  if (error) return <p>Error: {error}</p>;

  return auth.isAuthenticated ? (
    <div>
      <p>Signed in as {auth.user?.username}</p>
      <button onClick={auth.signOut}>Sign Out</button>
    </div>
  ) : (
    <button onClick={auth.signIn}>Sign In</button>
  );
}
```

## FILESYSTEM
```
const { fs } = usePuterStore();

// Write file
await fs.write("/hello.txt", "Hello World");

// Read file
const blob = await fs.read("/hello.txt");
console.log(await blob?.text());

// List directory
const files = await fs.readDir("/");
console.log(files);

// Delete file
await fs.delete("/hello.txt");
```
## AI CHAT
```
const { ai } = usePuterStore();

// Chat with AI
const response = await ai.chat("Write me a poem about the sea");
console.log(response?.message.content);

// Feedback (file + text)
await ai.feedback("/document.txt", "Summarize this file");

// Image to text
const text = await ai.img2txt(myImageFile);
console.log(text);
```
## KEY VALUE STORE
```
const { kv } = usePuterStore();

// Set a value
await kv.set("theme", "dark");

// Get a value
const theme = await kv.get("theme");

// List keys
const keys = await kv.list("*");
console.log(keys);

// Flush storage
await kv.flush();
```

## 🛠️  API Reference

| Key          | Type               | Description                                |
| ------------ | ------------------ | ------------------------------------------ |
| `isLoading`  | `boolean`          | Indicates if an async operation is running |
| `error`      | `string` \| `null` | Error message if an operation fails        |
| `puterReady` | `boolean`          | True when `window.puter` is detected       |