> ## 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.

# workspace

> 创建 workspace、邀请成员、管理角色并在团队间共享应用。

<Info>
  workspace 由 `api.workspaces` 模块暴露，这是 v4 新增的功能。它们在 **Standard、Pro 和 Enterprise** 套餐上可用。
</Info>

## 创建 workspace

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

`name` 长度必须为 1–32 个字符。

## 列出 workspace

`api.workspaces.list()` 返回当前已认证用户作为所有者或成员的所有 workspace。

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

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

<Warning>
  在 v3 中，`ws.members` 和 `ws.applications` 持有原始数据数组。在 v4 中它们现在是**模块**（`ws.members.add(...)`、`ws.applications.add(...)`）。原始数组被移到了 `ws.memberList` 和 `ws.applicationList`。
</Warning>

## 获取单个 workspace

```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);
```

## 邀请成员

邀请成员是一个两步握手过程：受邀者通过在**其自己的**客户端生成一个短时（5 分钟）代码来证明同意，然后由所有者消费该代码。

```typescript theme={null}
// 1. From the invitee's own SDK client
const otherApi = new SquareCloudAPI(process.env.OTHER_USER_API_KEY!);
const code = await otherApi.workspaces.generateInviteCode();

// 2. From the workspace owner's client
await workspace.members.add(code, "maintain");
```

`group` 参数的有效角色：

| Role       | Description       |
| ---------- | ----------------- |
| `view`     | 只读访问              |
| `manager`  | 管理应用              |
| `maintain` | 管理应用 + 管理其层级以下的成员 |
| `admin`    | 完全管理员             |

<Note>
  `owner` 角色无法通过 API 分配，所有权转移未对外开放。
</Note>

## 更改成员角色

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

## 移除成员

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

<Note>
  只有 workspace 所有者才能移除成员。
</Note>

## 共享应用

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

## 离开或删除 workspace

```typescript theme={null}
// As a member
await workspace.leave();

// As the owner (irreversible)
await workspace.delete();
```

你也可以直接通过模块按 ID 删除或离开：

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