@omni/sites-sdk

SDK Type-Safe e framework-agnostic para o microservice omni-sites. Esta SDK permite interagir com a API RPC do omni-sites de forma totalmente tipada e com suporte completo a internacionalização.

Características

• ✅ Type-Safe: Todos os métodos com tipagem completa TypeScript
• ✅ Framework-Agnostic: Sem dependências de React, Vue, etc.
• ✅ Locale Support: Detecção automática e manual de locale
• ✅ Error Handling: Tratamento de erros tipado
• ✅ Tree-Shakable: Estrutura modular para tree-shaking
• ✅ Dual Package: Suporte ESM e CJS
• ✅ Demo Mode: Modo demo que retorna dados fictícios quando demo: true

Instalação

npm install @omni/sites-sdk
# ou
yarn add @omni/sites-sdk
# ou
pnpm add @omni/sites-sdk

Uso Básico

import { OmniSitesClient } from '@omni/sites-sdk';

// Criar instância do cliente
const client = new OmniSitesClient({
  baseUrl: 'https://omni-sites.workers.dev',
  tenantId: 'seu-tenant-id',
  defaultLocale: 'pt-BR', // opcional
});

// Usar métodos
const posts = await client.blog.getPosts({ limit: 10 });
const post = await client.blog.getPost({ id: 'post-1' });

Modo Demo

O modo demo permite usar dados fictícios sem fazer requisições à API, útil para desenvolvimento e testes:

// Ativar modo demo
const client = new OmniSitesClient({
  baseUrl: 'https://omni-sites.workers.dev',
  tenantId: 'seu-tenant-id',
  demo: true, // Ativa modo demo
});

// Todos os métodos retornarão dados fictícios
const posts = await client.blog.getPosts({ limit: 10 }); // Dados mockados
const links = await client.links.getLinks(); // Dados mockados

Nota: No modo demo, nenhuma requisição HTTP é feita. Todos os dados são retornados de mocks internos com suporte completo a traduções.

Métodos Disponíveis

Blog

getPosts(params?, options?)

Lista posts do blog com traduções.

// Listar posts
const posts = await client.blog.getPosts({
  limit: 10,
  offset: 0,
  category: 'marketing-digital', // opcional
  locale: 'pt-BR', // opcional
});

// Com opções de requisição
const posts = await client.blog.getPosts(
  { limit: 10 },
  { locale: 'en-US', headers: { 'Custom-Header': 'value' } }
);

Parâmetros:

• params.limit?: number - Número de posts por página (padrão: 10)
• params.offset?: number - Offset para paginação (padrão: 0)
• params.category?: string - Filtrar por categoria (opcional)
• params.locale?: string - Locale específico (opcional)

Retorna: Promise<BlogPostTranslated[]>

getPost(params, options?)

Busca post específico por ID ou slug.

// Por ID
const post = await client.blog.getPost({ id: 'post-1' });

// Por slug
const post = await client.blog.getPost({ slug: 'como-comecar-sua-jornada-digital' });

// Com locale específico
const post = await client.blog.getPost(
  { id: 'post-1', locale: 'en-US' },
  { locale: 'en-US' }
);

Parâmetros:

• params.id?: string - ID do post (ou slug)
• params.slug?: string - Slug do post (ou id)
• params.locale?: string - Locale específico (opcional)

Retorna: Promise<BlogPostTranslated | null>

getCategories(locale?, options?)

Lista categorias do blog com traduções.

const categories = await client.blog.getCategories('pt-BR');

Parâmetros:

• locale?: string - Locale específico (opcional)

Retorna: Promise<BlogCategoryTranslated[]>

Links

getLinks(params?, options?)

Lista todos os links (Linktree).

const links = await client.links.getLinks({ locale: 'pt-BR' });

Parâmetros:

• params.locale?: string - Locale específico (opcional)

Retorna: Promise<LinkTranslated[]>

getLink(params, options?)

Busca link específico por ID.

const link = await client.links.getLink({ id: 'link-1', locale: 'pt-BR' });

Parâmetros:

• params.id: string - ID do link (obrigatório)
• params.locale?: string - Locale específico (opcional)

Retorna: Promise<LinkTranslated | null>

Contatos

getContacts(params?, options?)

Lista canais de contato.

const contacts = await client.contacts.getContacts({ locale: 'pt-BR' });

Parâmetros:

• params.locale?: string - Locale específico (opcional)

Retorna: Promise<ContactTranslated[]>

getContactForm(params?, options?)

Retorna configuração do formulário de contato.

const form = await client.contacts.getContactForm({ locale: 'pt-BR' });

Parâmetros:

• params.locale?: string - Locale específico (opcional)

Retorna: Promise<ContactFormConfig | null>

Newsletter

subscribe(params, options?)

Inscreve email na newsletter.

const subscription = await client.newsletter.subscribe({
  email: '[email protected]',
});

Parâmetros:

• params.email: string - Email para inscrever (obrigatório)

Retorna: Promise<NewsletterSubscription>

unsubscribe(params, options?)

Remove inscrição da newsletter.

const success = await client.newsletter.unsubscribe({
  email: '[email protected]',
  token: 'optional-token', // opcional
});

Parâmetros:

• params.email: string - Email para remover (obrigatório)
• params.token?: string - Token de desinscrição (opcional)

Retorna: Promise<boolean>

Redes Sociais

getLinks(params?, options?)

Lista links de redes sociais.

const socialLinks = await client.social.getLinks({ locale: 'pt-BR' });

Parâmetros:

• params.locale?: string - Locale específico (opcional)

Retorna: Promise<SocialLinkTranslated[]>

Detecção de Locale

A SDK suporta detecção automática de locale com a seguinte ordem de prioridade:

1. Parâmetro RPC (params.locale ou options.locale) - Prioridade 1
2. Query parameter (?locale=pt-BR) - Prioridade 2
3. Header Accept-Language - Prioridade 3
4. Configuração do tenant (defaultLocale no cliente) - Prioridade 4
5. Fallback final - pt-BR

Exemplos de Detecção

// Locale explícito no parâmetro (maior prioridade)
const posts = await client.blog.getPosts({ locale: 'en-US' });

// Locale via opções
const posts = await client.blog.getPosts({}, { locale: 'es-ES' });

// Locale padrão do cliente
const client = new OmniSitesClient({
  baseUrl: 'https://omni-sites.workers.dev',
  tenantId: 'tenant-id',
  defaultLocale: 'en-US', // usado como fallback
});

// Locale normalizado automaticamente
const posts = await client.blog.getPosts({ locale: 'pt' }); // normalizado para 'pt-BR'
const posts = await client.blog.getPosts({ locale: 'en' }); // normalizado para 'en-US'

Tratamento de Erros

A SDK lança erros tipados OmniSitesError para facilitar o tratamento:

import { OmniSitesClient, OmniSitesError } from '@omni/sites-sdk';

try {
  const post = await client.blog.getPost({ id: 'post-1' });
} catch (error) {
  if (error instanceof OmniSitesError) {
    console.error('Erro RPC:', error.code, error.message);
    console.error('Dados adicionais:', error.data);
  } else {
    console.error('Erro desconhecido:', error);
  }
}

Propriedades de OmniSitesError:

• code: number - Código de erro HTTP ou RPC
• message: string - Mensagem de erro
• data?: unknown - Dados adicionais do erro

Configuração Avançada

Headers Customizados

const client = new OmniSitesClient({
  baseUrl: 'https://omni-sites.workers.dev',
  tenantId: 'tenant-id',
  headers: {
    'X-Custom-Header': 'value',
    'Authorization': 'Bearer token',
  },
});

// Ou atualizar depois
client.setHeaders({
  'X-New-Header': 'new-value',
});

Alterar Locale Padrão

// No construtor
const client = new OmniSitesClient({
  baseUrl: 'https://omni-sites.workers.dev',
  tenantId: 'tenant-id',
  defaultLocale: 'en-US',
});

// Ou depois
client.setDefaultLocale('es-ES');

Obter Configuração Atual

const config = client.getConfig();
console.log(config.baseUrl, config.tenantId, config.defaultLocale);

Tipos TypeScript

Todos os tipos estão disponíveis para importação:

import type {
  BlogPostTranslated,
  BlogCategoryTranslated,
  LinkTranslated,
  ContactTranslated,
  ContactFormConfig,
  NewsletterSubscription,
  SocialLinkTranslated,
  Locale,
  GetBlogParams,
  GetBlogPostParams,
  // ... outros tipos
} from '@omni/sites-sdk';

Exemplos Completos

React/Next.js

'use client';

import { OmniSitesClient } from '@omni/sites-sdk';
import { useEffect, useState } from 'react';

export function BlogPosts() {
  const [posts, setPosts] = useState([]);
  
  useEffect(() => {
    const client = new OmniSitesClient({
      baseUrl: process.env.NEXT_PUBLIC_SITES_URL!,
      tenantId: process.env.NEXT_PUBLIC_TENANT_ID!,
      defaultLocale: 'pt-BR',
    });
    
    client.blog.getPosts({ limit: 10 })
      .then(setPosts)
      .catch(console.error);
  }, []);
  
  return (
    <div>
      {posts.map(post => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <p>{post.excerpt}</p>
        </article>
      ))}
    </div>
  );
}

Node.js/Express

import express from 'express';
import { OmniSitesClient } from '@omni/sites-sdk';

const app = express();
const client = new OmniSitesClient({
  baseUrl: process.env.SITES_URL!,
  tenantId: process.env.TENANT_ID!,
});

app.get('/api/blog', async (req, res) => {
  try {
    const locale = req.query.locale as string || 'pt-BR';
    const posts = await client.blog.getPosts({ locale });
    res.json(posts);
  } catch (error) {
    res.status(500).json({ error: 'Failed to fetch posts' });
  }
});

Vue.js

<script setup lang="ts">
import { ref, onMounted } from 'vue';
import { OmniSitesClient } from '@omni/sites-sdk';

const posts = ref([]);

onMounted(async () => {
  const client = new OmniSitesClient({
    baseUrl: import.meta.env.VITE_SITES_URL,
    tenantId: import.meta.env.VITE_TENANT_ID,
  });
  
  posts.value = await client.blog.getPosts({ limit: 10 });
});
</script>

Utilitários

A SDK também exporta utilitários úteis:

import {
  resolveLocale,
  normalizeLocale,
  isValidLocale,
  parseAcceptLanguage,
  getDefaultLocale,
} from '@omni/sites-sdk';

// Resolver locale de múltiplas fontes
const locale = resolveLocale({
  rpcParam: 'en-US',
  queryParam: 'pt-BR',
  acceptLanguage: 'es-ES,es;q=0.9',
  tenantDefault: 'pt-BR',
});

// Normalizar locale
const normalized = normalizeLocale('pt'); // 'pt-BR'
const normalized = normalizeLocale('en'); // 'en-US'

// Validar locale
if (isValidLocale('pt-BR')) {
  // locale válido
}

// Parsear Accept-Language header
const locale = parseAcceptLanguage('pt-BR,pt;q=0.9,en-US;q=0.8');

// Obter locale padrão
const defaultLocale = getDefaultLocale(); // 'pt-BR'

Locales Suportados

• pt-BR (padrão)
• en-US
• es-ES

Locales base (pt, en, es) são automaticamente normalizados para o formato completo.

Desenvolvimento

# Instalar dependências
npm install

# Verificar tipos
npm run type-check

# Build
npm run build

Licença

MIT