npm package: @riligar/storage-sdk
Description: [![npm version](https://img.shields.io/npm/v/@riligar/storage-sdk.svg)](https://www.npmjs.com/package/@riligar/storage-sdk) [![license](https://img.shields.io/github/license/riligar-solutions/storage.svg)](LICENSE)
Latest version: 1.2.1

# @riligar/storage-sdk

[![npm version](https://img.shields.io/npm/v/@riligar/storage-sdk.svg)](https://www.npmjs.com/package/@riligar/storage-sdk)
[![license](https://img.shields.io/github/license/riligar-solutions/storage.svg)](LICENSE)

O SDK oficial do **RiLiGar Storage**. Uma interface leve e poderosa para manipulação programática de Coleções (JSON + Vetores), Blobs (Arquivos no R2) e Analytics via SQL direto.

---

## 🚀 Instalação

```bash
bun add @riligar/storage-sdk
# ou
npm install @riligar/storage-sdk
```

---

## 🔑 Autenticação

Para utilizar o SDK, você precisa de uma `API Key` (formato `sk_...`) obtida no seu Dashboard ou via administrador.

```javascript
import Storage from '@riligar/storage-sdk';

const storage = new Storage(
  'https://storage.manager.riligar.click', // URL Base
  'sk_your_api_key'                       // Sua API Key (Tenant Isolation)
);
```

---

## 📦 Módulos

### 1. Collections (JSON + Vector Storage)
Armazenamento **schema-less** onde o primeiro `insert` define a estrutura da tabela. Inclui suporte nativo para busca semântica por similaridade vetorial.

#### Inserção (INSERT)
```javascript
await storage.collection('memories').insert({
  id: "msg_123", // Opcional: auto-gerado se omitido
  content: "User prefers dark mode",
  tags: ["ui", "preference"],
  embedding: [0.1, 0.2, 0.3] // Campo vetorial para busca semântica
});
```

#### Seleção e Filtros (SQL-like)
```javascript
const results = await storage.collection('memories').select({
  where: {
    tags: { $like: "%ui%" },
    created_at: { $gt: "2024-01-01" }
  },
  limit: 10
});
```

#### Busca Semântica (Vector Search)
```javascript
const context = await storage.collection('memories').select({
  vectorIndex: 'embedding', // Nome da coluna numérica
  vector: [0.1, 0.2, 0.3],  // Embedding da query
  vectorTopK: 3             // Retorna os 3 mais próximos
});
```

---

### 2. Blobs (R2 File Storage)
Ideal para arquivos binários, imagens ou logs extensos com suporte a tracking de progresso.

```javascript
const uploadTask = storage.blob.upload(file, (p) => {
  console.log(`Progresso: ${p.percent}%`);
});

try {
  const publicUrl = await uploadTask.execute();
  console.log("Arquivo disponível em:", publicUrl);
} catch (err) {
  console.error("Upload falhou ou foi abortado");
}

// Para cancelar: uploadTask.abort();
```

---

### 3. SQL Raw (Power Analytics)
Acesso direto para consultas complexas e agregações (Somente Leitura).

```javascript
const report = await storage.sql(
  "SELECT category, count(*) as total FROM products WHERE price > ? GROUP BY category",
  [100]
);
```

---

## 🛡️ Melhores Práticas

- **Segurança**: Nunca exponha sua `sk_...` no client-side em produção. Utilize via Proxy ou Backend.
- **Vetores**: Ao salvar embeddings, utilize o formato de array numérico `[number, number, ...]`.
- **Esquema**: O sistema é dinâmico, mas lembre-se que o primeiro insert define o tipo da coluna no SQLite persistente.
- **Isolamento**: Cada `api_key` garante isolamento total por `tenant_id`.

---

## 📄 Licença

MIT © [RiLiGar Solutions](https://riligar.click)