# 公共 API

## 更新记录

- 2026-07-16: 创建 Auth、CRUD、Platform、Admin 和 Handler API 文档。
- 2026-07-16: 补充签名、返回、错误和真实路由映射。
- 2026-07-16: 增加 Base44 访问申请 API、assertion 配置和恢复时间错误字段。
- 2026-07-16: 明确 core 用户解析复用、固定路径请求体白名单和旧 assertion 兼容边界。

## CreateSupabaseFunctionHandler(Options)

创建 Base44 后台函数 Handler。

主要参数：

- `ApiBaseUrl`：`go_qoder_file` 服务根地址；
- `CreateBase44ClientFromRequest`：Base44 服务端鉴权适配器；
- `RequireAuth`：默认 `true`，仅测试环境可设为 `false`；
- `FetchImpl`、`TimeoutMs`、`StaticHeaders`、`BuildHeaders`：沿用核心代理包；
- `ResolveAccessToken`：可选，自定义从 Base44 请求中读取 Go Token；
- `ResolveIdempotencyKey`：可选，自定义读取幂等键。
- `Base44AssertionAlgorithm`：必须为 `RS256`；
- `Base44AssertionKeyId`、`Base44AssertionPrivateKeyPem`：签名 Key ID 和 PKCS#8 私钥；
- `Base44AssertionIssuer`、`Base44AssertionAudience`：必须与 Go 白名单对应；
- `Base44ProviderAppId`：受控部署 App ID，不读取页面或用户对象的 App ID；
- `Base44AssertionLifetimeSeconds`：必填，建议 `45`，有效范围 `1..60`；
- `ResolveBase44Identity`：可选的服务端身份适配器；默认读取 Base44 官方 `id/email/is_verified/disabled` 字段。

Handler 默认读取代理载荷顶层的 `AccessToken` 和 `IdempotencyKey`。二者会在核心代理解析时被丢弃，只转换为受控请求头。

对三个精确路径，Handler 通过 core `ResolveBase44User` 只调用一次 Base44 `auth.me()`，即时签发新 assertion 并重建 Go Body。页面字段不能覆盖 Subject、Email、Disabled、Provider App ID、内部哈希或限流参数；access-status 和创建申请传入 assertion 会被拒绝，旧 exchange 传入的 assertion 仅为兼容而被忽略。

返回：`{ Handle(Request): Promise<Response> }`。路径、Base44 鉴权和上游错误遵循 core 统一结构。

## CreateSupabaseProxy(Options)

创建低层代理，只允许以下路径前缀：

- `/ts/dbbase/supabase`
- `/ts/dbbase/auth`
- `/ts/dbbase/platform`
- `/ts/dbbase/admin`

一般业务应优先用 `CreateSupabaseFunctionHandler`，因为它支持逐用户 Go Token。

## CreateSupabaseClient(Options)

签名：

```js
CreateSupabaseClient(Options): SupabaseFacadeClient
```

主要参数：

- `InvokePayload`：调用 Base44 后台函数的函数；
- `AccessToken`：静态 Go Token；
- `GetAccessToken`：动态读取 Go Token，优先于 `AccessToken`；
- `CreateIdempotencyKey`：自定义幂等键生成器；
- `Handler`：本地测试时注入 Handler；
- 未提供 `InvokePayload` / `Handler` 时，会用其余参数创建本地 Handler。

返回成员：

- `AuthApi`
- `CrudApi`
- `PlatformApi`
- `AdminApi`
- `Request`
- `InvokePayload`
- `ListAllPages`

客户端来源由 core `CreateFacadeClientContext` 统一解析；本包额外支持把 `Handler` 作为 Proxy 来源。

## AuthApi

- `Login({ AppId, IdentityType, Identity, Password, DeviceType? })`
- `ExchangeBase44(Assertion)`
- `ExchangeCurrentBase44User()`
- `GetBase44AccessStatus()`
- `CreateBase44AccessRequest({ RequestMessage? }, { IdempotencyKey? })`
- `GetCurrentState()`
- `GetCurrentAuthState()`：`GetCurrentState` 的兼容别名
- `SelectContext(StaffId)`
- `SelectAuthorizationContext(StaffId)`：`SelectContext` 的兼容别名
- `Logout()`
- `InspectInvitation(Token)`
- `AcceptInvitation(Token, NewPassword)`
- `RequestRegistration(Input)`
- `InspectRegistration(Token)`
- `CompleteRegistration(Token, NewPassword)`
- `RequestPasswordReset(Input)`
- `InspectPasswordReset(Token)`
- `CompletePasswordReset(Token, NewPassword)`

领域接口成功时直接返回 Go 响应的 `ret_str`。

`ExchangeBase44(Assertion)` 已弃用。新方法不接受 assertion；创建申请会把 `RequestMessage` trim 后映射为 `request_message`，最大 2000 个 Unicode 字符，并自动生成或复用幂等键。

公开方法不会附带 Go Token；其余方法要求 `AccessToken/GetAccessToken`。Login wire 字段为 `app_id / identity_type / identity / password / DeviceType`。

## CrudApi

- `Select(Options)`
- `Insert(Options)`
- `Update(Options)`
- `Upsert(Options)`
- `Request(Action, Options)`

`Options` 支持：`Table`、`Schema`、`Columns`、`Select`、`Filters`、`Match`、`OrderBy`、`Limit`、`Offset`、`Data`、`Rows`、`Key`。

响应保留 Go CRUD 原始结构，例如 `{ success, action, table, schema, data }`。

错误与限制：空 `Table` 或 `delete` 在本地拒绝；真实表、列、操作符和行级访问仍由 Go 白名单与权限链决定。

## PlatformApi

- `ListApps({ Search?, Cursor?, Limit?, IncludeDeleted? })`
- `CreateApp(Input, { IdempotencyKey? })`
- `UpdateApp(AppId, Input, { IdempotencyKey? })`

## AdminApi

先按目标 App 建立作用域：

```js
const AppAdmin = Client.AdminApi.ForApp(AppId);
```

可用方法：

- `Users.List / Create / SetStatus / IssueInvitation / RevokeInvitation / IssuePasswordReset`
- `Staff.List / Create / Update`
- `Roles.List / Create / Update`
- `Permissions.List / Create / Update`
- `Audits.List / Get`

所有写方法最后一个参数均可传 `{ IdempotencyKey }`。

固定 Go 路由：

- `/ts/dbbase/admin/apps/{appId}/users`
- `/staff`
- `/roles`
- `/permissions`
- `/permission-audits`

动态 App、User、Staff、Role、Permission 和 Audit ID 都会使用 URL path segment 编码。

## SupabaseFacadeError

字段：

- `Code`
- `StatusCode`
- `RequestId`
- `RetryAllowedAt`

代理层稳定保留 HTTP 状态、Go `code`、`request_id` 和允许公开的 `retry_allowed_at`；完整 Go 错误 envelope 不透传，以减少内部字段泄露。

示例：

```js
try {
  await Client.AdminApi.ForApp(AppId).Roles.Update(RoleId, InputValue);
} catch (ErrorValue) {
  if (ErrorValue.Code === 'VERSION_CONFLICT') {
    await ReloadRole();
  }
}
```

## ListAllPages

```js
ListAllPages(Loader, MaxPages = 10): Promise<Array>
```

`Loader(Cursor)` 返回 `{ items, next_cursor }`。达到空 cursor 或最大页数时停止。

## 注意事项

- 本包不导出 Supabase Client，也不接受 Supabase URL、Secret 或 `service_role` Key。
- `RequestRegistration` 等 Input 保持 Go snake_case wire 字段。
- Base44 Web 不应记录顶层 `AccessToken` 或把它放入 URL。