@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 CHANGED
@@ -1,4 +1,4 @@
1
- [English](README.md) | [简体中文](README.zh-CN.md) | 日本語
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.0 です。メソッド名は [`spec/api.json`](../spec/api.json) のもので、Go・Python の SDK と共通です。サーバー側のクライアントが送るリクエストにはすべて `User-Agent: karpoland-sdk-ts/1.0.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`](../examples/hello/typescript) は最小のアプリです。[`examples/dice/typescript`](../examples/dice/typescript) はこの SDK で作ったサイコロテーブルの完全なアプリです(セッション、タイマー、アプリメッセージ、ボード、ページ)。
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`(イベントごとに型付け、[`spec/events.json`](../spec/events.json))、`karpo`(配信のコンテキスト `MP-Karpo-Delivery` にあるもの)があります。
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` はプラットフォームが必須としているためマニフェストにも残っています。型はプラットフォームのマニフェスト構造にフィールド単位で対応しており([`spec/manifest-fields.json`](../spec/manifest-fields.json) と照合済み)、`connect`(ページが接続できるオリジン:https または wss、パスなし、サブドメインは `*.`、最大 10 個)や `install_policy`(`anyone`、または `developer`:アプリのオーナーとメンバーだけが追加でき、アプリ広場への掲載や open スコープのセッション kind の宣言はできません)も含みます。これが唯一のバリデーターです。Go と Python の SDK は型だけを持ち、`npm exec --no -- karpoland validate` を案内します。
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` は、クライアント、アプリ、ハンドラーのコンテキスト、テストキット、ページクライアント、開発者クライアントの名前が [`spec/api.json`](../spec/api.json) と完全に一致すること、`spec/reasons.json`、`events.json`、`limits.json` がコードと一致すること、そして(コンパイル時と実行時に)`Manifest` 型が [`spec/manifest-fields.json`](../spec/manifest-fields.json) のフィールドから SDK が省いたものを除いたものとちょうど一致することを確認します。`test/fixtures.test.ts` は [`spec/fixtures`](../spec/fixtures) のすべてのケースを実行します。`src/reasons.ts` と `spec/reasons.json` はプラットフォームのレジストリから生成されるので、手で編集しないでください。
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 | [简体中文](README.zh-CN.md) | [日本語](README.ja.md)
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.0. The method names are those of [`spec/api.json`](../spec/api.json), shared with the Go and Python SDKs. Every request the server-side clients send carries `User-Agent: karpoland-sdk-ts/1.0.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`](../examples/hello/typescript) is the smallest app; [`examples/dice/typescript`](../examples/dice/typescript) is the full dice table app (sessions, timers, app messages, boards, a page) on this SDK.
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, [`spec/events.json`](../spec/events.json)) and `karpo` (in the delivery's context, `MP-Karpo-Delivery`).
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 [`spec/manifest-fields.json`](../spec/manifest-fields.json)), 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`.
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 [`spec/api.json`](../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`](../spec/manifest-fields.json) minus the ones the SDK leaves out. `test/fixtures.test.ts` runs every case in [`spec/fixtures`](../spec/fixtures). `src/reasons.ts` and `spec/reasons.json` are generated from the platform's registry; don't edit them by hand.
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](README.md) | 简体中文 | [日本語](README.ja.md)
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.0。方法名与 [`spec/api.json`](../spec/api.json) 一致,和 Go、Python SDK 共用。服务端客户端发出的每个请求都带 `User-Agent: karpoland-sdk-ts/1.0.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`](../examples/hello/typescript) 是最小的应用;[`examples/dice/typescript`](../examples/dice/typescript) 是基于本 SDK 的完整骰子局应用(局、定时器、应用消息、榜单、页面)。
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`(按事件类型化,见 [`spec/events.json`](../spec/events.json))和 `karpo`(处于投递上下文,`MP-Karpo-Delivery`)。
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` 仍留在清单里,因为平台要求它。类型逐字段对应平台的清单结构(对照 [`spec/manifest-fields.json`](../spec/manifest-fields.json) 检查),包括 `connect`(页面可以访问的源:https 或 wss,不带路径,`*.` 表示子域名,最多 10 个)和 `install_policy`(`anyone`,或 `developer`:只有应用的所有者和成员可以添加,且不能上架应用广场,也不能声明 open scope 的局 kind)。这是唯一的校验器;Go 和 Python SDK 只有类型,并引导你使用 `npm exec --no -- karpoland validate`。
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` 检查客户端、应用、处理器上下文、测试工具包、页面客户端和开发者客户端的名字与 [`spec/api.json`](../spec/api.json) 完全一致,检查 `spec/reasons.json`、`events.json` 和 `limits.json` 与代码一致,并(在编译时和运行时)检查 `Manifest` 类型恰好包含 [`spec/manifest-fields.json`](../spec/manifest-fields.json) 中的字段,减去 SDK 略去的那些。`test/fixtures.test.ts` 运行 [`spec/fixtures`](../spec/fixtures) 中的每个用例。`src/reasons.ts` 和 `spec/reasons.json` 由平台的注册表生成;不要手工编辑。
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.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.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