# @biltme/backend 中文文档

规范地址：https://npmcn.com/package/%40biltme/backend/

版本：0\.7\.1
npm 元数据更新时间：2026-10-18T14:05:51.945Z
中文译文更新时间：2026-11-08T02:40:28.682Z
软件包许可：UNLICENSED

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40biltme/backend
原文对照：https://npmcn.com/package/%40biltme/backend/?lang=original
项目主页：https://github.com/buildingapplications/bilt-backend#readme
源码仓库：https://github.com/buildingapplications/bilt-backend

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：490 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：@react-native-async-storage/async-storage ^2\.0\.0
- 首次发布：2026-07-14T22:19:15.865Z
- 最新版本发布：2026-10-18T14:05:51.497Z
- 近 30 天下载量：3494（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

比尔特后端 SDK – 为 bilt- cloud 项目在 @ supabase/ supabase-js 上瘦的 shim

## 安装

```sh
npm install @biltme/backend
```

也可以使用：`pnpm add @biltme/backend`、`yarn add @biltme/backend`、`bun add @biltme/backend`

## README

# @ biltme/ 后端

微细地闪过 [`@supabase/supabase-js`](https://github.com/supabase/supabase-js) 比尔特项目。 公用表面 = supabase-js 的表面; 此包添加 存储适配器帮助器,用于代理即时模板的稳定导入,以及 再导出清除的函数错误类别 `catch` 块.

## 安装

```bash
bun add @biltme/backend
# Expo only — also install AsyncStorage as the session store
bun add @react-native-async-storage/async-storage
```

## 快速启动( Expo)

```ts
import { createClient, asyncStorage } from '@biltme/backend'
import AsyncStorage from '@react-native-async-storage/async-storage'

const url = process.env.EXPO_PUBLIC_BILT_URL!     // https://<pid>.cloud.bilt.me
const key = process.env.EXPO_PUBLIC_BILT_ANON_KEY!

export const bilt = createClient(url, key, {
  auth: {
    storage: asyncStorage(AsyncStorage),
    persistSession: true,
    autoRefreshToken: true,
    detectSessionInUrl: false,
  },
})
```

每个supabase-js方法都有效:

```ts
const { data, error } = await bilt.auth.signInWithPassword({ email, password })
const { data: rows } = await bilt.from('notes').select('*')
```

## 输入的查询

`createClient` 读取一个空的图案 `Database` 接口此软件包 出口。 增强它,并输入文件中每个表格的列 :

```ts
declare module '@biltme/backend' {
  interface Database {
    public: {
      Tables: {
        notes: {
          Row: { id: string; title: string; tags: string[] | null }
          Insert: { id?: string; title: string; tags?: string[] | null }
          Update: { id?: string; title?: string; tags?: string[] | null }
          Relationships: []
        }
      }
      Views: Record<never, never>
      Functions: Record<never, never>
      Enums: Record<never, never>
      CompositeTypes: Record<never, never>
    }
  }
}
```

你不能用手写 Bilt-cloud从现场计划再生出来 每个 `bilt_apply_sql`,而代理将其丢入项目。 因为它是一个 模块增强而不是 `createClient<Database>`,没有通用 线程通过,在呼叫站点没有保持同步.

每把密钥都关了 不在的表格、视图或列 文件无法编译,所以 `rpc()` 调用函数文件 没有列出,也没有提出它没有的论点。 因此,一个陈旧的文件 屏蔽一个构件,直到下一个方案改变它.

离开 `Database` 毫无戒备,排队回来 `any`这是0.5.x所做的.

### 正在命名一行

四个帮手决定了同样的增加 `Database`,这样一行可以交叉 不重报组件边界:

```ts
import type { Tables, TablesInsert, TablesUpdate, Enums } from '@biltme/backend'

function MessageCard({ message }: { message: Tables<'messages'> }) { … }
function draft(): TablesInsert<'messages'> { … }
function patch(): TablesUpdate<'messages'> { … }
function badge(status: Enums<'order_status'>) { … }
```

`Tables` 横跨表格和视图,并给出相同类型 `select()` 返回数 键. `TablesInsert` 财务报告和审定财务报表 `TablesUpdate` 仅取餐桌,如在苏帕巴克js, 因此一个可写视图有一个行名,但没有有效载荷名. `Enums` 决定: 联合bilt-cloud makes under `Database['public']['Enums']`,所以一个 `switch` 结束 检查是否详尽无遗.

在第一次更改计划之前,没有名字,通过一个是编译 错误而不是 `any`。 。 。 .

## 调用函数

```ts
const { data, error } = await bilt.functions.invoke('send-email', {
  body: { to: 'user@example.com', subject: 'Welcome' },
})
```

Auth 头自动设定: 如果签名, 活动会话的访问符 里面,否则就是肛门 职能 `verify_jwt: true` 需求 签名会话或肛门密钥; `verify_jwt: false` 接受未签名 请求.

抓取已键入错误类 :

```ts
import { FunctionsHttpError, FunctionsRelayError, FunctionsFetchError } from '@biltme/backend'

const { data, error } = await bilt.functions.invoke('send-email', { body: {...} })
if (error instanceof FunctionsHttpError) {
  // user function returned 4xx/5xx — inspect error.context (Response)
} else if (error instanceof FunctionsRelayError) {
  // bilt-cloud / pool relay failed (function not found, cold start error)
} else if (error instanceof FunctionsFetchError) {
  // transport-level (DNS, TCP, TLS)
}
```

`region` 选项 `invoke()` 被接受,但被默默地忽略——bit-cloud is 单区域.

## 存储

```ts
// Admin (server-side, service key) — bucket lifecycle
await bilt.storage.createBucket('avatars', { public: false, fileSizeLimit: 5 * 1024 * 1024 })
await bilt.storage.createBucket('public-assets', { public: true })

// Upload (RLS-gated for anon-key / user-token; bypassed for service key)
const { data, error } = await bilt.storage
  .from('avatars')
  .upload(`${user.id}/photo.jpg`, file, { contentType: 'image/jpeg', upsert: true })

// Public bucket → URL is unauthenticated
const { data: { publicUrl } } = bilt.storage
  .from('public-assets')
  .getPublicUrl('logo.png')

// Private bucket → time-limited signed URL (up to 7 days)
const { data, error } = await bilt.storage
  .from('avatars')
  .createSignedUrl(`${user.id}/photo.jpg`, 3600)

// Catch storage errors:
import { StorageApiError } from '@biltme/backend'
if (error instanceof StorageApiError) { /* … */ }
```

Bucket 管理员 (`createBucket`, (中文(简体) ), `updateBucket`, (中文(简体) ), `deleteBucket`, (中文(简体) ), `emptyBucket`, (中文(简体) ), `listBuckets`)是只服务Key. 对象操作由 Postgres RLS 打开 投资政策 `storage.objects` - 写他们与 `bilt_storage_apply` 代理工具或 SQL 编辑器 .

原生反应, a `Blob` 转至 `upload`, (中文(简体) ), `update` 或者说 `uploadToSignedUrl` 以标记的字节发送 `contentType`这样 `fetch(uri).blob()` 从a 选中的文件通过一个桶的 MIME 许可列表 。 过 `contentType` 联合国 文件: React Introduct Blob 没有自己的类型, 没有上传 标签 `application/octet-stream`。 。 。 .

## 网页

```ts
import { createClient, webStorage } from '@biltme/backend'

const bilt = createClient(url, key, {
  auth: { storage: webStorage(), persistSession: true, autoRefreshToken: true },
})
```

## 服务器( 无会话持续)

```ts
import { createClient, memoryStorage } from '@biltme/backend'

const bilt = createClient(url, key, {
  auth: { storage: memoryStorage(), persistSession: false, autoRefreshToken: false },
})
```

## 此软件包添加的 vs `@supabase/supabase-js`

-   `createClient` _实值_ 苏帕贝斯的 `createClient`,重新打出,这样一个没有类型的呼叫 参数默认其计划到可增强 `Database` 上方接口代替 `any`。 。 。 .
-   `Database`,一个工程扩充的空接口可以输入其方案.
-   在本地反应时, 存储上传 `Blob` 作为字节 `contentType` 到达水桶(见存储).
-   无法提供实时 : `bilt.channel()` 掷出 `REALTIME_NOT_SUPPORTED`缩写 `bilt.from(...)` 在间隔或屏幕焦点上.
-   `asyncStorage(impl)` 工厂包装 `@react-native-async-storage/async-storage` -js的存储形状.
-   `webStorage()` 财务报告和审定财务报表 `memoryStorage()` 为完整起见.
-   `FunctionsHttpError`, (中文(简体) ), `FunctionsRelayError`, (中文(简体) ), `FunctionsFetchError`, (中文(简体) ), `FunctionRegion` 清洁再出口 `catch` 并输入选项.
-   `StorageApiError` 再出口储存 `catch` 块.
-   Bilt 代理快速模板的稳定导入路径 .

## 文档

对于其他一切(自动流、RLS、OAuth、函数参考), 使用情况 [Supabase的文档](https://supabase.com/docs/reference/javascript/introduction)。 。 。 . 比尔特的后端会说同样的电线协议.

## 常见问题

### @biltme/backend 是什么？

比尔特后端 SDK – 为 bilt- cloud 项目在 @ supabase/ supabase-js 上瘦的 shim

### 如何安装 @biltme/backend？

在项目目录运行 npm install @biltme/backend，或使用 pnpm add / yarn add / bun add。

### @biltme/backend 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @biltme/backend 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @biltme/backend 可以商用吗？

@biltme/backend 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @biltme/backend 的下载量有多少？

根据 npm 官方下载统计，@biltme/backend 在 2026/10/08 – 2026/11/06 这 30 天内被下载 3,494 次，日均约 116 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @biltme/backend 还在维护吗？

最新版本 0\.7\.1 发布于 2026/10/18（20 天前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/07/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。