Primeiros Passos com a Copera Starter Application

A Copera Starter Application é um portal de referência que mostra como construir um web app voltado ao cliente alimentado pelo seu workspace Copera. Ela usa um Board como banco de dados, então você pode gerenciar usuários e tickets diretamente no Copera enquanto o seu portal cuida da autenticação, do envio e da exibição.

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte instalado e disponível:

Requisito	Versão / Observações
Node.js	>= 24.0.0
pnpm	10.16.1
Banco de dados	Uma instância local ou um banco de dados gerenciado na nuvem
Workspace Copera	Um workspace ativo com um Board configurado (veja o Passo 2)

Passo 1: Clone o Repositório

A starter application será publicada em github.com/copera-ai. Assim que estiver disponível, clone-a para a sua máquina local:

git clone https://github.com/copera-ai/starter-application.git
cd starter-application

observação

Se o repositório ainda não for público, verifique novamente em github.com/copera-ai ou entre em contato com o time do Copera para obter acesso antecipado.

Passo 2: Configure Seu Board no Copera

A starter application lê e escreve em um Copera Board. Você precisa criar um Board com duas tabelas — Users e Tickets — e depois copiar os IDs relevantes para o arquivo de config da aplicação.

Crie o Board

No seu workspace Copera, vá em Collaborate na sidebar e crie um novo Board. Dê a ele um nome como "Portal Data".

Configure a Tabela Users

Seu Board terá uma tabela padrão. Renomeie-a para Users e adicione as seguintes colunas:

Nome da Coluna	Tipo de Campo	Observações
Name	Text	O nome de exibição do usuário
Identifier	Text	O endereço de email do usuário (usado para login)
Password	Password	Armazenada com segurança; usada para autenticação no portal
Role	Select (Dropdown)	Adicione duas opções: admin e user

Configure a Tabela Tickets

Adicione uma segunda tabela ao Board e nomeie-a Tickets. Adicione as seguintes colunas:

Nome da Coluna	Tipo de Campo	Observações
Title	Text	Um resumo curto do ticket
Details	Paragraph (Text)	Descrição completa da solicitação
User	Link	Link para a tabela Users
Status	Select (Dropdown)	Adicione opções como open, in progress, closed
Request Type	Select (Dropdown)	Adicione opções relevantes ao seu caso de uso

Encontre Seu Board ID, Table IDs e Column IDs

Você precisa copiar vários IDs para o config da aplicação. Veja onde encontrar cada um:

• Board ID — O Board ID aparece na URL quando você está com o Board aberto. Ele se parece com: app.copera.ai/boards/6abc123.... Copie o trecho depois de /boards/.
• Table ID — Abra o Board, depois clique na aba com o nome da tabela no topo. O Table ID é mostrado no painel de configurações da tabela, ou você pode encontrá-lo na URL após navegar para dentro da tabela.
• Column ID — Clique no ícone de configurações (engrenagem ou menu de três pontos) em qualquer cabeçalho de coluna. O painel de configurações da coluna mostrará o ID dela. Copie esse valor para cada coluna que você precisa referenciar.

Para um passo a passo completo, veja Encontrando Board, Table e Column IDs.

dica

Mantenha um arquivo de texto aberto enquanto copia os IDs — você vai precisar de um Board ID, dois Table IDs e vários Column IDs antes de avançar para o próximo passo.

Edite src/config.ts

Abra src/config.ts no repositório clonado e preencha os IDs que você coletou:

export const config = {
  boardId: 'YOUR_BOARD_ID',
  tables: {
    users: {
      tableId: 'YOUR_USERS_TABLE_ID',
      columns: {
        name: 'YOUR_NAME_COLUMN_ID',
        identifier: 'YOUR_IDENTIFIER_COLUMN_ID',
        password: 'YOUR_PASSWORD_COLUMN_ID',
        role: 'YOUR_ROLE_COLUMN_ID',
      },
    },
    tickets: {
      tableId: 'YOUR_TICKETS_TABLE_ID',
      columns: {
        title: 'YOUR_TITLE_COLUMN_ID',
        details: 'YOUR_DETAILS_COLUMN_ID',
        user: 'YOUR_USER_COLUMN_ID',
        status: 'YOUR_STATUS_COLUMN_ID',
        requestType: 'YOUR_REQUEST_TYPE_COLUMN_ID',
      },
    },
  },
};

Passo 3: Configure as Variáveis de Ambiente

A aplicação usa um arquivo .env para armazenar secrets e detalhes de conexão. Copie o arquivo de exemplo para começar:

cp .env.example .env

Abra o .env e preencha os seguintes valores:

Variável	Descrição
MONGODB_URI	A connection string para a instância do seu banco de dados (ex.: mongodb://localhost:27017/starter ou sua URI do Atlas)
APP_TOKEN	Qualquer string secreta usada para assinar os JWTs do gerenciamento de sessão do portal (ex.: uma string aleatória longa)
COPERA_API_KEY	Um token de API do Copera usado pelo SDK. Use uma Integration API Key (com prefixo cp_key_) ou um Personal Access Token (com prefixo cp_pat_), criados em Workspace Settings → Integrations

Para o app web (frontend), defina uma variável adicional:

Variável	Descrição
VITE_SERVER_URL	A URL onde o servidor da API vai rodar (ex.: http://localhost:3000)

dica

Você pode gerar uma string aleatória segura para o APP_TOKEN usando openssl rand -hex 32 no seu terminal.

Encontrando Seu Token de API do Copera

1. No Copera, abra Workspace Settings → Integrations.
2. Para criar uma Integration API Key (com prefixo cp_key_), abra a aba API Keys e crie uma nova key. Integration API Keys funcionam para operações de board e channel, que é tudo de que a Starter Application precisa.
3. Para criar um Personal Access Token (com prefixo cp_pat_), abra a aba Personal Tokens e crie um novo token. Um PAT desbloqueia toda a superfície da API.
4. Copie o token imediatamente — ele é mostrado apenas uma vez — e cole-o em COPERA_API_KEY no seu arquivo .env.

Para uma explicação mais aprofundada dos tipos de token e escopos, veja o guia de Autenticação.

Passo 4: Instale as Dependências e Execute

Com a configuração concluída, instale as dependências e inicie a API e o app web juntos:

pnpm install
pnpm dev

Isso inicia ambos os serviços simultaneamente:

• Servidor da API — roda na porta definida no seu .env (padrão: http://localhost:3000)
• App web — roda no servidor de dev (padrão: http://localhost:5173)

Abra seu navegador e navegue até a URL do app web. Você verá a página de login do portal.

Passo 5: Crie Seu Primeiro Usuário

O portal não tem um formulário de cadastro público por padrão — os usuários são gerenciados diretamente no seu Copera Board. Para criar o primeiro usuário:

1. No Copera, abra o Board que você configurou e navegue até a tabela Users.
2. Adicione uma nova linha e preencha as colunas Name, Identifier (email), Password e Role.
3. Volte para o app web no seu navegador.
4. Faça login usando o email e a senha que você acabou de inserir.

observação

As senhas inseridas no Board são tratadas pela camada de autenticação da aplicação. O comportamento exato depende de como a starter app processa as credenciais — consulte os arquivos src/config.ts e do serviço de auth para mais detalhes.

O Que Vem a Seguir

Agora que a aplicação está rodando, aqui estão algumas direções para ir além:

• Customize o portal para o seu caso de uso — Ajuste a UI, adicione novas páginas ou mude os campos do formulário de ticket para combinar com o seu workflow.
• Adicione colunas ao seu Board — Qualquer nova coluna que você adicionar no Copera pode ser referenciada no app adicionando o Column ID dela em src/config.ts.
• Use ferramentas de IA para construir novos recursos — A starter app foi projetada para ser um ponto de partida. Use assistentes de código com IA junto com a API do Copera para acelerar o desenvolvimento.
• Explore a API do Copera — Revise a API Reference para entender quais operações de dados estão disponíveis além do que a starter app demonstra.

dica

Quando você adicionar uma nova coluna ao seu Board no Copera, lembre-se de também adicionar o Column ID dela na seção relevante de src/config.ts para que a aplicação possa ler e escrever nesse campo.