@hirall/client/README.md

Official TypeScript/JavaScript client for Hirall - Backend-as-a-Service

# @hirall/client

Official TypeScript/JavaScript client for Hirall - Backend-as-a-Service

## Installation

```bash
npm install @hirall/client
# or
yarn add @hirall/client
# or
pnpm add @hirall/client
```

## Quick Start

```typescript
import { createClient } from '@hirall/client';

const hirall = createClient(
  'https://your-project.hirall.io',
  'your-api-key'
);

// Query data
const { data, error } = await hirall.db
  .from('users')
  .select('*')
  .eq('status', 'active')
  .execute();

// Insert data
const { data: newUser } = await hirall.db
  .from('users')
  .insert({ name: 'John Doe', email: 'john@example.com' });

// Upload file
const { data: file } = await hirall.storage
  .bucket('avatars')
  .upload('user-123.png', fileBlob);

// Authenticate
const { data: session } = await hirall.auth.signIn({
  email: 'user@example.com',
  password: 'password123'
});
```

## Features

- ✅ **Database**: PostgreSQL queries with type-safe query builder
- ✅ **Authentication**: Email/password, OAuth, magic links
- ✅ **Storage**: File upload/download with signed URLs
- ✅ **Realtime**: WebSocket subscriptions
- ✅ **Functions**: Edge function invocation
- ✅ **AI**: Embeddings, semantic search, chat
- ✅ **TypeScript**: Full type safety
- ✅ **Multi-tenant**: Project isolation built-in

## API Reference

### Database

```typescript
// Select
const { data } = await hirall.db
  .from('posts')
  .select('id, title, author')
  .eq('published', true)
  .order('created_at', { ascending: false })
  .limit(10)
  .execute();

// Insert
const { data } = await hirall.db
  .from('posts')
  .insert({ title: 'Hello World', content: '...' });

// Update
const { data } = await hirall.db
  .from('posts')
  .eq('id', 123)
  .update({ title: 'Updated Title' });

// Delete
await hirall.db
  .from('posts')
  .eq('id', 123)
  .delete();

// Raw SQL
const { data } = await hirall.db.query(
  'SELECT * FROM posts WHERE id = $1',
  [123]
);
```

### Authentication

```typescript
// Sign up
const { data: session } = await hirall.auth.signUp({
  email: 'user@example.com',
  password: 'secure-password'
});

// Sign in
const { data: session } = await hirall.auth.signIn({
  email: 'user@example.com',
  password: 'secure-password'
});

// Sign out
await hirall.auth.signOut();

// Get current user
const { data: user } = await hirall.auth.getUser();

// Listen to auth changes
const { data: subscription } = hirall.auth.onAuthStateChange((event) => {
  console.log('Auth event:', event);
});
```

### Storage

```typescript
// List buckets
const { data: buckets } = await hirall.storage.listBuckets();

// Create bucket
const { data: bucket } = await hirall.storage.createBucket('avatars', {
  public: true
});

// Upload file
const { data: file } = await hirall.storage
  .bucket('avatars')
  .upload('user-123.png', fileBlob);

// Download file
const { data: blob } = await hirall.storage
  .bucket('avatars')
  .download('user-123.png');

// Get signed URL
const { data: url } = await hirall.storage
  .bucket('avatars')
  .getSignedUrl('user-123.png', { expiresIn: 3600 });

// Delete file
await hirall.storage
  .bucket('avatars')
  .delete('user-123.png');
```

### Realtime

```typescript
// Subscribe to channel
const channel = hirall.realtime
  .channel('room-1')
  .on('message', (payload) => {
    console.log('New message:', payload);
  })
  .subscribe();

// Send message
channel.send('message', { text: 'Hello!' });

// Unsubscribe
channel.unsubscribe();
```

### Functions

```typescript
// Invoke function
const { data, error } = await hirall.functions.invoke('my-function', {
  body: { name: 'John' }
});
```

### AI

```typescript
// Generate embeddings
const { data } = await hirall.ai.generateEmbedding('Hello world');

// Semantic search
const { data: results } = await hirall.ai.semanticSearch('query', 10);

// Chat completion
const { data: response } = await hirall.ai.chat([
  { role: 'user', content: 'Hello!' }
]);
```

## Error Handling

All methods return a response object with `data` and `error`:

```typescript
const { data, error, status } = await hirall.db
  .from('users')
  .select('*')
  .execute();

if (error) {
  console.error('Error:', error.message);
  console.error('Code:', error.code);
} else {
  console.log('Data:', data);
}
```

## TypeScript Support

Full TypeScript support with type inference:

```typescript
interface User {
  id: number;
  name: string;
  email: string;
}

const { data } = await hirall.db
  .from<User>('users')
  .select('*')
  .execute();

// data is typed as User[]
```

## License

MIT

## Links

- [Documentation](https://docs.hirall.io)
- [GitHub](https://github.com/hirall/hirall-js)
- [Website](https://hirall.io)