# @ambasada/sdk 中文文档

规范地址：https://npmcn.com/package/%40ambasada/sdk/

版本：0\.8\.19
npm 元数据更新时间：2026-11-06T08:34:32.774Z
中文译文更新时间：2026-11-07T05:14:42.263Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ambasada/sdk
原文对照：https://npmcn.com/package/%40ambasada/sdk/?lang=original
项目主页：https://ambasada.id/

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

- 包体积（解压后）：89.8 kB，14 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- 首次发布：2026-11-02T07:31:43.337Z
- 最新版本发布：2026-11-06T08:34:32.571Z
- 近 30 天下载量：5776（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：33（近 12 个月 33 个）

## 中文简介

Ambasada平台 SDK:与Ambasada签约,小型应用程序通知,项目商店,文件.

## 安装

```sh
npm install @ambasada/sdk
```

也可以使用：`pnpm add @ambasada/sdk`、`yarn add @ambasada/sdk`、`bun add @ambasada/sdk`

## README

# @ambasada/ sdk (英语)

Ambasada平台客户端:与Ambasada签名,小型应用程序通知,项目商店,文件. 22号节点, Bun, Cloudflare工人, Next.js 路由处理器。 没有运行时间依赖 .

```ts
import { ambasada } from "@ambasada/sdk"; // AMBASADA_API_KEY, AMBASADA_API_URL (default https://api.ambasada.dev)
```

|  |  |
| --- | --- |
| `ambasada.auth.login(req)` 编号 : `.callback(req)` 编号 : `.user(req)` 编号 : `.logout(req)` 编号 : `.shell(req)` | 与 Ambasada (下方) 签约 |
| `ambasada.apps.verifyWebhook(req)` 编号 : `.notify({ … })` | ambasada应用软件的事件和推动通知(Docs/MINI-APPS.md §7) |
| `ambasada.store.get(key)` 编号 : `.put(key, value)` 编号 : `.delete(key)` 编号 : `.list(prefix)` | JSON 密钥值, 每个应用程序 1 MB |
| `ambasada.files.put(data)` | 公共 URL 的文件 |
| `ambasada.project()`, (中文(简体) ), `ambasada.keys()` | 应用程序的ID; API 的签名密钥 |
| `defineApp({ id, name, description, product })` | `ambasada.config.ts` |

错误是 `AmbasadaError` 与 `code` 从 `@ambasada/protocol` (单位:千美元)`isAmbasadaError(e, "UNAUTHORIZED")`),以及 `WebhookInvalidError` (400) (英语). 工人: `createAmbasada({ env })`。一个应用程序自己的数据库、KV、文件和持久 对象为工人绑定(`env.DB`, (中文(简体) ), `env.KV`, (中文(简体) ), `env.FILES`;docs/STORAGE.md),不是SDK的电话.

Hack A Ton经济(TON,退货,供货,代理)是加价 [`@ambasada/village`](https://www.npmjs.com/package/@ambasada/village)它的0.7个名称(`village`, (中文(简体) ), `createVillage`, (中文(简体) ), `VillageError`, (中文(简体) ), `offering`, (中文(简体) ), `defineCompany`,.)仍然在此被导出, `@deprecated`,直到2.0为止. 请注意: `createAmbasada` 从 0.8 返回平台客户端; 销售代码使用 `createVillage`。 。 。 .

## 和安巴萨达签约

人们用自己的"Ambasada"ID(OAuth 2.0代码流+PKCE,同意屏幕)向您的产品签名. 无 设置在 `https://<slug>.ambasada.dev`数字 : `ambasada deploy` 注射数 `AMBASADA_AUTH_CLIENT_ID`, (中文(简体) ), `AMBASADA_AUTH_CLIENT_SECRET` 财务报告和审定财务报表 `AMBASADA_AUTH_ISSUER`· ; `ambasada dev` 用假的和假的标志 作为"假访客". 为 Workers 和 Next.js 路由处理器获取风格的处理器, 仅WebCrypto .

```ts
const ambasada = createAmbasada({ env });
// GET /api/auth/login?returnTo=/path   → redirect to the Ambasada ID consent screen
return ambasada.auth.login(req, { returnTo: "/", email: true }); // email: also ask for their email
// GET /api/auth/callback               → checks state, exchanges the code, reads the profile, sets the cookie
return ambasada.auth.callback(req);
// anywhere on the server
const user = await ambasada.auth.user(req); // AmbasadaUser | null
// GET /api/auth/logout
return ambasada.auth.logout(req, { returnTo: "/" });
```

`AmbasadaUser` 实值 `{ id, name, avatar_url, builder, builder_since, member_since, pass, email? }`数字 : `id` 这是 稳定型安巴萨达身份证`user_…`, (中文(简体) ), `pass` 实值 `"builder" | "visitor" | "staff" | null` 为本次活动, `email` 只有你问了 他们同意了 会话是 Http Only `SameSite=Lax` 饼干`__Host-ambasada_session` 在 https 上)持有已签名的配置文件(HMAC-SHA256,密钥取自客户端秘密),有效期为7天;没有符号 留着. `returnTo` 必须是您网站上的路径 . `user()` 还要 `{ headers }` (下一个服务器组件 : `ambasada.auth.user({ headers: await headers() })`) (中文(简体) ). `ambasada.auth.configured` 说明证书是否设定. 用它代替它们 `createAmbasada({ auth: { clientId, clientSecret, issuer, publicUrl } })`· ; `PUBLIC_URL` 设置 当工人看到另一个主机时,创建回调 URL。 更多:文件/AUTH.md.

`pnpm build` 写入 `dist/` (一份无害环境管理文件+) `.d.ts`(三); `publishConfig` 将公布的软件包指向它.

由 [科特维索](https://centyso.com/) 页:1 [安巴萨达](https://ambasada.id/)麻省理工学院.

## 常见问题

### @ambasada/sdk 是什么？

Ambasada平台 SDK:与Ambasada签约,小型应用程序通知,项目商店,文件\.

### 如何安装 @ambasada/sdk？

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

### @ambasada/sdk 支持 TypeScript 吗？

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

### @ambasada/sdk 支持 ESM 还是 CommonJS？

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

### @ambasada/sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ambasada/sdk 可以商用吗？

@ambasada/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ambasada/sdk 的下载量有多少？

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

### @ambasada/sdk 还在维护吗？

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