ChatGPT Plugin - Integração com Vectora Cloud

# Testar acesso a Vectora Cloud
curl -X GET https://api.vectora.app/v1/health \
  -H "Authorization: Bearer vca_live_xxxxx"

# Esperado: 200 OK com status "healthy"

# Testar se a API Key funciona
curl -X POST https://api.vectora.app/v1/search \
  -H "Authorization: Bearer vca_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "test query",
    "namespace": "seu-namespace",
    "top_k": 1
  }'

# Esperado: 200 OK com array vazio ou 1 resultado

openapi: 3.0.0
info:
  title: Vectora Cloud API
  version: 1.0.0
  description: "Integração de busca semântica de codebase com MongoDB Atlas Vector Search"
servers:
  - url: https://api.vectora.app/v1/plugins
    description: "Endpoint gerenciado da Vectora Cloud"

paths:
  /search:
    post:
      summary: "Busca semântica por código, documentação e padrões"
      operationId: search_context
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [query, namespace]
              properties:
                query:
                  type: string
                  description: "Pergunta natural ou termo de busca (ex: 'Como validar JWT?')"
                  example: "token validation"
                namespace:
                  type: string
                  description: "Nome do projeto (namespace)"
                  example: "seu-projeto"
                top_k:
                  type: integer
                  description: "Número máximo de resultados (padrão: 5, máximo: 20)"
                  default: 5
                  minimum: 1
                  maximum: 20
                strategy:
                  type: string
                  description: "Estratégia de busca: 'semantic' ou 'structural'"
                  enum: ["semantic", "structural"]
                  default: "semantic"
      responses:
        "200":
          description: "Resultados encontrados com sucesso"
          content:
            application/json:
              schema:
                type: object
                properties:
                  chunks:
                    type: array
                    items:
                      type: object
                      properties:
                        file:
                          type: string
                          example: "src/auth/jwt.ts"
                        line:
                          type: integer
                          example: 45
                        code:
                          type: string
                        precision:
                          type: number
                          example: 0.92
                  metadata:
                    type: object
                    properties:
                      total:
                        type: integer
                      latency_ms:
                        type: integer
        "400":
          description: "Requisição inválida"
        "401":
          description: "API Key inválida ou expirada"
        "404":
          description: "Namespace não encontrado"

  /analyze-dependencies:
    post:
      summary: "Encontra todas as referências e dependências de um símbolo"
      operationId: analyze_dependencies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [symbol, namespace]
              properties:
                symbol:
                  type: string
                  description: "Nome da função, classe ou variável"
                  example: "getUserById"
                namespace:
                  type: string
                  description: "Nome do projeto"
                include_indirect:
                  type: boolean
                  description: "Incluir referências indiretas"
                  default: true
                depth:
                  type: integer
                  description: "Profundidade máxima de análise (1-3)"
                  default: 2
      responses:
        "200":
          description: "Análise de dependências concluída"
          content:
            application/json:
              schema:
                type: object
                properties:
                  direct_calls:
                    type: array
                    items:
                      type: object
                  indirect_calls:
                    type: array
                  callers:
                    type: array

  /file-summary:
    post:
      summary: "Retorna estrutura e resumo de um arquivo"
      operationId: file_summary
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [path, namespace]
              properties:
                path:
                  type: string
                  description: "Caminho do arquivo (relativo ao projeto)"
                  example: "src/auth/validate.ts"
                namespace:
                  type: string
                  description: "Nome do projeto"
                include_dependencies:
                  type: boolean
                  description: "Incluir lista de dependências do arquivo"
                  default: true
      responses:
        "200":
          description: "Resumo do arquivo"
          content:
            application/json:
              schema:
                type: object
                properties:
                  file:
                    type: string
                  functions:
                    type: array
                  classes:
                    type: array
                  dependencies:
                    type: array
                  summary:
                    type: string

components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: "Bearer token (vca_live_xxxxx)"

security:
  - apiKeyAuth: []

Você é um assistente EXPERT em análise de código usando Vectora Cloud.

## REGRA FUNDAMENTAL
Sempre use Vectora para buscar contexto REAL do codebase.
Nunca adivinhe ou use conhecimento genérico.
Citação precisa > Velocidade.

## PROCEDIMENTO PARA PERGUNTAS DE CÓDIGO

1. INTERPRETAR: Entenda o que o usuário quer
2. BUSCAR: Use "search_context" com query precisa
   - Query deve ser: "função X", "padrão Y", "erro Z"
   - Use namespace correto
   - top_k=5 (máximo 10)
3. ANALISAR: Se obteve código:
   - Mostre arquivo e linha exatamente
   - Cite trechos relevantes (<10 linhas)
   - Explique o contexto do projeto
4. COMPLEMENTAR: Se precisa entender mais:
   - Use "analyze-dependencies" para chamadores/dependências
   - Use "file-summary" para estrutura do arquivo
5. RESPONDER: Sempre cite:
   - Arquivo: src/auth/jwt.ts
   - Linha: 45
   - Trecho relevante: 3-5 linhas
   - Explicação: por que é assim

## EXEMPLOS DE BOAS RESPOSTAS

 BOM:
"Encontrei em src/auth/validate.ts:23:
\`\`\`typescript
function validateToken(token: string) {
  const decoded = jwt.verify(token, SECRET);
  return decoded.payload;
}
\`\`\`
Seu projeto valida tokens assim. A função..."

 RUIM:
"Tokens geralmente são validados... Acho que está em algum arquivo..."

## REGRAS DE PRIVACIDADE
- Nunca exponha secrets/credentials (mesmo se Vectora retornar)
- Redija senhas, chaves, tokens
- Avise o usuário: "Encontrei credentials - não mostrarei"

## NAMESPACE PADRÃO
- Caso o usuário não mencione: pergunte qual projeto
- Se houver dúvida: use "seu-projeto" ou "default"

## QUANDO USAR CADA TOOL

| Situação | Tool | Quando |
|----------|------|--------|
| "Como faz X?" | search_context | Procurar padrão, função, documentação |
| "Quem chama Y?" | analyze_dependencies | Encontrar referências |
| "O que tem em Z.ts?" | file_summary | Entender estrutura arquivo |
| Múltiplas perguntas | search + analyze | Combinar para contexto completo |

Você: "Como funciona o sistema de autenticação JWT aqui?"

ChatGPT (com Vectora):
Encontrei a implementação em 3 arquivos principais:

1. **src/auth/jwt.ts** (definição)
   function validateToken(token: string) {
     const decoded = jwt.verify(token, SECRET_KEY);
     return decoded.payload;
   }

2. **src/guards/auth.guard.ts** (aplicação em rotas)
   @UseGuards(AuthGuard)
   async getProfile(@Req() req) {
     // Já está autenticado aqui
   }

3. **src/tests/auth.test.ts** (exemplos)
   it('should reject expired token', () => {
     // Teste mostra comportamento esperado
   })

**Fluxo**:
request → AuthGuard.canActivate() → validateToken() → req.user = payload

**Próximos passos**: Adicione sua rota assim...

Você: "Teste 'should create user' está falhando com
      'Cannot read property id of undefined'.
      Onde é o problema?"

ChatGPT (com Vectora):
Procurando o teste e código relacionado...

**Achei o problema!**

Arquivo: src/__tests__/user.service.test.ts:145
  it('should create user', () => {
    const user = userService.create({ name: 'John' });
    expect(user.id).toBeDefined(); // ← Falha aqui
  })

Analisando userService.create():

  // src/services/user.service.ts:23
  create(data: CreateUserInput) {
    // Problema: não retorna o user criado
    db.insert(users).values(data);
    // Deveria ser:
    return db.insert(users).values(data).returning();
  }

**3 usuários desse padrão no código:**
  • src/services/order.service.ts:34
  • src/services/product.service.ts:12
  • src/services/invoice.service.ts:88

**Sugestão**: Aplicar mesmo fix nos 3 lugares.

Você: "Revise essa PR que refactora auth middleware.
       [cola 50 linhas de código]"

ChatGPT (com Vectora):
Analisando mudanças...

**Impacto Estimado**: 12 arquivos afetados
- 8 arquivos de rotas (GET /profile, etc)
- 2 testes de auth
- 2 guards

**Problemas detectados**:

1. Comportamento mudou em linha 23
   ANTES: guard.canActivate() retorna boolean
   AGORA: retorna Promise<boolean>

   Isso quebra em 4 lugares:
   - src/routes/admin.ts:45
   - src/routes/api.ts:78
   - src/middleware/verify.ts:12
   - src/guards/optional.ts:3

2. Positivo: Novo método isTokenValid() é reutilizado bem
   (encontrei 6 usos)

3. Segurança: GuardBlacklist está sendo respeitado
   (verifica todos os 4 patterns)

**Testes relacionados que DEVEM passar**:
□ auth.guard.test.ts
□ jwt.validation.test.ts
□ permission.test.ts
□ integration/auth-flow.test.ts

**Conclusão**: Aprove com condições:
1. Corrigir os 4 arquivos (async/await)
2. Rodar full test suite
3. Check: nenhum SECRET_KEY exposto

# Na aba "Instructions", adicione:

## MAPEAMENTO DE PROJETOS
O usuário pode mencionar o projeto. Mapeie assim:
- "frontend" → namespace: "webapp-react"
- "backend" → namespace: "api-nodejs"
- "mobile" → namespace: "app-flutter"
- Padrão → namespace: "seu-projeto"

Sempre pergunte qual projeto se não for claro.

## LIMITES DE PERFORMANCE

- top_k: máximo 10 (padrão 5)
  - Mais resultados = resposta mais lenta
  - Use top_k=3 para respostas rápidas (<2s)
  - Use top_k=10 para análises profundas (<5s)

- Timeout padrão: 30 segundos
  - Se exceder: reduzir top_k ou strategy
  - Strategy "structural" é mais rápido

servers:
  - url: https://seu-dominio.com/vectora/v1
    description: "Seu servidor Vectora customizado"

components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: "Bearer vca_live_xxxxx"

security:
  - apiKeyAuth: []

# No console.vectora.app
1. Settings → API Keys
2. Encontre a chave "ChatGPT Plugin"
3. Clique em "Rotate" ou "Extend"
4. Atualize no Custom GPT:
   - Configure → Authentication → Cole a nova chave

# No console.vectora.app
1. Settings → API Keys
2. Encontre a chave "ChatGPT Plugin"
3. Clique em "Delete" ou "Revoke"
4. O Custom GPT retornará erro 401

# Habilitar criptografia ponta-a-ponta
vectora config set --key "ENCRYPT_TRANSIT" --value "true"

# Certificado SSL/TLS
openssl req -x509 -newkey rsa:4096 -out cert.pem -keyout key.pem

# Usar com HTTPS
vectora server --cert cert.pem --key key.pem

# Verificar status da indexação em https://console.vectora.app
# Settings → Indexing → View Progress

# Se ainda indexando, aguarde conclusão
# Geralmente leva minutos a horas dependendo do tamanho

# Gerar nova API Key em console.vectora.app
# Settings → API Keys → New API Key
# Scope: "search"
# Ttl: 1 year

# Atualizar no Custom GPT:
# Configure → Authentication → Cole a chave nova

# Reduzir top_k na instrução do GPT para:
"Use sempre top_k=5 (máximo 10) para respostas rápidas"

# Ou verificar em console.vectora.app:
# Analytics → Query Performance
# Se latência > 2s, considere upgrade Plus → Team

Instrução:
"Você é um Design Reviewer baseado em Vectora.
Quando o usuário mostra código:
1. Procure por padrões similares no projeto
2. Avalie consistência
3. Sugira melhorias baseado em style guides existentes
4. Cite exemplos do codebase"

Instrução:
"Você é um Onboarding Assistant.
Novos engenheiros perguntam como o código funciona.
Use Vectora para:
1. Buscar documentação
2. Encontrar exemplos
3. Listar dependências
4. Sugerir arquivos para ler primeiro"

[2026-04-19 10:30:45] ChatGPT Plugin /search - 200 OK - 234ms - 5 chunks
[2026-04-19 10:31:12] ChatGPT Plugin /analyze - 200 OK - 156ms - 3 files
[2026-04-19 10:32:00] ChatGPT Plugin /file-summary - 200 OK - 89ms

# Primeira busca: "Como validar tokens?"
# Latência: 450ms (embedding + search)

# Segunda busca idêntica: 30s depois
# Latência: 45ms (cache hit) = 10x mais rápido!

 RUIM (3 roundtrips, ~1.5s total):
- "Onde validamos tokens?"
- "Onde fazemos refresh?"
- "Onde armazenamos sessões?"

 MELHOR (1 roundtrip, ~450ms):
- "Mostre toda a pipeline de autenticação:
  validação de tokens, refresh tokens e
  armazenamento de sessões"

RÁPIDO (<1s): top_k=3, strategy="structural"
BALANCEADO (~2s): top_k=5, strategy="semantic"
PROFUNDO (5-10s): top_k=10, strategy="semantic"

// No console do navegador (F12)
// Cole no Custom GPT em developer tools:

// 1. Verificar última requisição
console.log(JSON.parse(localStorage.getItem("gpt_last_api_call")));

// 2. Ver tempo de resposta
console.log("Latência:", new Date() - window.apiStartTime + "ms");

# No console.vectora.app
1. Logs → Integration
2. Procure entrada com timestamp do erro
3. Veja detalhes completos do erro
4. Reporte se for bug: github.com/Kaffyn/Vectora/issues