> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Base44 Coder

> Construa aplicativos na plataforma Base44 usando o SDK JavaScript da Base44.

<Warning>
  Esta página faz parte de uma habilidade de agente de código IA e é escrita para agentes, não para humanos. Para a documentação legível por humanos da Base44, veja a [documentação para desenvolvedores](/developers).
</Warning>

# Base44 Coder

Construa aplicativos na plataforma Base44 usando o SDK JavaScript da Base44.

## ⚡ AÇÃO IMEDIATA NECESSÁRIA - Leia isto primeiro

Esta habilidade é ativada em QUALQUER menção a "base44" ou quando uma pasta `base44/` existe. **NÃO leia arquivos de documentação ou pesquise na web antes de agir.**

**Sua primeira ação DEVE ser:**

1. Verifique se `base44/config.jsonc` existe no diretório atual
2. Se **SIM** (cenário de projeto existente):
   * Esta habilidade (base44-sdk) lida com a solicitação
   * Implemente recursos usando o SDK Base44
   * NÃO use base44-cli a menos que o usuário solicite explicitamente comandos CLI
3. Se **NÃO** (cenário de novo projeto):
   * Transfira para a habilidade base44-cli para inicialização do projeto
   * Esta habilidade não pode ajudar até que o projeto seja inicializado

## Quando usar esta habilidade vs base44-cli

**Use base44-sdk quando:**

* Construindo recursos em um projeto Base44 **EXISTENTE**
* `base44/config.jsonc` já existe no projeto
* Importações do SDK Base44 estão presentes (`@base44/sdk`)
* Escrevendo código JavaScript/TypeScript usando módulos do SDK Base44
* Implementando funcionalidade, componentes ou recursos
* O usuário menciona: "implement", "build a feature", "add functionality", "write code for"
* O usuário diz "create a \[type] app" **e** um projeto Base44 já existe

**NÃO USE base44-sdk para:**

* ❌ Inicializar novos projetos Base44 (use `base44-cli` em vez disso)
* ❌ Diretórios vazios sem configuração Base44
* ❌ Quando o usuário diz "create a new Base44 project/app/site" e nenhum projeto existe
* ❌ Comandos CLI como `npx base44 create`, `npx base44 deploy`, `npx base44 login` (use `base44-cli`)

**Dependências de habilidade:**

* `base44-sdk` assume que um projeto Base44 já está **inicializado**
* `base44-cli` é um **pré-requisito** para `base44-sdk` em novos projetos
* Se o usuário quer "create an app" e nenhum projeto Base44 existe, use `base44-cli` primeiro

**Lógica de verificação de estado:**
Antes de selecionar esta habilidade, verifique:

* SE (usuário menciona "create/build app" OU "make a project"):
  * SE (diretório está vazio OU nenhum `base44/config.jsonc` existe):
    → Use **base44-cli** (inicialização de projeto necessária)
  * SENÃO:
    → Use **base44-sdk** (projeto existe, construa recursos)

## Início rápido

```javascript theme={null}
// In Base44-generated apps, base44 client is pre-configured and available

// CRUD operations
const task = await base44.entities.Task.create({ title: "New task", status: "pending" });
const tasks = await base44.entities.Task.list();
await base44.entities.Task.update(task.id, { status: "done" });

// Get current user
const user = await base44.auth.me();
```

```javascript theme={null}
// External apps
import { createClient } from "@base44/sdk";

// IMPORTANT: Use 'appId' (NOT 'clientId' or 'id')
const base44 = createClient({ appId: "your-app-id" });
await base44.auth.loginViaEmailPassword("user@example.com", "password");
```

## ⚠️ CRÍTICO: Não Alucine APIs

**Antes de escrever QUALQUER código Base44, verifique os nomes dos métodos contra esta tabela ou [QUICK\_REFERENCE.md](https://docs.base44.com/developers/skills/base44-sdk/references/QUICK_REFERENCE.md).**

O SDK Base44 tem nomes de método únicos. NÃO assuma padrões do Firebase, Supabase ou outros SDKs.

### Autenticação - ERRADO vs CORRETO

| ❌ ERRADO (alucinado)                    | ✅ CORRETO                                      |
| --------------------------------------- | ---------------------------------------------- |
| `signInWithGoogle()`                    | `loginWithProvider('google')`                  |
| `signInWithProvider('google')`          | `loginWithProvider('google')`                  |
| `auth.google()`                         | `loginWithProvider('google')`                  |
| `signInWithEmailAndPassword(email, pw)` | `loginViaEmailPassword(email, pw)`             |
| `signIn(email, pw)`                     | `loginViaEmailPassword(email, pw)`             |
| `createUser()` / `signUp()`             | `register({email, password})`                  |
| `onAuthStateChanged()`                  | `me()` (sem listener, chame quando necessário) |
| `currentUser`                           | `await auth.me()`                              |

### Funções - ERRADO vs CORRETO

| ❌ ERRADO (alucinado)           | ✅ CORRETO                        |
| ------------------------------ | -------------------------------- |
| `functions.call('name', data)` | `functions.invoke('name', data)` |
| `functions.run('name', data)`  | `functions.invoke('name', data)` |
| `callFunction('name', data)`   | `functions.invoke('name', data)` |
| `httpsCallable('name')(data)`  | `functions.invoke('name', data)` |

### Integrações - ERRADO vs CORRETO

| ❌ ERRADO (alucinado)           | ✅ CORRETO                                          |
| ------------------------------ | -------------------------------------------------- |
| `ai.generate(prompt)`          | `integrations.Core.InvokeLLM({prompt})`            |
| `openai.chat(prompt)`          | `integrations.Core.InvokeLLM({prompt})`            |
| `llm(prompt)`                  | `integrations.Core.InvokeLLM({prompt})`            |
| `sendEmail(to, subject, body)` | `integrations.Core.SendEmail({to, subject, body})` |
| `email.send()`                 | `integrations.Core.SendEmail({to, subject, body})` |
| `uploadFile(file)`             | `integrations.Core.UploadFile({file})`             |
| `storage.upload(file)`         | `integrations.Core.UploadFile({file})`             |

### Entidades - ERRADO vs CORRETO

| ❌ ERRADO (alucinado)         | ✅ CORRETO                     |
| ---------------------------- | ----------------------------- |
| `entities.Task.find({...})`  | `entities.Task.filter({...})` |
| `entities.Task.findOne(id)`  | `entities.Task.get(id)`       |
| `entities.Task.insert(data)` | `entities.Task.create(data)`  |
| `entities.Task.remove(id)`   | `entities.Task.delete(id)`    |
| `entities.Task.onChange(cb)` | `entities.Task.subscribe(cb)` |

## Módulos do SDK

| Módulo                     | Propósito                                                   | Referência                                                                                           |
| -------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `entities`                 | Operações CRUD em modelos de dados                          | [entities.md](https://docs.base44.com/developers/skills/base44-sdk/references/entities.md)           |
| `auth`                     | Login, registro, gerenciamento de usuário                   | [auth.md](https://docs.base44.com/developers/skills/base44-sdk/references/auth.md)                   |
| `agents`                   | Conversas de IA e mensagens                                 | [base44-agents.md](https://docs.base44.com/developers/skills/base44-sdk/references/base44-agents.md) |
| `functions`                | Invocação de função de backend                              | [functions.md](https://docs.base44.com/developers/skills/base44-sdk/references/functions.md)         |
| `integrations`             | IA, e-mail, uploads de arquivo, APIs personalizadas         | [integrations.md](https://docs.base44.com/developers/skills/base44-sdk/references/integrations.md)   |
| `analytics`                | Rastreia eventos personalizados e atividade do usuário      | [analytics.md](https://docs.base44.com/developers/skills/base44-sdk/references/analytics.md)         |
| `appLogs`                  | Registra atividade do usuário no aplicativo                 | [app-logs.md](https://docs.base44.com/developers/skills/base44-sdk/references/app-logs.md)           |
| `users`                    | Convida usuários para o aplicativo                          | [users.md](https://docs.base44.com/developers/skills/base44-sdk/references/users.md)                 |
| `asServiceRole.connectors` | Tokens OAuth com escopo de aplicativo (apenas service role) | [connectors.md](https://docs.base44.com/developers/skills/base44-sdk/references/connectors.md)       |
| `asServiceRole.sso`        | Geração de token SSO (apenas service role)                  | [sso.md](https://docs.base44.com/developers/skills/base44-sdk/references/sso.md)                     |

Para configuração do cliente e modos de autenticação, veja [client.md](https://docs.base44.com/developers/skills/base44-sdk/references/client.md).

### TypeScript e registros de tipo

Cada arquivo de referência inclui uma seção "Type Definitions" com interfaces e tipos TypeScript para os métodos, parâmetros e valores de retorno do módulo.

**Obter entidades, funções e agentes tipados:** A CLI Base44 gera tipos dos recursos do seu projeto (entidades, funções, agentes), incluindo aumentos para `EntityTypeRegistry`, `FunctionNameRegistry` e `AgentNameRegistry`, e os conecta ao seu projeto para que você obtenha autocomplete e verificação de tipos sem configuração manual. Para saber como gerar tipos, use a habilidade **base44-cli**.

**Aumento manual:** Você pode aumentar os registros por conta própria em um arquivo `.d.ts`; veja as seções Type Definitions em [entities.md](https://docs.base44.com/developers/skills/base44-sdk/references/entities.md), [functions.md](https://docs.base44.com/developers/skills/base44-sdk/references/functions.md) e [base44-agents.md](https://docs.base44.com/developers/skills/base44-sdk/references/base44-agents.md).

## Instalação

Instale o SDK Base44:

```bash theme={null}
npm install @base44/sdk
```

**Importante:** Nunca assuma ou hardcode a versão do pacote `@base44/sdk`. Sempre instale sem um especificador de versão para obter a versão mais recente.

## Criando um cliente (aplicativos externos)

Ao criar um cliente em aplicativos externos, **SEMPRE use `appId` como o nome do parâmetro**:

```javascript theme={null}
import { createClient } from "@base44/sdk";

// ✅ CORRECT
const base44 = createClient({ appId: "your-app-id" });

// ❌ WRONG - Do NOT use these:
// const base44 = createClient({ clientId: "your-app-id" });  // WRONG
// const base44 = createClient({ id: "your-app-id" });        // WRONG
```

**Parâmetro obrigatório:** `appId` (string) - Seu ID de aplicativo Base44

**Parâmetros opcionais:**

* `token` (string) - Token de usuário pré-autenticado
* `options` (object) - Opções de configuração
  * `options.onError` (function) - Manipulador global de erros

**Exemplo com manipulador de erros:**

```javascript theme={null}
const base44 = createClient({
  appId: "your-app-id",
  options: {
    onError: (error) => {
      console.error("Base44 error:", error);
    }
  }
});
```

## Seleção de módulo

**Trabalhando com dados do aplicativo?**

* Criar/ler/atualizar/excluir registros → `entities`
* Importar dados de arquivo → `entities.importEntities()`
* Atualizações em tempo real → `entities.EntityName.subscribe()`

**Gerenciamento de usuários?**

* Login/registro/logout → `auth`
* Obter usuário atual → `auth.me()`
* Atualizar perfil de usuário → `auth.updateMe()`
* Convidar usuários → `users.inviteUser()`

**Recursos de IA?**

* Conversar com agentes de IA → `agents` (requer usuário logado)
* Criar nova conversa → `agents.createConversation()`
* Gerenciar conversas → `agents.getConversations()`
* Gerar texto/JSON com IA → `integrations.Core.InvokeLLM()`
* Gerar imagens → `integrations.Core.GenerateImage()`

**Lógica de backend personalizada?**

* Executar código do lado do servidor → `functions.invoke()`
* Necessário acesso de administrador → `base44.asServiceRole.functions.invoke()`

**Serviços externos?**

* Enviar e-mails → `integrations.Core.SendEmail()`
* Fazer upload de arquivos → `integrations.Core.UploadFile()`
* APIs personalizadas → `integrations.custom.call()`
* OAuth com escopo de aplicativo (conta do construtor do aplicativo) → `asServiceRole.connectors.getConnection()` (apenas backend)

**Rastreamento e análise?**

* Rastrear eventos personalizados → `analytics.track()`
* Registrar visualizações de página/atividade → `appLogs.logUserInApp()`

## Padrões comuns

### Filtrar e ordenar dados

```javascript theme={null}
const pendingTasks = await base44.entities.Task.filter(
  { status: "pending", assignedTo: userId },  // query
  "-created_date",                             // sort (descending)
  10,                                          // limit
  0                                            // skip
);
```

### Rotas protegidas (verificar autenticação)

```javascript theme={null}
const user = await base44.auth.me();
if (!user) {
  // Navigate to your custom login page
  navigate('/login', { state: { returnTo: window.location.pathname } });
  return;
}
```

### Chamada de função de backend

```javascript theme={null}
// Frontend
// ⚠️ invoke() returns the RAW axios response — your function's JSON is on `.data`,
//    NOT the top-level object. It also THROWS on non-2xx (error body at err.response.data).
const res = await base44.functions.invoke("processOrder", {
  orderId: "123",
  action: "ship"
});
const result = res.data; // ✅ e.g. res.data.success  (res itself is { data, status, headers, … })

// Backend function (Deno)
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const { orderId, action } = await req.json();
  // Process with service role for admin access
  const order = await base44.asServiceRole.entities.Orders.get(orderId);
  return Response.json({ success: true });
});
```

### Acesso Service Role

Use `asServiceRole` em funções de backend para operações em nível de administrador:

```javascript theme={null}
// User mode - respects permissions
const myTasks = await base44.entities.Task.list();

// Service role - full access (backend only)
const allTasks = await base44.asServiceRole.entities.Task.list();
const token = await base44.asServiceRole.connectors.getAccessToken("slack");
```

## Frontend vs Backend

| Capacidade                                       | Frontend | Backend |
| ------------------------------------------------ | -------- | ------- |
| `entities` (dados do usuário)                    | Sim      | Sim     |
| `auth`                                           | Sim      | Sim     |
| `agents`                                         | Sim      | Sim     |
| `functions.invoke()`                             | Sim      | Sim     |
| `functions.fetch()`                              | Sim      | Sim     |
| `integrations`                                   | Sim      | Sim     |
| `analytics`                                      | Sim      | Sim     |
| `appLogs`                                        | Sim      | Sim     |
| `users`                                          | Sim      | Sim     |
| `asServiceRole.*`                                | Não      | Sim     |
| `asServiceRole.connectors` (OAuth do aplicativo) | Não      | Sim     |
| `asServiceRole.sso`                              | Não      | Sim     |

Funções de backend usam `Deno.serve()` e `createClientFromRequest(req)` para obter um cliente adequadamente autenticado.

<Note>Esta página foi traduzida usando IA. Para informações mais precisas e atualizadas, consulte a [versão em inglês](/). </Note>