Skip to Content
Guia rápido

Guia rápido

Este guia segue o fluxo recomendado para usar o Meaple SDK em 4 etapas simples.

Instalação

Instale os pacotes que você vai usar:

# Pacotes essenciais (Core + tipos)
bun add @meaple-com/core @meaple-com/types
 
# Para React (opcional): hooks e/ou componentes headless
bun add @meaple-com/react-query @meaple-com/react-headless-components
bun add @tanstack/react-query

Criar a instância

Crie uma instância do SDK com o ID do seu canal (publicKey) e a URL base da API:

// lib/meaple.ts
import { MeapleSDK } from '@meaple-com/core';
 
export const sdk = new MeapleSDK({
  publicKey: 'cml9fi1xh00003b6qo2sqzeeh', // ID do canal (painel meaple.com.br)
  baseURL: 'https://api.meaple.app', // URL base da API
});

📋 Onde obter as credenciais

  • publicKey: ID do canal, obtido no painel em meaple.com.br . É o mesmo client_id usado no OAuth2.
  • baseURL: Para desenvolvimento use https://api.meaple.app. Use https://api.meaple.com.br em produção.
  • Variáveis de ambiente: em Next.js, use NEXT_PUBLIC_* para client-side; use MEAPLE_* (sem prefixo) para server-side.

Usando React Query ou Headless Components

Se você usa @meaple-com/react-query ou @meaple-com/react-headless-components, configure o Provider no layout (ou componente raiz):

// app/layout.tsx ou pages/_app.tsx
import { MeapleSDKProvider } from '@meaple-com/react-query';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { sdk } from '@/lib/meaple';
 
const queryClient = new QueryClient();
 
export default function RootLayout({ children }) {
  return (
    <QueryClientProvider client={queryClient}>
      <MeapleSDKProvider sdk={sdk}>
        {children}
      </MeapleSDKProvider>
    </QueryClientProvider>
  );
}

Como os pacotes se relacionam

Somente o Core (@meaple-com/core) faz chamadas HTTP para a API. Os demais pacotes trabalham em cima dele:

  • React Query — hooks (como useEvents e useCreateOrder) que recebem o SDK via MeapleSDKProvider e chamam internamente os métodos do Core.
  • Headless Components — componentes (como ListEvents e Cart) que usam os hooks do React Query e, em alguns casos, o Core diretamente.

Em resumo: Headless → React Query → Core (ou às vezes, Headless → Core).

Consumir as APIs

O canal é identificado pelo header X-Channel-Id (configurado no SDK). Você não precisa passar channelId nas chamadas.

Core (server ou client)

// Listar eventos (priority: 0 é necessário para retornar resultados)
const { events } = await sdk.events.find({ priority: 0, limit: 20 });
 
// Evento por slug
const event = await sdk.events.getBySlug('event-slug');
 
// Categorias (retorna array)
const categories = await sdk.categories.find();
 
// Ingressos de um evento
const { tickets, groups } = await sdk.events.getTickets(eventId);

No React

Se você usa React Query ou Headless Components, os exemplos concretos (listar eventos, carrinho, cupom, etc.) estão nas páginas React Query e Headless Components.

Autenticação (quando necessário)

Muitas rotas são públicas e não exigem login. Para perfil, pedidos e ingressos do usuário, é preciso autenticar.

O Meaple usa OAuth 2.0 com PKCE. Depois de concluir o fluxo de login e obter o access_token, configure-o na instância:

sdk.setGlobalToken('seu_access_token');
 
// A partir daqui você pode chamar rotas autenticadas
const user = await sdk.users.getMe();
const orders = await sdk.users.getOrders();

Com token (rotas autenticadas)

Após sdk.setGlobalToken('...'):

const user = await sdk.users.getMe();
const orders = await sdk.users.getOrders({ status: 'PAID' });
const events = await sdk.users.getEvents();

📖 Guia completo de autenticação

Para implementar o fluxo OAuth2 (autorização, troca de código por token, refresh e integração com better-auth), veja Autenticação.

Próximos passos

Last updated on
InícioIntrodução