@riligar/storage-sdk

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

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.

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)

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)

const results = await storage.collection('memories').select({
  where: {
    tags: { $like: "%ui%" },
    created_at: { $gt: "2024-01-01" }
  },
  limit: 10
});

Busca Semântica (Vector Search)

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.

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).

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