@karpoland/sdk 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.ja.md +6 -6
- package/README.md +6 -6
- package/README.zh-CN.md +6 -6
- package/dist/cli.js +1 -1
- package/dist/index.cjs +1 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/package.json +2 -1
package/README.ja.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
[English](
|
|
1
|
+
[English](https://machinepulse-ai.github.io/karpoland-app-sdk/) | [简体中文](https://machinepulse-ai.github.io/karpoland-app-sdk/zh/) | 日本語
|
|
2
2
|
|
|
3
3
|
# @karpoland/sdk
|
|
4
4
|
|
|
@@ -11,7 +11,7 @@ Karpo Land ミニアプリ向けの公式 TypeScript/JavaScript SDK です。あ
|
|
|
11
11
|
- **`simulate` / `mockPlatform`**(`@karpoland/sdk/testing`):署名付きの配信とモックプラットフォームで、ネットワークなしにサービスをテストします。
|
|
12
12
|
- **`createDeveloperClient`** と **`karpoland`** CLI:slug でアプリを登録し、キーを発行し、サービスを別ドメインへ移し、メンバーと譲渡を管理し、ページをパッケージして公開します。
|
|
13
13
|
|
|
14
|
-
バージョン 1.0.
|
|
14
|
+
バージョン 1.0.1 です。メソッド名は [機能一覧](https://machinepulse-ai.github.io/karpoland-app-sdk/ja/capabilities.html) のもので、Go・Python の SDK と共通です。サーバー側のクライアントが送るリクエストにはすべて `User-Agent: karpoland-sdk-ts/1.0.1` が付きます。
|
|
15
15
|
|
|
16
16
|
Node ≥ 18、ESM と CommonJS に対応し、ランタイム依存はありません。
|
|
17
17
|
|
|
@@ -67,7 +67,7 @@ npm exec --no -- karpoland publish --manifest manifest.json --pages ./page --not
|
|
|
67
67
|
|
|
68
68
|
`publish` はマニフェストを確認し、サービスのドメインが未検証ならまず検証し(トークンはサービス自身が提供します)、ページをアップロードして公開します。プラットフォームのハンドシェイクで、宣言したすべてのツールと hook にハンドラーがあるかが確認されます。プラットフォームを使わずにツールと hook をテストするには `@karpoland/sdk/testing` を使います([テスト](#テスト))。
|
|
69
69
|
|
|
70
|
-
[`examples/hello/typescript`](
|
|
70
|
+
[`examples/hello/typescript`](https://machinepulse-ai.github.io/karpoland-app-sdk/ja/resources/examples.html) は最小のアプリです。[`examples/dice/typescript`](https://machinepulse-ai.github.io/karpoland-app-sdk/ja/resources/examples.html) はこの SDK で作ったサイコロテーブルの完全なアプリです(セッション、タイマー、アプリメッセージ、ボード、ページ)。
|
|
71
71
|
|
|
72
72
|
## アプリサービス:`createApp(options)`
|
|
73
73
|
|
|
@@ -135,7 +135,7 @@ app.tool<Args>(name, async (ctx, args) => …)
|
|
|
135
135
|
app.hook("timer.fired", async (ctx, data) => { data.key; data.payload; });
|
|
136
136
|
```
|
|
137
137
|
|
|
138
|
-
マニフェストでは `handler: true` を付けて hook を宣言します。`ctx` には `event`、`deliveryId`、`attempt`、`install`、`sessionId`、`residentId`(その hook が代わりに操作できる住人)、`data`(イベントごとに型付け、[
|
|
138
|
+
マニフェストでは `handler: true` を付けて hook を宣言します。`ctx` には `event`、`deliveryId`、`attempt`、`install`、`sessionId`、`residentId`(その hook が代わりに操作できる住人)、`data`(イベントごとに型付け、[イベント](https://machinepulse-ai.github.io/karpoland-app-sdk/ja/reference/events.html))、`karpo`(配信のコンテキスト `MP-Karpo-Delivery` にあるもの)があります。
|
|
139
139
|
|
|
140
140
|
### 重複排除
|
|
141
141
|
|
|
@@ -373,7 +373,7 @@ const manifest = defineManifest({ ... }); // throws ManifestError listing every
|
|
|
373
373
|
validateManifest(manifest, { allowHttp: true }); // → [{ field: "manifest.tools[0].name", message }]
|
|
374
374
|
```
|
|
375
375
|
|
|
376
|
-
マニフェストはアプリにできることを記述します。表示用のフィールド(名前、概要、アイコン、色)はアプリのレコードにあり、`apps.update` で変更します。`name` はプラットフォームが必須としているためマニフェストにも残っています。型はプラットフォームのマニフェスト構造にフィールド単位で対応しており([
|
|
376
|
+
マニフェストはアプリにできることを記述します。表示用のフィールド(名前、概要、アイコン、色)はアプリのレコードにあり、`apps.update` で変更します。`name` はプラットフォームが必須としているためマニフェストにも残っています。型はプラットフォームのマニフェスト構造にフィールド単位で対応しており([マニフェスト](https://machinepulse-ai.github.io/karpoland-app-sdk/ja/reference/manifest.html) と照合済み)、`connect`(ページが接続できるオリジン:https または wss、パスなし、サブドメインは `*.`、最大 10 個)や `install_policy`(`anyone`、または `developer`:アプリのオーナーとメンバーだけが追加でき、アプリ広場への掲載や open スコープのセッション kind の宣言はできません)も含みます。これが唯一のバリデーターです。Go と Python の SDK は型だけを持ち、`npm exec --no -- karpoland validate` を案内します。
|
|
377
377
|
|
|
378
378
|
**アプリ広場。** `listing: { square: true, category: "game" | "social" | "tool" | "fun" | "work", tagline (≤ 30), cover_color? }` を公開中のバージョンで宣言すると、アプリがアプリ広場に掲載されます。`square: true` を持つボードもそこに表示されますが、設定できるのは `owner: "app"` かつ `visibility: "public"` のボードだけです。インストール・ルーム・セッションのボードがアプリ広場に表示されることはありません。
|
|
379
379
|
|
|
@@ -537,6 +537,6 @@ npm test # unit tests, the spec/ name table and fixtures,
|
|
|
537
537
|
KARPO_IT=1 npm run test:integration # requires a local stack at KARPO_API (default http://127.0.0.1:8090) and people.json (KARPO_IT_PEOPLE)
|
|
538
538
|
```
|
|
539
539
|
|
|
540
|
-
`test/spec.test.ts` は、クライアント、アプリ、ハンドラーのコンテキスト、テストキット、ページクライアント、開発者クライアントの名前が
|
|
540
|
+
`test/spec.test.ts` は、クライアント、アプリ、ハンドラーのコンテキスト、テストキット、ページクライアント、開発者クライアントの名前が `spec/api.json` と完全に一致すること、`spec/reasons.json`、`events.json`、`limits.json` がコードと一致すること、そして(コンパイル時と実行時に)`Manifest` 型が `spec/manifest-fields.json` のフィールドから SDK が省いたものを除いたものとちょうど一致することを確認します。`test/fixtures.test.ts` は `spec/fixtures` のすべてのケースを実行します。`src/reasons.ts` と `spec/reasons.json` はプラットフォームのレジストリから生成されるので、手で編集しないでください。
|
|
541
541
|
|
|
542
542
|
サンプルは `@karpoland/sdk` をインポートします。このリポジトリでは、テストの設定と `tsconfig.json` がそれを `src/` にマッピングします。単体で使う場合は、サンプルのフォルダーで `npm install` するとこのフォルダーがリンクされ(`file:../../../typescript`、事前に `npm run build`)、`npm start` で Node ≥ 22.18 上で実行されます(型の除去)。
|
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
English | [简体中文](
|
|
1
|
+
English | [简体中文](https://machinepulse-ai.github.io/karpoland-app-sdk/zh/) | [日本語](https://machinepulse-ai.github.io/karpoland-app-sdk/ja/)
|
|
2
2
|
|
|
3
3
|
# @karpoland/sdk
|
|
4
4
|
|
|
@@ -11,7 +11,7 @@ The official TypeScript/JavaScript SDK for Karpo Land mini apps. You write the s
|
|
|
11
11
|
- **`simulate` / `mockPlatform`** (`@karpoland/sdk/testing`): test the service with signed deliveries and a fake platform, without a network.
|
|
12
12
|
- **`createDeveloperClient`** and the **`karpoland`** CLI: register an app by slug, issue keys, move the service to another domain, manage members and transfers, pack pages and publish.
|
|
13
13
|
|
|
14
|
-
Version 1.0.
|
|
14
|
+
Version 1.0.1. The method names are those of [Capability overview](https://machinepulse-ai.github.io/karpoland-app-sdk/capabilities.html), shared with the Go and Python SDKs. Every request the server-side clients send carries `User-Agent: karpoland-sdk-ts/1.0.1`.
|
|
15
15
|
|
|
16
16
|
Node ≥ 18, ESM and CommonJS, no runtime dependencies.
|
|
17
17
|
|
|
@@ -67,7 +67,7 @@ npm exec --no -- karpoland publish --manifest manifest.json --pages ./page --not
|
|
|
67
67
|
|
|
68
68
|
`publish` checks the manifest, verifies the service's domain first when it is not verified yet (the service serves the token itself), uploads the pages and publishes; the platform's handshake checks every declared tool and hook has a handler. Test the tools and hooks without the platform with `@karpoland/sdk/testing` ([Testing](#testing)).
|
|
69
69
|
|
|
70
|
-
[`examples/hello/typescript`](
|
|
70
|
+
[`examples/hello/typescript`](https://machinepulse-ai.github.io/karpoland-app-sdk/resources/examples.html) is the smallest app; [`examples/dice/typescript`](https://machinepulse-ai.github.io/karpoland-app-sdk/resources/examples.html) is the full dice table app (sessions, timers, app messages, boards, a page) on this SDK.
|
|
71
71
|
|
|
72
72
|
## The service: `createApp(options)`
|
|
73
73
|
|
|
@@ -135,7 +135,7 @@ The return value is the answer:
|
|
|
135
135
|
app.hook("timer.fired", async (ctx, data) => { data.key; data.payload; });
|
|
136
136
|
```
|
|
137
137
|
|
|
138
|
-
Declare the hook in the manifest with `handler: true`. `ctx` has `event`, `deliveryId`, `attempt`, `install`, `sessionId`, `residentId` (the resident the hook may act for), `data` (typed per event, [
|
|
138
|
+
Declare the hook in the manifest with `handler: true`. `ctx` has `event`, `deliveryId`, `attempt`, `install`, `sessionId`, `residentId` (the resident the hook may act for), `data` (typed per event, [Events](https://machinepulse-ai.github.io/karpoland-app-sdk/reference/events.html)) and `karpo` (in the delivery's context, `MP-Karpo-Delivery`).
|
|
139
139
|
|
|
140
140
|
### Deduplication
|
|
141
141
|
|
|
@@ -373,7 +373,7 @@ const manifest = defineManifest({ ... }); // throws ManifestError listing every
|
|
|
373
373
|
validateManifest(manifest, { allowHttp: true }); // → [{ field: "manifest.tools[0].name", message }]
|
|
374
374
|
```
|
|
375
375
|
|
|
376
|
-
The manifest describes what the app can do. Display fields (name, summary, icon, color) live on the app record and change with `apps.update`; `name` stays in the manifest because the platform requires it. The types follow the platform's manifest structure field by field (checked against [
|
|
376
|
+
The manifest describes what the app can do. Display fields (name, summary, icon, color) live on the app record and change with `apps.update`; `name` stays in the manifest because the platform requires it. The types follow the platform's manifest structure field by field (checked against [Manifest](https://machinepulse-ai.github.io/karpoland-app-sdk/reference/manifest.html)), including `connect` (origins the pages may reach: https or wss, no path, `*.` for subdomains, at most 10) and `install_policy` (`anyone`, or `developer`: only the app's owner and members may add it, and it cannot list on the square or declare open-scope session kinds). This is the only validator; the Go and Python SDKs have the types and point to `npm exec --no -- karpoland validate`.
|
|
377
377
|
|
|
378
378
|
**The app square.** `listing: { square: true, category: "game" | "social" | "tool" | "fun" | "work", tagline (≤ 30), cover_color? }` lists the app on the square once its live version says so. A board with `square: true` shows there too, but only an `owner: "app"` board with `visibility: "public"` may set it. Install, room and session boards never appear on the square.
|
|
379
379
|
|
|
@@ -537,6 +537,6 @@ npm test # unit tests, the spec/ name table and fixtures,
|
|
|
537
537
|
KARPO_IT=1 npm run test:integration # requires a local stack at KARPO_API (default http://127.0.0.1:8090) and people.json (KARPO_IT_PEOPLE)
|
|
538
538
|
```
|
|
539
539
|
|
|
540
|
-
`test/spec.test.ts` checks that the client, app, handler contexts, test kit, page client and developer client have exactly the names in
|
|
540
|
+
`test/spec.test.ts` checks that the client, app, handler contexts, test kit, page client and developer client have exactly the names in `spec/api.json`, that `spec/reasons.json`, `events.json` and `limits.json` match the code, and (at compile time and at run time) that the `Manifest` type has exactly the fields of `spec/manifest-fields.json` minus the ones the SDK leaves out. `test/fixtures.test.ts` runs every case in `spec/fixtures`. `src/reasons.ts` and `spec/reasons.json` are generated from the platform's registry; don't edit them by hand.
|
|
541
541
|
|
|
542
542
|
The examples import `@karpoland/sdk`: here the test config and `tsconfig.json` map it to `src/`; on their own, `npm install` in an example folder links this folder (`file:../../../typescript`, after `npm run build`), and `npm start` runs it on Node ≥ 22.18 (type stripping).
|
package/README.zh-CN.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
[English](
|
|
1
|
+
[English](https://machinepulse-ai.github.io/karpoland-app-sdk/) | 简体中文 | [日本語](https://machinepulse-ai.github.io/karpoland-app-sdk/ja/)
|
|
2
2
|
|
|
3
3
|
# @karpoland/sdk
|
|
4
4
|
|
|
@@ -11,7 +11,7 @@ Karpo Land 小程序的官方 TypeScript/JavaScript SDK。你编写的是应用
|
|
|
11
11
|
- **`simulate` / `mockPlatform`**(`@karpoland/sdk/testing`):用带签名的投递和假平台测试服务,无需网络。
|
|
12
12
|
- **`createDeveloperClient`** 和 **`karpoland`** CLI:按 slug 注册应用、签发 key、把服务迁到另一个域名、管理成员和移交、打包页面并发布。
|
|
13
13
|
|
|
14
|
-
版本 1.0.
|
|
14
|
+
版本 1.0.1。方法名与 [能力总览](https://machinepulse-ai.github.io/karpoland-app-sdk/zh/capabilities.html) 一致,和 Go、Python SDK 共用。服务端客户端发出的每个请求都带 `User-Agent: karpoland-sdk-ts/1.0.1`。
|
|
15
15
|
|
|
16
16
|
Node ≥ 18,支持 ESM 和 CommonJS,没有运行时依赖。
|
|
17
17
|
|
|
@@ -67,7 +67,7 @@ npm exec --no -- karpoland publish --manifest manifest.json --pages ./page --not
|
|
|
67
67
|
|
|
68
68
|
`publish` 会检查清单;服务的域名尚未验证时先验证域名(token 由服务自己提供);然后上传页面并发布。平台的握手会检查每个声明的工具和 hook 都有处理器。不经平台测试工具和 hook,用 `@karpoland/sdk/testing`([测试](#测试))。
|
|
69
69
|
|
|
70
|
-
[`examples/hello/typescript`](
|
|
70
|
+
[`examples/hello/typescript`](https://machinepulse-ai.github.io/karpoland-app-sdk/zh/resources/examples.html) 是最小的应用;[`examples/dice/typescript`](https://machinepulse-ai.github.io/karpoland-app-sdk/zh/resources/examples.html) 是基于本 SDK 的完整骰子局应用(局、定时器、应用消息、榜单、页面)。
|
|
71
71
|
|
|
72
72
|
## 应用服务:`createApp(options)`
|
|
73
73
|
|
|
@@ -135,7 +135,7 @@ app.tool<Args>(name, async (ctx, args) => …)
|
|
|
135
135
|
app.hook("timer.fired", async (ctx, data) => { data.key; data.payload; });
|
|
136
136
|
```
|
|
137
137
|
|
|
138
|
-
在清单里用 `handler: true` 声明 hook。`ctx` 含 `event`、`deliveryId`、`attempt`、`install`、`sessionId`、`residentId`(该 hook 可以代其操作的居民)、`data`(按事件类型化,见 [
|
|
138
|
+
在清单里用 `handler: true` 声明 hook。`ctx` 含 `event`、`deliveryId`、`attempt`、`install`、`sessionId`、`residentId`(该 hook 可以代其操作的居民)、`data`(按事件类型化,见 [事件](https://machinepulse-ai.github.io/karpoland-app-sdk/zh/reference/events.html))和 `karpo`(处于投递上下文,`MP-Karpo-Delivery`)。
|
|
139
139
|
|
|
140
140
|
### 去重
|
|
141
141
|
|
|
@@ -373,7 +373,7 @@ const manifest = defineManifest({ ... }); // throws ManifestError listing every
|
|
|
373
373
|
validateManifest(manifest, { allowHttp: true }); // → [{ field: "manifest.tools[0].name", message }]
|
|
374
374
|
```
|
|
375
375
|
|
|
376
|
-
清单描述应用能做什么。展示字段(名称、简介、图标、颜色)保存在应用记录上,用 `apps.update` 修改;`name` 仍留在清单里,因为平台要求它。类型逐字段对应平台的清单结构(对照 [
|
|
376
|
+
清单描述应用能做什么。展示字段(名称、简介、图标、颜色)保存在应用记录上,用 `apps.update` 修改;`name` 仍留在清单里,因为平台要求它。类型逐字段对应平台的清单结构(对照 [清单](https://machinepulse-ai.github.io/karpoland-app-sdk/zh/reference/manifest.html) 检查),包括 `connect`(页面可以访问的源:https 或 wss,不带路径,`*.` 表示子域名,最多 10 个)和 `install_policy`(`anyone`,或 `developer`:只有应用的所有者和成员可以添加,且不能上架应用广场,也不能声明 open scope 的局 kind)。这是唯一的校验器;Go 和 Python SDK 只有类型,并引导你使用 `npm exec --no -- karpoland validate`。
|
|
377
377
|
|
|
378
378
|
**应用广场。** `listing: { square: true, category: "game" | "social" | "tool" | "fun" | "work", tagline (≤ 30), cover_color? }` 在线上版本这样声明后,让应用出现在应用广场上。带 `square: true` 的榜单也会出现在那里,但只有 `owner: "app"` 且 `visibility: "public"` 的榜单才能设置它。安装、房间和局的榜单永远不会出现在应用广场上。
|
|
379
379
|
|
|
@@ -537,6 +537,6 @@ npm test # unit tests, the spec/ name table and fixtures,
|
|
|
537
537
|
KARPO_IT=1 npm run test:integration # requires a local stack at KARPO_API (default http://127.0.0.1:8090) and people.json (KARPO_IT_PEOPLE)
|
|
538
538
|
```
|
|
539
539
|
|
|
540
|
-
`test/spec.test.ts` 检查客户端、应用、处理器上下文、测试工具包、页面客户端和开发者客户端的名字与
|
|
540
|
+
`test/spec.test.ts` 检查客户端、应用、处理器上下文、测试工具包、页面客户端和开发者客户端的名字与 `spec/api.json` 完全一致,检查 `spec/reasons.json`、`events.json` 和 `limits.json` 与代码一致,并(在编译时和运行时)检查 `Manifest` 类型恰好包含 `spec/manifest-fields.json` 中的字段,减去 SDK 略去的那些。`test/fixtures.test.ts` 运行 `spec/fixtures` 中的每个用例。`src/reasons.ts` 和 `spec/reasons.json` 由平台的注册表生成;不要手工编辑。
|
|
541
541
|
|
|
542
542
|
示例导入 `@karpoland/sdk`:在这里,测试配置和 `tsconfig.json` 把它映射到 `src/`;单独使用时,在示例目录里 `npm install` 会链接本目录(`file:../../../typescript`,需先 `npm run build`),`npm start` 在 Node ≥ 22.18 上运行它(类型剥离)。
|
package/dist/cli.js
CHANGED
|
@@ -203,7 +203,7 @@ function backoff(attempt, base, max) {
|
|
|
203
203
|
var enc = (s) => encodeURIComponent(String(s));
|
|
204
204
|
|
|
205
205
|
// src/version.ts
|
|
206
|
-
var SDK_VERSION = "1.0.
|
|
206
|
+
var SDK_VERSION = "1.0.1";
|
|
207
207
|
var USER_AGENT = `karpoland-sdk-ts/${SDK_VERSION}`;
|
|
208
208
|
|
|
209
209
|
// src/developer.ts
|
package/dist/index.cjs
CHANGED
|
@@ -434,7 +434,7 @@ function randomKey(prefix = "") {
|
|
|
434
434
|
var enc = (s) => encodeURIComponent(String(s));
|
|
435
435
|
|
|
436
436
|
// src/version.ts
|
|
437
|
-
var SDK_VERSION = "1.0.
|
|
437
|
+
var SDK_VERSION = "1.0.1";
|
|
438
438
|
var USER_AGENT = `karpoland-sdk-ts/${SDK_VERSION}`;
|
|
439
439
|
|
|
440
440
|
// src/client.ts
|