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

# Workspaces

> Crie workspaces, convide membros, gerencie papéis e compartilhe aplicações entre uma equipe.

<Info>
  Workspaces são expostos pelo módulo `api.workspaces`. Disponível nos planos **Standard, Pro e Enterprise**.
</Info>

## Criando um workspace

```typescript theme={null}
const { id: workspaceId } = await api.workspaces.create({ name: "Acme" });
```

O `name` deve ter de 1 a 32 caracteres, e criar um workspace exige um plano pago ativo.

## Listando workspaces

`api.workspaces.list()` retorna todos os workspaces em que o usuário autenticado é dono ou membro.

```typescript theme={null}
const workspaces = await api.workspaces.list();

for (const ws of workspaces) {
    console.log(
        `${ws.name} (${ws.memberList.length} membros, ${ws.applicationList.length} apps)`,
    );
}
```

<Warning>
  Na v3, `ws.members` e `ws.applications` armazenavam arrays de dados brutos. Na v4 esses nomes são **módulos** (`ws.members.add(...)`, `ws.applications.add(...)`). Os arrays brutos foram movidos para `ws.memberList` e `ws.applicationList`.
</Warning>

## Buscando um workspace específico

```typescript theme={null}
const workspace = await api.workspaces.fetch(workspaceId);

console.log(workspace.id);
console.log(workspace.name);
console.log(workspace.owner);
console.log(workspace.createdAt);
console.log(workspace.memberList);
console.log(workspace.applicationList);

for (const member of workspace.memberList) {
    console.log(`${member.name} entrou em ${member.joinedAt}`);
}
```

## Convidando membros

Convidar um membro é um handshake em duas etapas — o convidado prova o consentimento gerando um código de curta duração (5 minutos) a partir do **próprio** cliente, e o dono do workspace consome esse código.

```typescript theme={null}
// 1. A partir do cliente SDK do convidado
const otherApi = new SquareCloudAPI(process.env.OTHER_USER_API_KEY!);
const code = await otherApi.workspaces.generateInviteCode();

// 2. A partir do cliente do dono do workspace
await workspace.members.add(code, "maintain");
```

Papéis válidos para o argumento `group`:

| Papel      | Descrição                                              |
| ---------- | ------------------------------------------------------ |
| `view`     | Somente leitura                                        |
| `manager`  | Gerencia aplicações                                    |
| `maintain` | Gerencia aplicações + membros abaixo da sua hierarquia |
| `admin`    | Admin completo                                         |

<Note>
  O papel `owner` não pode ser atribuído pela API — a transferência de propriedade não está exposta.
</Note>

## Alterando o papel de um membro

```typescript theme={null}
await workspace.members.update("1234567890abcdef1234567890abcdef", "admin");
```

## Removendo um membro

```typescript theme={null}
await workspace.members.remove("1234567890abcdef1234567890abcdef");
```

<Note>
  Somente o dono do workspace pode remover membros.
</Note>

## Compartilhando aplicações

```typescript theme={null}
await workspace.applications.add("abc123def456abc123def456");
await workspace.applications.remove("abc123def456abc123def456");
```

## Saindo ou deletando um workspace

```typescript theme={null}
// Como membro
await workspace.leave();

// Como dono (irreversível)
await workspace.delete();
```

Também é possível sair ou deletar pelo ID, direto no módulo:

```typescript theme={null}
await api.workspaces.delete(workspaceId);
await api.workspaces.leave(workspaceId);
```