iluria-sdk

v0.6.14

Published

10 months ago

SDK oficial do Iluria para integração com lojas e criação de frontends customizados

0High
0Medium
0Low

lorenzo.iluria

joao.camera

pedroiluria

iluria sdk api ecommerce storefront template-engine static-site

Iluria SDK

SDK JavaScript oficial do Iluria para integração com lojas e criação de frontends customizados.

🎯 O que é?

O Iluria SDK é um motor de substituição de conteúdo que permite:

Sites estáticos: Substitui automaticamente conteúdo HTML usando data attributes
Apps React/Vue/Angular: Acesso programático aos dados da loja via API
Node.js: Integração server-side com cache inteligente

SDK com suporte a múltiplas formas de autenticação: API Key, Token JWT ou validação por domínio!

⚡ Início Rápido (30 segundos)

HTML Estático - Mais Simples!

<!DOCTYPE html>
<html>
<body>
  <h1 data-iluria="store.storeName">Carregando...</h1>
  <img data-iluria-src="store.logoUrl" alt="Logo">
  
  <script src="https://unpkg.com/@iluria/sdk"></script>
  <script>
    IluriaSDK.init('sua-api-key-aqui');
  </script>
</body>
</html>

Pronto! O SDK substitui automaticamente o conteúdo. 🎉

📦 Instalação Completa

NPM (Projetos Node.js/React/Vue/Angular)

npm install @iluria/sdk

HTML Estático (sem build)

<!-- Via unpkg (recomendado) -->
<script src="https://unpkg.com/iluria-sdk@latest/dist/iluria-sdk.min.js"></script>

<!-- Versão específica -->
<script src="https://unpkg.com/[email protected]/dist/iluria-sdk.min.js"></script>

🚀 Início Rápido

Node.js / React / Vue

import IluriaSDK from '@iluria/sdk';

// Simples assim - só precisa da API Key!
const sdk = new IluriaSDK('sua-api-key-aqui');

// Buscar dados da loja
const storeName = await sdk.store.getName();
const logoUrl = await sdk.store.getLogoUrl();

HTML Estático (Sites sem build)

<!DOCTYPE html>
<html>
<head>
    <title>Minha Loja</title>
</head>
<body>
    <!-- Elementos com data-iluria são substituídos automaticamente -->
    <h1 data-iluria="store.storeName">Carregando...</h1>
    <img data-iluria-src="store.logoUrl" alt="Logo">
    
    <!-- SDK via unpkg -->
    <script src="https://unpkg.com/@iluria/sdk"></script>
    <script>
        // Inicializa e substitui conteúdo automaticamente
        IluriaSDK.init('sua-api-key-aqui');
    </script>
</body>
</html>

📖 Documentação Completa

Autenticação

O SDK suporta 3 formas de autenticação:

1. API Key (Recomendado para aplicações públicas)

const sdk = new IluriaSDK({
  apiKey: 'eyJhbGciOiJSUzI1NiJ9...'
});

Para obter uma API Key:

Acesse o painel administrativo do Iluria
Navegue até Configurações > API Keys
Clique em Nova Chave Pública
Dê um nome descritivo (ex: "Meu Site")
Copie a chave gerada (não será exibida novamente!)

2. Token JWT (Para contextos autenticados)

const sdk = new IluriaSDK({
  token: 'eyJhbGciOiJIUzI1NiJ9...'
});

3. Sem Autenticação (Validação por domínio)

// O SDK pode funcionar sem autenticação!
// O storefront identifica a loja pelo domínio da requisição
const sdk = new IluriaSDK();
// ou
const sdk = new IluriaSDK({
  baseURL: 'https://minhaloja.com.br'
});

Sessão de clientes (cookies + auto refresh)

O SDK gerencia automaticamente a sessão dos clientes autenticados sem precisar incluir código extra nos HTMLs:

Login, cadastro e OAuth salvam a sessão e agendam a renovação do access token alguns segundos antes do vencimento.
Ao abrir a página, o SDK tenta reidratar cookies válidos chamando /api/storefront/customer/refresh em segundo plano.
Se o usuário voltar horas depois, ele continua logado enquanto o refresh token continuar válido (2h padrão, 30 dias com rememberMe).
O estado da sessão é sincronizado entre abas via localStorage, evitando múltiplos refresh simultâneos.

Configuração opcional ao iniciar o SDK (browser ou Node):

const sdk = IluriaSDK.init({
  apiKey: 'sua-api-key',
  customerSession: {
    rememberMeDefault: true,    // usa "lembrar-me" automaticamente em fluxos OAuth/claim
    refreshAheadSeconds: 60,    // renova 60s antes de expirar
    autoHydrate: true,          // tenta refresh na carga inicial da página
    enabled: true,              // defina false para desativar o gerenciador
    debug: false                // true habilita logs de debug no console
  }
});

Dica: para que o cliente permaneça autenticado após longos períodos de inatividade, envie rememberMe: true ao chamar customer.login() ou defina customerSession.rememberMeDefault: true. Assim o refresh token terá validade estendida (30 dias) e o SDK fará a renovação automática ao retornar.

Métodos Disponíveis

Node.js / Bundlers

// Inicialização com diferentes métodos de auth
const sdk = new IluriaSDK('api-key');              // Forma simplificada
const sdk = new IluriaSDK({ apiKey: 'key' });      // Com API Key
const sdk = new IluriaSDK({ token: 'jwt' });       // Com token JWT
const sdk = new IluriaSDK();                       // Sem auth (usa domínio)

// Métodos assíncronos
await sdk.store.getName();           // Nome da loja
await sdk.store.getLogoUrl();        // URL do logo
await sdk.store.getFaviconUrl();     // URL do favicon  
await sdk.store.getData();           // Todos os dados

// Mudar autenticação dinamicamente
sdk.setApiKey('nova-api-key');       // Troca para API Key
sdk.setToken('novo-token');          // Troca para token JWT
sdk.setApiKey(null);                 // Remove auth (usa domínio)

// Cache
sdk.clearCache();                     // Limpa cache
sdk.store.setCacheTTL(300000);       // 5 minutos

Browser (HTML Estático)

O SDK para browser tem superpoderes! Ele substitui automaticamente o conteúdo HTML:

<!-- Substituição de Texto -->
<h1 data-iluria="store.storeName">Nome Padrão</h1>
<p data-iluria="store.metaDescription">Descrição</p>

<!-- Substituição de Atributos -->
<img data-iluria-src="store.logoUrl" src="placeholder.jpg">
<a data-iluria-href="store.website">Link</a>
<div data-iluria-bg="store.bannerUrl">Banner</div>

<!-- Condicionais -->
<div data-iluria-if="store.logoUrl">Logo existe!</div>
<div data-iluria-unless="store.maintenance">Loja aberta!</div>

Formas de Inicialização (Browser)

1. Auto-inicialização com API Key

<script src="https://unpkg.com/@iluria/sdk"></script>
<script>
    // Mais simples - passa direto a API Key
    IluriaSDK.init('sua-api-key');
</script>

2. Configuração Customizada

<script>
    IluriaSDK.init({
        apiKey: 'sua-api-key',
        autoReplace: true,      // Substitui elementos automaticamente (padrão: true)
        cacheTTL: 60000        // Cache de 1 minuto (padrão)
    });
</script>

3. Controle Manual

<script>
    const sdk = new IluriaSDK('sua-api-key');
    
    // Inicializa manualmente
    sdk.init().then(data => {
        console.log('Dados:', data);
        
        // Acesso programático
        document.getElementById('nome').textContent = sdk.getName();
        document.getElementById('logo').src = sdk.getLogoUrl();
    });
</script>

Eventos do Browser

// Dados carregados com sucesso
document.addEventListener('iluria:loaded', (event) => {
    console.log('Dados:', event.detail);
});

// Erro ao carregar
document.addEventListener('iluria:error', (event) => {
    console.error('Erro:', event.detail);
});

🎨 Exemplos Práticos

Site Estático Completo

<!DOCTYPE html>
<html lang="pt-BR">
<head>
    <meta charset="UTF-8">
    <title data-iluria="store.metaTitle">Minha Loja</title>
    <meta name="description" content="">
    <style>
        body { font-family: sans-serif; padding: 40px; }
        .logo { max-width: 200px; }
    </style>
</head>
<body>
    <header>
        <img class="logo" data-iluria-src="store.logoUrl" alt="Logo">
        <h1 data-iluria="store.storeName">Nome da Loja</h1>
        <p data-iluria="store.metaDescription">Descrição da loja</p>
    </header>

    <script src="https://unpkg.com/@iluria/sdk"></script>
    <script>
        IluriaSDK.init('eyJhbGciOiJSUzI1NiJ9...');
    </script>
</body>
</html>

React Component

import { useEffect, useState } from 'react';
import IluriaSDK from '@iluria/sdk';

function StoreHeader() {
    const [storeData, setStoreData] = useState(null);
    
    useEffect(() => {
        const sdk = new IluriaSDK('sua-api-key');
        sdk.store.getData().then(setStoreData);
    }, []);
    
    if (!storeData) return <div>Carregando...</div>;
    
    return (
        <header>
            <img src={storeData.logoUrl} alt="Logo" />
            <h1>{storeData.storeName}</h1>
            <p>{storeData.metaDescription}</p>
        </header>
    );
}

Vue Component

<template>
  <header v-if="store">
    <img :src="store.logoUrl" alt="Logo">
    <h1>{{ store.storeName }}</h1>
    <p>{{ store.metaDescription }}</p>
  </header>
</template>

<script>
import IluriaSDK from '@iluria/sdk';

export default {
  data() {
    return { store: null };
  },
  async mounted() {
    const sdk = new IluriaSDK('sua-api-key');
    this.store = await sdk.store.getData();
  }
};
</script>

🔧 Configurações Avançadas

Detecção Automática de URL

O SDK detecta automaticamente o ambiente:

Desenvolvimento (localhost, 127.0.0.1, file://) → http://localhost:8080
Produção → https://api.iluria.com

Para forçar uma URL específica:

const sdk = new IluriaSDK({
    apiKey: 'sua-api-key',
    baseURL: 'https://api.custom.com'
});

Cache Inteligente Multi-Camada

O SDK agora tem um sistema de cache robusto com duas camadas:

Browser SDK

Memory Cache: LRU com até 100 items
SessionStorage: Persiste entre reloads
TTL: 5 minutos por padrão

// Configuração do cache
const sdk = IluriaSDK.init({
  apiKey: 'sua-api-key',
  cache: true,              // Habilitar cache (default: true)
  cacheTTL: 300000,        // 5 minutos (default)
  cacheStorage: 'session', // 'session' ou 'local'
  cacheDebug: false        // Logs de debug
});

// Estatísticas do cache
const stats = await sdk.getCacheStats();
console.log(stats);
// {
//   hits: 10,
//   misses: 2,
//   hitRate: "83.33%",
//   memory: { size: 3, maxSize: 100 },
//   storage: { size: 5, maxSize: 1000 }
// }

// Invalidar cache seletivamente
await sdk.invalidateCache('iluria:graphql:*'); // Remove queries GraphQL
await sdk.invalidateCache('*'); // Remove tudo

// Inspecionar item específico
const info = await sdk.inspectCache('iluria:graphql:123456');

// Limpar todo o cache
await sdk.clearCache();

Performance

Primeira chamada: ~200ms (fetch da API)
Chamadas subsequentes: ~5ms (do cache)
Cache persiste entre page reloads
Deduplica requests simultâneas

Node.js SDK

// Cache configurável por módulo
sdk.store.setCacheTTL(300000); // 5 minutos
sdk.product.setCacheTTL(600000); // 10 minutos

🏗️ Estrutura dos Dados

interface StoreData {
    storeName: string;        // Nome da loja
    logoUrl: string;          // URL do logotipo
    faviconUrl: string;       // URL do favicon
    metaTitle: string;        // Título para SEO
    metaDescription: string;  // Descrição para SEO
    seoImageUrl: string;      // Imagem para compartilhamento
}

📊 Casos de Uso

1. Site Institucional Separado

Cliente quer um site institucional fora do Iluria mas com dados sincronizados:

<script src="https://unpkg.com/@iluria/sdk"></script>
<script>IluriaSDK.init('api-key');</script>

2. Aplicação React/Next.js Customizada

npm install @iluria/sdk

import IluriaSDK from '@iluria/sdk';
const sdk = new IluriaSDK(process.env.ILURIA_API_KEY);

3. Preview no Editor de Layout (Admin)

// Injetado automaticamente pelo editor
const sdk = new IluriaSDK(previewApiKey);
await sdk.init();

🐛 Resolução de Problemas

Erro: "API Key is required"

Verifique se a API Key foi configurada corretamente
Confirme que copiou a chave completa do admin

Erro: "Store not found"

A API Key pode estar inválida ou expirada
Verifique se a loja existe e está ativa

Erro: CORS

Em desenvolvimento, certifique-se que o StoreFront está rodando em localhost:8080
Em produção, confirme que seu domínio está autorizado

Cache não atualiza

// Force refresh
sdk.clearCache();
await sdk.store.getData();

📚 Scripts de Build

Desenvolvimento

npm install        # Instalar dependências
npm run build      # Gerar builds
npm test           # Testar com exemplo

Builds Gerados

dist/
├── index.js           # CommonJS (Node.js)
├── browser.js         # Browser (não minificado)
└── browser.min.js     # Browser (minificado)

💾 Sistema de Cache

O Iluria SDK possui um sistema de cache inteligente e configurável que melhora drasticamente a performance, reduzindo chamadas desnecessárias à API.

Como Funciona

O cache funciona em múltiplas camadas, cada uma com características específicas:

Memory Cache (Padrão: 50 items, TTL: 60s)
- Mais rápido, volátil
- Usa algoritmo LRU (Least Recently Used)
- Ideal para dados acessados frequentemente
Storage Cache (Padrão: sessionStorage, TTL: 5min)
- Persistente durante a sessão
- Compartilhado entre abas (localStorage)
- Fallback automático se memória estiver cheia

Configuração Básica

// Configuração padrão (zero config)
const sdk = new IluriaSDK('sua-api-key');
// Cache automático de 60 segundos em memória

// Desabilitar cache completamente
const sdk = new IluriaSDK({
  apiKey: 'sua-api-key',
  cache: false
});

// Configuração customizada
const sdk = new IluriaSDK({
  apiKey: 'sua-api-key',
  cache: {
    maxMemorySize: 100,      // Máximo de 100 items em memória
    ttl: 120000,             // 2 minutos de TTL padrão
    storage: 'local',        // 'local' | 'session' | false
    storageTtl: 600000,      // 10 minutos no storage
    debug: true              // Logs detalhados
  }
});

Estratégias de Cache

O SDK escolhe automaticamente onde cachear baseado no tamanho dos dados:

< 100KB: Memory + Storage
100KB - 1MB: Apenas Storage
> 1MB: Não cacheia (muito grande)

Invalidação de Cache

// Limpar todo o cache
await sdk.clearCache();

// Invalidar cache específico (com pattern)
await sdk.invalidateCache('product:*');  // Invalida todos os produtos
await sdk.invalidateCache('product:123'); // Invalida produto específico
await sdk.invalidateCache('store:*');     // Invalida dados da loja

Métricas e Debug

// Obter estatísticas do cache
const stats = await sdk.getCacheStats();
console.log(stats);
// {
//   total: { hitRate: 0.89, hits: 145, misses: 22 },
//   layers: [
//     { type: 'MemoryCache', size: 23, hitRate: 0.87 },
//     { type: 'StorageCache', size: 45, hitRate: 0.92 }
//   ]
// }

// Inspecionar item específico
const info = await sdk.inspectCache('store:storeName');
console.log(info);

// Modo debug (logs detalhados)
const sdk = new IluriaSDK({
  apiKey: 'sua-api-key',
  cache: { debug: true }
});

Comportamento do Cache

Cache Hit Flow

Verifica Memory Cache (< 1ms)
Se não encontrar, verifica Storage (< 10ms)
Se não encontrar, busca da API (100-300ms)
Salva em todas as camadas aplicáveis

Cache Promotion

Quando um dado é encontrado em uma camada inferior (mais lenta), ele é automaticamente promovido para camadas superiores (mais rápidas) para próximos acessos.

Eviction Policy

Memory: LRU - Remove items menos usados recentemente
Storage: Remove 20% dos items mais antigos quando atinge quota

Cenários de Uso

E-commerce de Alto Tráfego

const sdk = new IluriaSDK({
  apiKey: 'sua-api-key',
  cache: {
    maxMemorySize: 200,     // Mais items em memória
    ttl: 30000,             // 30 segundos (produtos mudam rápido)
    storage: 'session'       // Não persiste entre sessões
  }
});

Site Institucional

const sdk = new IluriaSDK({
  apiKey: 'sua-api-key',
  cache: {
    ttl: 3600000,           // 1 hora (conteúdo estático)
    storage: 'local'         // Persiste entre sessões
  }
});

Desenvolvimento/Debug

const sdk = new IluriaSDK({
  apiKey: 'sua-api-key',
  cache: false  // Sem cache, sempre fresh data
});

Performance Esperada

| Operação | Sem Cache | Com Cache (hit) | Melhoria | |----------|-----------|-----------------|----------| | store.getName() | ~200ms | ~1ms | 200x | | product.getById() | ~150ms | ~1ms | 150x | | products.list() | ~300ms | ~10ms | 30x | | Navegação entre páginas | ~500ms | ~15ms | 33x |

Considerações

Cache é transparente: Funciona automaticamente sem código adicional
Degradação graciosa: Se storage falhar, usa apenas memória
Sem vendor lock-in: Pode trocar estratégia sem mudar código
Thread-safe: Storage compartilhado entre abas é sincronizado
Quota management: Lida automaticamente com storage cheio

🚀 Vantagens

✅ Simples: Apenas uma API Key
✅ Inteligente: Detecta ambiente automaticamente
✅ Performático: Cache inteligente em múltiplas camadas
✅ Flexível: Funciona em qualquer lugar
✅ Leve: ~10KB minificado
✅ Sem Dependências: Zero deps no browser

📄 Licença

MIT

🆘 Suporte

Documentação: https://docs.iluria.com
GitHub: https://github.com/iluria/sdk
Email: [email protected]