# @gemmein/sdk 中文文档

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

版本：0\.24\.1
npm 元数据更新时间：2026-11-14T23:12:38.174Z
中文译文更新时间：2026-11-16T03:12:14.045Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gemmein/sdk
原文对照：https://npmcn.com/package/%40gemmein/sdk/?lang=original
项目主页：https://gemmein.com/
源码仓库：https://github.com/gemmeinhq/gemmein-release

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

- 包体积（解压后）：1.1 MB，19 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：expo \*，react-native \*，expo-secure-store \*
- 首次发布：2026-07-10T02:14:10.678Z
- 最新版本发布：2026-11-14T21:57:51.324Z
- 近 30 天下载量：2041（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：41（近 12 个月 41 个）

## 中文简介

Gemmein SDK——无密码认证,安全存储,以及用于AI所建应用的花纹驱动记录翻转. 小到一个提示教整个API.

## 安装

```sh
npm install @gemmein/sdk
```

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

## README

# @gemmein/ sdk (英语)

Gemmein是网络和移动应用程序的后端:托管,登录,保护数据,支付,AI工具以及运行客户的仪表板. 没有 SQL, 没有安全规则语言, 没有服务器配置 。 Web, Expo/React Introduct, 和斯威夫特, 在一个合同上.

二门一所. **从一个想法开始** - 还没建成吗? 运行 `npx -y gemmein dev` 并针对本地后端构建:零设置,无账号,无取取密钥,无出出机. **已经有应用程序了吗?** 签名 `npx gemmein login` (下方)并让Gemmein替换当前站点或假冒的登录,存储和支付;前端,框架和主机留在原地. 无论是门,Gemmein是将应用程序带给真正的客户的角色.

## 步骤 0 - 获取您的应用密钥

每一次通话都需要一个应用密钥( E)`pk_...`) (中文(简体) ). 没有人复制一个: 运行 `npx gemmein login` ,并在浏览器中批准(在 **[app.gemmein.com (英语)](https://app.gemmein.com/)** 带有电子邮件代码——免费,无卡. CLI 保存开发应用密钥于 `gemmein/gemmein.config.json` (单位:千美元)`testPublicKey`),以及 `npx gemmein keys app` 打印项目拥有的每个应用键——本地、开发和活化。 当地建筑 `npx gemmein dev` 首先吗? 它的靴子卡印出本地密钥; 不需要账户 .

## 安装

```
npm i @gemmein/sdk
```

没有捆绑? SDK是无依赖性的纯无害环境管理——副本 `dist/index.js` 从 HTML 旁边的软件包中 `import { gemmein } from "./index.js"` 在一个 `<script type="module">`在任何静态主机上工作.

## 快开始

```js
import { gemmein } from "@gemmein/sdk"

const g = gemmein("pk_test_...")

// Login — email code, no passwords
await g.auth.sendEmailCode("user@example.com")
await g.auth.verifyEmailCode({ email: "user@example.com", code: "12345678" })

// Store data — rules enforced server-side. A new app has no collections:
// create "tasks" first — `npx gemmein collection add tasks`, then
// `npx gemmein sync` — or add it on Collections in the dashboard.
// Otherwise this answers 404 unknown_collection.
await g.collection("tasks").create({ title: "Buy milk", done: false })
const { records } = await g.collection("tasks").list()
```

这就是产品所执行的创意阶段的订单:先签到,然后是数据规则,然后是客户付费。 对一个当地人 `gemmein dev` 后端相同行运行于 `pk_local_` 键,它会打印出来;对着它们运行的云 `pk_test_` 接下来 `pk_live_`。 。 。 .

客户端有两层: **您的收藏库** (单位:千美元)`g.collection("tasks")` ——你的应用程序自己的数据模型)和 **gemmein为您服务** (单位:千美元)`g.auth`, (中文(简体) ), `g.subscriptions`, (中文(简体) ), `g.payments`, (中文(简体) ), `g.purchases`, (中文(简体) ), `g.credits`, (中文(简体) ), `g.ai`, (中文(简体) ), `g.files`, (中文(简体) ), `g.account` 签字用户自助服务表面;管理 _其他项目_ 人们的用户,订阅,和记录都发生在主人的仪表板上,是故意的).

整个页面自动重新加载会话( 浏览器中的本地存储器, 其它处的内存 —— 覆盖到 `tokenStore` 如果您需要自定义的持久性). 每个用户一个会话: 验证新代码取消电子邮件旧会话的功能—— 一个已过时的会话 `auth_expired` 一次,SDK清除了它,一次再试(或再试)恢复.

一个不能的商店 **保留** 会话中这样写:拒绝 `localStorage` 写入( 私有模式超过其配额, 站点数据被屏蔽, 沙盒式 iframe) `verifyEmailCode()` 掷出 `secure_store_unavailable` 而不是交回一个会话 下一次重载会丢失。 读取和清出保持宽大——不可读取的商店意味着签出. 无论哪种方式,会话都是真实的,所以一个应用程序,它宁愿运行,也不愿停止捕获一个代码,重建它的客户端 `MemoryTokenStore`,它从来没有扔.

这艘船旁边有两个参考文件: **[`REFERENCE.md`](https://npmcn.com/package/%40gemmein/sdk/REFERENCE.md)** ——每一种方法,签名和还原形状——并 **`llms.txt`**,粘入AI工具的指南。 两者都在包里;同样的材料在 **[页面存档备份,存于互联网档案馆. docs.gemmein.com](https://docs.gemmein.com/)**。 。 。 .

## 认证

```js
await g.auth.sendEmailCode("user@example.com")   // sends an 8-digit code

const session = await g.auth.verifyEmailCode({ email: "user@example.com", code: "12345678" })
// { token, expiresAt, user: { id, email } } — token stored automatically

const user = await g.auth.currentUser()
// { authenticated: true, userId: "usr_...", email: "user@example.com" }

await g.auth.logout()
```

### 删除账户

```js
await g.account.delete()
```

自助去除——"删除我的账户"屏幕. 每个应用 **应用** a. 用于任何账户创建的应用程序。 服务器侧是完整的级联:会话被取消,用户的记录和文件被删除,他们的订阅行被删除. 不可逆的——在它面前贴出一个真正的确认.

## 移动-博览会和斯威夫特

手机应用与浏览器应用是相同的合同:公钥识别应用,会话授权人. 已验证域为浏览器控制- 应用程序发送否 `Origin`,所以没有进行校验; 构建仿佛任何请求都可以来自任何地方,并让会话和服务器的规则决定.

**博览会/反应原生.** `@gemmein/sdk/expo` 这是同一个软件包吗,第二个切入点 在一个电话的4个接合器中填充 —— 会话的所在, “软件在前面是怎样回答的?” `fetch` 带着字节和客户端标签上写的 在应用程序中安装对等器, 而不是在您的单曲中: `npx expo install expo-secure-store expo-file-system`。 。 。 .

```js
import { createExpoGemmein } from "@gemmein/sdk/expo"
import { AppState, Platform } from "react-native"

export const g = createExpoGemmein({ appKey: "pk_live_..." }, { AppState, Platform })
```

每个模块都是可选的——没有通过,条目解决 `expo-secure-store`, (中文(简体) ), `react-native` 财务报告和审定财务报表 `expo/fetch` 懒得第一次使用。 可注射键是 `SecureStore`, (中文(简体) ), `AppState`, (中文(简体) ), `Platform`, (中文(简体) ), `FileSystem` 财务报告和审定财务报表 `fetch`; 客户端标签读取 `expo-ios` 编号 : `expo-android` 编号 : `expo-web` 当你通过 `Platform`,以及 `expo` 当你不这样做. `apiUrl` 是客户端的选项, 因此将应用程序指向本地 `gemmein dev` 引擎是一个字段 : `createExpoGemmein({ appKey, apiUrl: "http://127.0.0.1:4545" }, { AppState, Platform })`。 。 。 .

**斯 Sw.** `GemmeinSwift` ——iOS 17+ / macOS 14+,无依赖性,同为斯威夫特idiom中的方法名称. 单行 `Package.swift`数字 :

```swift
.package(url: "https://github.com/gemmeinhq/gemmein-swift.git", from: "0.10.0")
```

**无论是哪种方式,存储购买.** `currentUser()` 携带 `storeAccountToken` 一张不透明的每人身份证明 把它交给FinancialCat作为应用程序用户代号,一个商店的webhook通过中继器解决了完全一个人的问题,没有你的应用程序密钥或个人的电子邮件进入第三方的分类账.

```js
const me = await g.auth.currentUser()
if (me.authenticated && me.storeAccountToken) {
  await Purchases.configure({ apiKey: RC_KEY, appUserID: me.storeAccountToken })
}
```

整个移动地表——手机接通的代码,商店道路,模拟器的两个主机事实——位于 **[docs.gemmein.com/移动](https://docs.gemmein.com/mobile)**。 。 。 .

## 存储

收藏品由程序所有人在仪表板上创建([docs.gemmein.com/console/data 页面存档备份,存于互联网档案馆](https://docs.gemmein.com/console/data))——SDK无法创建. A 404 (韩语) `unknown_collection` 表示它还不存在: 要求应用程序所有者添加它(一击),并从下表中选择它的规则.

```js
const tasks = g.collection("tasks")

const task = await tasks.create({ title: "Buy milk", done: false })

// Records come back WRAPPED — your fields live under .data:
//   { id, data: { title, done }, createdAt, updatedAt }
// Read task.data.title, NOT task.title. This trips up AI-generated code
// more than anything else — if your UI shows blanks, this is why.
console.log(task.id, task.data.title)

// list() returns { records, cursor, hasMore } — records is the array
const { records } = await tasks.list()
records.forEach(r => console.log(r.data.title))
const recent = await tasks.list({ limit: 10, sort: "newest" })
const filtered = await tasks.list({ where: { done: false } })   // exact-match filters
const one = await tasks.get("rec_abc123")
await tasks.update("rec_abc123", { done: true })
await tasks.delete("rec_abc123")

// Images/files: presigned upload, returns a REFERENCE to store in a record
const file = await tasks.upload(imageBlob, { name: "avatar.png" })
// { id, ref, contentType, sizeBytes }   ref looks like "file:<uuid>"
await tasks.create({ title: "Profile", avatar: file.ref })

// To show or download it — one call, whatever the collection:
const { url } = await g.files.link(record.avatar)
// public collection → a permanent, cacheable URL
// anything else     → a signed URL valid for a couple of minutes, re-checked
//                     against who you are and what you still hold
```

存储参考文献, 绝不使用 URL 。 推荐书不会过期,会给 单靠自己什么都不是; `link()` 每次都是授权的地方 那个 也意味着如果一个收藏后来从 公为私.

**约束,诚实地说:** 取消访问停止 Gemmein 发布新链接 马上 在某人手中的链接一直有效,直到到期为止. 没什么 可以收回他们已经下载的文件——这是控制下交付,而不是 DRM(英语:DRM).

### 收集规则

每个收藏都有一条规则,设置在仪表板上. 服务器执行它——您的应用程序从未执行授权 :

| 规则 | 谁识字 | 谁会写 | 使用大小写 |
| --- | --- | --- | --- |
| `private` | 仅所有者 | 仅所有者 | 用户的个人数据(任务,笔记,设置) |
| `shared` | 所有认证用户 | 每个用户:只有自己的记录 | 饲料、社区、团队板 |
| `public_read` | 任何人( 不需要登录) | 只能从仪表板、中继器或您的服务器(密钥)获取 App 所有人 | 菜单,上市,营销页面,单作者博客(你卖的是 `g.payments.products()`,从不收藏) |
| `community` | 任何人( 不需要登录) | 每个登录用户:只有自己的记录——纯文本 | 多作者博客、公共董事会、简介 |
| `addressed` | 每个用户:只发给他们的记录 | 从仪表板、中继器或您的服务器(密钥)中, App 所有人, 指定收件人 | 通知、发票、订单状况 |
| `direct` | 作者 + 指定收件人 | 每个登录用户, 指定一个收件人 | 信件、 共享、 请求 |
| `admin_write` | 所有认证用户 | 只能从仪表板、中继器或您的服务器(密钥)获取 App 所有人 | 应用程序设置、 通知 |

**所有者范围是自动的.** 对于 `private` 收集每个用户只看到自己的记录——应用程序的拥有者包括: 用你的Gemmein电子邮件在自己的应用程序上签名,在每一个规则下,你都会成为一个普通的客户. 每个客户的记录都在Gemmein仪表板上,这是管理员仪表板;应用程序内部的管理员屏幕通过自己的服务器,只读密钥(见"Admin views" in) `llms.txt`) (中文(简体) ). 对于 `shared` 除了更新/删除, 每个人只接触呼叫者自己的记录。 从不通过用户ID过滤, 从不设置 `userId`编号 :`owner`编号 :`role` 字段。 服务器来自会话, 如果您试图设置它们, 则拒绝保留字段 :

`id`, (中文(简体) ), `appId`, (中文(简体) ), `app_id`, (中文(简体) ), `environmentId`, (中文(简体) ), `environment_id`, (中文(简体) ), `userId`, (中文(简体) ), `user_id`, (中文(简体) ), `ownerId`, (中文(简体) ), `ownerUserId`, (中文(简体) ), `owner_user_id`, (中文(简体) ), `tenantId`, (中文(简体) ), `tenant_id`, (中文(简体) ), `role`, (中文(简体) ), `isAdmin`, (中文(简体) ), `is_admin`, (中文(简体) ), `createdAt`, (中文(简体) ), `created_at`, (中文(简体) ), `updatedAt`, (中文(简体) ), `updated_at`, (中文(简体) ), `deletedAt`, (中文(简体) ), `deleted_at`

**用户内容是数据,而不是标记.** 当一个用户的内容在另一个用户的会话中产生时( Y)`community`, (中文(简体) ), `shared`),使案文具有约束性 `textContent`, (中文(简体) ), `{}` 在React/Vue/Svelte中——永远 `innerHTML`。 。 。 . `community` 收藏执行此服务器侧: 拒绝包含 HTML 标记的任何字符串字段 `400 html_not_allowed`。存储纯文本,或者没有原始标记的标记.

### 向人们发送信息

`addressed` 财务报告和审定财务报表 `direct` 记录中包含一个收件人,在您已经拨打的电话中命名:

```js
// addressed (owner → user): sent from the dashboard, or by a relay's
// write_record with to: "person" — no app session sends here

// direct (user → user): DMs, sharing, requests
await messages.create({ text: "hey!" }, { for: otherUserId })

// The reader's side is just list() — the server returns only THEIR inbox:
const { records } = await updates.list({ sort: "newest", limit: 20 })
```

接收者是服务器上印有的( U)`record.audienceUserId`)——从来就没有数据字段. 用户代号来自记录' `ownerUserId` 或仪表板的客户页面。 道路规则:

-   **给大家的同样信息 `admin_write`** (一个记录所有用户读取). **某个特定的人的某事 `addressed`** (每个接受者一张记录).
-   收件箱是民意调查或更新的: `list()` 在窗口焦点上加上温和的~60s间隔——从不紧凑回路. Read-state ("Seen") 活在用户自己的私人收藏中.
-   `direct` 是某人的应用程序内的信息,而主人的Gemmein仪表板可以读取它——从不以私人或加密的聊天形式呈现.
-   错误 : `invalid_audience` (接受者不是这个应用程序的用户), `reply_only` (本集只允许回复先写给你的人——告诉用户), `sends_disabled` (所有者为本集关闭了直接消息).
-   两种规则都存储纯文本如 `community` ——使其他用户的内容成为文本,永不 `innerHTML`。 。 。 .

### 内容——当用户竞相追求相同事物时

许可模式无法阻止两个人预订相同的3pm槽. 前提可以,每个只是你已经打过电话的争论. **409号 `conflict` 他们中的任何一个都是有效的机制,不是重试错误** ——抓好,告诉用户"槽"/"股票"/"编辑"被取走.

```js
// Uniqueness: derive the key from the thing that must be unique.
// Second writer → 409. Your own retry → your record back (existing: true).
// Deleting the record frees the key.
await bookings.create({ who: email }, { key: "slot:2026-07-15T15:00" })

// Limited stock, N units anyone can buy: claim units with keyed creates —
// on conflict try the next unit; all taken = sold out. Race-proof under
// every safety rule (writes on OTHER users' records are never allowed).
await orders.create({ item: 42 }, { key: "unit:item42:1" })  // then :2 … :N

// Your own counters: the server does the math on current state.
// Breaching the floor/ceiling → 409, record untouched.
await products.update(id, { stock: { decrement: 1, floor: 0 } })

// Shared editing: pass back the version you read — a stale save gets 409
// instead of silently clobbering someone's edit. Re-read, reapply, retry.
await pages.update(id, { body }, { ifVersion: page.version })
```

补丁中的物体只有在其键完全相同时才被视为原子操作 `increment`|`decrement` (+ 可选) `floor`|`ceiling`),所有数字——其他任何数据都作为普通数据存储. 键是 1 -120字符 字母,数字,和 `: _ . @ / -`。永远不要找到当时的创建,也永远不要计算计数器客户端:两种种族,只有在真正的用户相撞时两者都失败.

## 支付(Stripe)——你不会建立网页

Gemmein 主持您的 Strade Webhook 并管理您的订阅: 准确的每个客户一个( 电子邮件上对大小写不敏感) , 由支付本身创建, 降级到您取消时的默认计划, 脱序的 Strade 事件解决到最新的 。 应用程序所有者用仪表盘上的受限键连接 Strepe **付款** gemmein在网页上登记, 并让每个支付链接都用花条。 没有种子。 你的应用程序有两种工作:

```js
// 1. Send the buyer to checkout — one call, Gemmein does the rest. Gemmein
//    made each priced plan's Stripe Payment Link through the owner's key;
//    g.subscriptions.checkout() picks the right one and wires the signed-in buyer in.
//    Never build checkout URLs or sessions yourself: raw emails are
//    silently dropped by Stripe's URL rules, and sessions need a secret
//    key that must never ship client-side.
await g.subscriptions.checkout("pro")   // redirects; omit the arg to buy the paid plan
// GemmeinError codes worth handling: "authentication_required" (sign in
// first), "plan_has_no_link" (the owner hasn't connected Stripe and priced
// that plan yet).
// err.message is written for the buyer and safe to show; the owner's fix
// is in their dashboard's Logs.

// 2. Gate paid features by reading the managed subscription:
const sub = await g.subscriptions.mine()   // { plan, status } or null (never paid / payments off)
if (sub?.plan === "pro") { /* unlock */ }
```

执行 **没有** 写一个网路处理器。 这样做 **没有** (原始内容存档于2018-10-21). Power Frede. 执行 **没有** 在自己的收藏中存储计划/订阅状态 - `g.subscriptions.mine()` 是真理的唯一来源, 并且故意没有客户端写路径.

计划 **限制** (注数,特征盖,座位号)是您应用的逻辑——Gemmein只告诉你在哪个计划中;仪表板的计划名称没有配额.

一项计划是三种方式之一的销售,设定在付款页上:通过Frede——一种价格,与Frede连接,以及支付链接Gemmein制作(`checkout` 航行在那里,通过 **中继** - 任何提供商,其网页绘制的拥有者地图(GoCardless、Lemon Squeezy、Paddle、银行转账)都给予该地图 `grant_plan` 中继动作并用 `revoke_plan` -或者说 **还没有**。 。 。 . `g.subscriptions.mine()` 同样的回答 `{ plan, status }` 不论路由写作; `checkout` 计划通过中继器出售或尚未答复 `"plan_not_sellable"` (409) (英语).

### 出售物品(一次性购买)

计划是订阅。 卖出一个 **东西** - 海报、节拍、电子书、会话 - 店主加了 **产品** 在同一付款页和套数上 **每个都怎么卖**:通过Frede(价格,有Frede连接——Gemmein使支付链接),通过a **中继** (任何由他们绘制网络图的供应商——GoCardless、Lemon Squeezy、Paddle、一家应用商店,通过FinanceCat、银行转账),或 **还没有** (产品是确定的,其赠款和信贷是已知的,没有公路线).

```js
// One product covering many items (license tiers over a catalog)? Name the
// item — display text only; the PRICE always comes from the provider:
await g.payments.buy("premium license", { item: "beat_37" })   // redirects
// "product_not_sellable" (409) = sold via a relay, or not yet: there is no
// Payment Link to open. "unknown_product" (404): check the name your app
// sends — the owner's Logs list what this environment sells.

// Fulfilment: Gemmein records every completed payment itself, so the buyer's
// proof does not live in your data. Gate on THIS, never on the redirect
// coming back (redirects can be faked; the record comes from the provider's
// signed webhook):
const purchases = await g.purchases.mine()
const paid = purchases.find(p => p.item === "premium license" && p.status === "paid")
if (paid?.delivery?.type === "gemmein_file") {
  const { url } = await g.files.link(paid.delivery.file, { intent: "download" })
}
```

每次购买都是 `{ item, kind: "purchase" | "subscription", status: "paid" | "part_refunded" | "refunded", amountMinor, currency, refundedMinor, grants, paidAt, delivery? }`首先,已使用的退款——数额 **小单位** (便士,一分钱) 完全如供应商所报告, 所以格式化是你的, 没有什么是圆形的。 卖出一个 **文件**,所有者将其附在产品卡上: `delivery: { type: "gemmein_file", file }` 财务报告和审定财务报表 _实值_ 授权,重新检查 `g.files.link()` - 全额退款会缩短下载时间. `delivery: { type: "external_url", url }` 是简单的交接:Gemmein控制谁被告知,谁不能使用.

A 类 **收据** 收集(规则) `addressed`现在 **选项** - 自己屏幕的证明记录 仅此而已 财经真相是 `g.purchases.mine()`,如果您重命名或删除该收藏,则真实性保持不变.

**没有车,没有数量** ——按设计每一次抽出一出产品. "一卡通"是N的取出,或者一个捆绑的产品,所有者的价格作为捆绑. 不要造一个车UI,否则保证。 仅数字化接入:实物货物,航运和库存超出范围. 全部细节 : **[docs.gemmein.com/支付](https://docs.gemmein.com/payments)**。 。 。 .

### 关于公共收藏的草稿

打开 `public_read` 财务报告和审定财务报表 `community` 藏书, `{ published: false }` 保存一个 **草案** 公众看不见——服务器强制,作者仍然看到他们自己的(而主人的仪表板看到每一个草稿):

```js
const post = await notes.create({ title: "wip" }, { published: false })  // hidden
await notes.update(post.id, {}, { published: true })                     // now live
```

将当前状态读回为 **顶级** 字段 - `record.published` (布尔),不 `record.data.published` (地点与 `id` 财务报告和审定财务报表 `updatedAt`,而不是在你的田间。 非作者只收到出版的唱片,所以你只会看到 `false` 在自己的草稿。 这就是你如何在作者自己的名单上 制作"未放出"的徽章.

永远不要假的草稿 `status` 字段 + 公众收藏上的客户端过滤——数据仍然可以到达每个读者的网络分页. `published` 是选项,不是数据字段;服务器在内部拒绝它 `data`编辑 **字段** 无论规则如何,每张唱片都回过头来 私人唱片读了 `published: true`,此选项无法写出.

## 贷项

A 类 **信贷** 是签约人持有的数量和你的产品开支——他们购买的一包(带有"赠款"的商品),他们支付的计划("每个时期的信用",在每个支付期间发放),所有者给予的补偿,继电器的补助. `g.credits.balance()` 是数字 **现在**,服务器已解析,所以您的计量器从未在零时拒绝的平衡上对客户端进行算术;您自己的服务器的支出是 `gemmeinServer(sk).spendCredits(personId, { amount, reason, key })`,1个有条件更新的下限为 0 `402 credits_exhausted` 携带平衡。 故意没有客户端写入路径 。 全部细节 : **[参考文献.md](https://npmcn.com/package/%40gemmein/sdk/REFERENCE.md)** → _贷项_,以及 **[docs.gemmein.com/资信](https://docs.gemmein.com/credits)**。 。 。 .

## 大赦国际

`g.ai.run(tool, inputs)` 调用 a **命名的 AI 工具** 定义的拥有者——服务器从工具自己的指令和模板(绝不是浏览器)中来构成提供者的请求,打开它,花费工具的入分和流出提供者自己的回答; `g.ai.runText(tool, inputs)` 是同一个调用收集到一个字符串,以及 `g.ai.calls()` 是签约人自己的历史。 提供者密钥与Gemmein同住,从未到达浏览器. `g.ai.chat(body)` 是原始路径——提供商自己的请求机构,并且它是 **默认关闭** (单位:千美元)`403 raw_calls_off`),直到所有者开关生取出这把钥匙. 全部细节 : **[参考文献.md](https://npmcn.com/package/%40gemmein/sdk/REFERENCE.md)** → _大赦国际_,以及 **[docs.gemmein.com/ai (中文(简体) )](https://docs.gemmein.com/ai)**。 。 。 .

```js
const summary = await g.ai.runText("summarise", { text })
const { balance } = await g.credits.balance()
```

## 中继

A 类 **中继** 一个触发器——另一个提供商的Webhook到达,一个时钟,一个记录的改变——和一个Gemmein自己输入的1到10个动作,运行顺序是:允许或取消访问,完成或退款一个产品,给予信用,写一个记录,给一个人发电子邮件,呼叫一个URL. 老板写道 `gemmein/relays/<name>.json` (或选择控制台中的模板); Gemmein 验证签名,将身体映射到已命名的字段,并运行动作. 内部没有计算——计算你的宿主,后面 `call_url`这条路是应用商店购买出行的路线,这条路是支付服务商以外的出行. 是配置,不是SDK表面——你的应用程序只读过结果(`g.purchases.mine()`, (中文(简体) ), `g.credits.balance()`,一个门式收藏成功)。 全部细节 : **[参考文献.md](https://npmcn.com/package/%40gemmein/sdk/REFERENCE.md)** → _中继_,以及 **[docs.gemmein.com/中继器](https://docs.gemmein.com/relays)**。 。 。 .

## 服务器侧( API 路由, cron 任务)

对于信任的服务器代码, 使用 `gemmeinServer` 带有有范围的秘密密钥`sk_...`——在仪表板上创建,每集范围:

```js
import { gemmeinServer } from "@gemmein/sdk"

const server = gemmeinServer(process.env.GEMMEIN_SECRET_KEY)

const tasks = await server.collection("tasks").list()
await server.collection("tasks").update("rec_abc123", { done: true })
await server.collection("tasks").create({ title: "Welcome" }, { for: personId })
await server.collection("tasks").delete("rec_abc123")
```

一个秘密的密钥读取它被标注到的集合,并且——当它被刻制出"读写"时——在那里创建并更新记录 **任意** 规则;它只删除被勾选的“ 删除也”和 a **全键** (小写为"每集") 读取,写出并删除出处. 服务器创建的记录在呼叫中被命名: `private` • 妇女 `shared` • 妇女 `community` 带 `{ for: personId }` (拥有者), `admin_write` • 妇女 `public_read` 不带任何人(应用程序的记录), `addressed` 带 `{ for }` (接受者), `direct` 带 `{ from, for }` (作者和收件人);失踪或额外人员为: `400 person_required` 编号 : `invalid_person`。每个服务器写入的都是命名密钥的日志行。 超越它打开 **大门**,用于您的代码运行于您的主机: `verifySession(token)` 将浏览器会话转换成个人和他们持有的东西, `holdings(personId)` 自己来回答, `grantAccess` 编号 : `revokeAccess` 一项补助金(补助金终止一次——第二次撤销是) `409 already_revoked`, (中文(简体) ), `spendCredits` 学分是有原因的, `invitePerson(email)` 通过地址创建或抓取一个人,以及 `notify(personId, …)` 您的应用程序之一的人。 每个都有一个在密钥上刻出的能力 当它被刻出时; 一个不刻出的能力是 `403 capability_required`永远没有管理权限 从不放 `sk_` 键在浏览器代码中(如果尝试,SDK会扔出).

**给自己的人发邮件—— `notify`。 。 。 .** 它发电子邮件给一个经核实的你应用程序的人, 通过ID,从来没有通过地址(`404 not_a_customer` 否则;地址是服务器自己的记录. 它只从 **您已核实的发送者域**: 在域名页面上验证一个之前, 每个呼叫都被拒绝 `409 sender_domain_required` 和没有叶子,没有记录, 没有花帽,是一样的 `key` 你一核实就发出 它永远不会回到Gemmein的地址上——签入的代码是Gemmein之前代表您发送的电子邮件,因为 _(通过Gemmein)_两种类型都离开你的领域 **账户** 词 - `kind: "event"` (缺省数,每人每天5个)和 `kind: "account"` (安全和账户通知,不设每人上限) **新闻** 语言是用于广播。 两者都计算为每小时200个应用程序;在开发中,每个应用程序每天20个应用程序和每个账户50个应用程序`429 development_capped` ——试验体积 `npx gemmein dev`) (中文(简体) ). 每个寄信人都会在收件箱里作为谈话 回答就会回来 送同样的东西给很多人, 或者在网路上,有继电器 `email_person` 换句话说.

```js
await server.notify("usr_abc123", {
  subject: "Your order shipped",
  text: "Order #142 left the warehouse today.",
  key: "order-142-shipped",   // retries can't double-send
})
```

## 错误

投出各种方法 `GemmeinError`数字 :

```js
import { GemmeinError } from "@gemmein/sdk"

try {
  await g.collection("tasks").create({ title: "Test" })
} catch (err) {
  if (err instanceof GemmeinError) {
    err.code     // "auth_expired", "unknown_collection", "scope_denied",
                 // "not_found" (also when touching a record you don't own —
                 // existence is never leaked), ...
    err.status   // HTTP status
    err.message  // human-readable, includes what to do next
    err.resetAt  // rate limits: when to retry
    err.requires // 403 entitlement_required: the plan/product key this
                 // collection asks for — show your upgrade screen
  }
}
```

| 代码 | 状态 | 含义 |
| --- | --- | --- |
| `missing_app_key` | 401 (中文(简体) ) | 没有应用键 — 在 app. gemmein.com 上获得一个 |
| `invalid_app_key` | 403 (韩语) | 未识别密钥( typo, 或错误的环境) |
| `auth_expired` | 401 (中文(简体) ) | 会话已过期—— SDK 自动清除符号 |
| `unknown_collection` | 404 (韩语) | 收藏不存在——在仪表板上创建 |
| `scope_denied` | 403 (韩语) | 此收藏/ 动作没有范围的秘密密钥 |
| `html_not_allowed` | 400个 | 社区收藏存储纯文本 – 删除 HTML 标签 |
| `invalid_file_content` | 400个 | 上传的字节不是他们声称的图像类型——上传实际的图像,不是重命名的文件 |
| `unknown_product` | 404 (韩语) | 没有这个名称的产品 —— 请检查您的应用程序发送的名称 ; 拥有者的日志列出此环境的销售内容 |
| `invalid_publish` | 400个 | `published` 仅是公共收集的选项,不是数据字段,也不是范围规则 |
| `forbidden` | 403 (韩语) | 规则拒绝了这一点——你的用户没有的许可. **永远不要重试**:同一电话将永远被拒绝. 修正方法(错误的收集规则,不写给 `admin_write`或显示 `err.message`。 。 。 . |
| `entitlement_required` | 403 (韩语) | 签入,但不在计划(或持有出品)上,此收藏被解锁. `err.requires` 携带该计划的关键`access:pro` 为了一个名为专业的计划。 后期成功的一款403:显示您的升级显示屏,送他们去退票,在他们握住后再进行再试. |
| `denied` | 429个/401个 | 普遍拒绝一切可收回或可修复的东西:费率限额(429美元) `resetAt`,等待和重试)或缺失的登录(401——先通过 `g.auth.sendEmailCode`) (中文(简体) ). 按 HTTP 状态区分; 显示 `err.message`,每个字写得正确. |
| `invalid_collection_name` | 0 (客户端) | `g.collection(name)` 被赋予了语法以外的名称——小写字母,数字和下划线,从字母开始,为2-63字符. 在一个请求存在之前抛出. |
| `secure_store_unavailable` | 0 (客户端) | 令牌店无法保存会话——拒绝的浏览器 `localStorage` 写, `expo-secure-store` 不在场或被拒绝, 一个键链说不. `err.cause` 携带商店本身的错误。 通过 a `tokenStore` 联合国 `MemoryTokenStore` 将会话保留为整个过程的生命. |
| `network_unreachable` | 0 (客户端) | 请求从未到达Gemmein——没有连接,一个无法解决的宿主,a `apiUrl` 指着什么。 消息名称为主机; `err.cause` 载运错误。 与拒绝无关. |

**错误代码分支 :** 开关 _具体名称_ 上面的代码。 最重要的一条规则是: `forbidden` 表示停止——重试永远不会成功; `denied` 意味着该请求可以稍后生效(等待 `resetAt` 429号,签到401号 仅限费率 `denied` 携带 `resetAt` ——这是重试后的可靠信号.

## 密钥环境( E)

| 前缀 | 环境 | 它的栖息地点 |
| --- | --- | --- |
| `pk_test_...` | 发展 | 前端代码——安全曝光 |
| `pk_live_...` | 生产 | 前端代码——安全曝光 |
| `sk_dev_...` 编号 : `sk_live_...` | 开发/ 程序 | 服务器 env vars 只运行您的应用程序; 绝不链接或同步 |
| `sk_cli_...` | 发展 | CLI自己的钥匙,等你的人同意后交给它 `npx gemmein login` 在浏览器中——从未显示或粘贴。 持续7天;在 `gemmein/.data/`永远不要 |
| `sk_sync_...` | 生产 | 一个Live推键,交给CLI一个批准 `gemmein sync --live` - 10分钟,当推完成后关闭,从未显示 |

环境是完全孤立的:不同的数据,不同的用户,不同的集合.

## 管理仅限仪表板

收藏、域、密钥、付款配置、日志和使用情况均在 [仪表板](https://app.gemmein.com/) ——故意不在SDK中,因此管理层的资信不能从应用代码中泄露出. 每个房间都走着, 屏幕一样,在 [docs.gemmein.com/会所](https://docs.gemmein.com/console)。 。 。 .

* * *

Gemmein是一个早期发布:上面的核心是活的,安全审计的,并且可以安全地继续发展;更广泛的特征是分阶段推出的. [gemmein.com (英语)](https://gemmein.com/) • 妇女 [你好@gemmein.com](mailto:hello@gemmein.com)

## 常见问题

### @gemmein/sdk 是什么？

Gemmein SDK——无密码认证,安全存储,以及用于AI所建应用的花纹驱动记录翻转\. 小到一个提示教整个API\.

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

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

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

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

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

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

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

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

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

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

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

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

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

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

