@karpoland/sdk 0.0.0-stage → 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/LICENSE +202 -0
- package/README.ja.md +542 -0
- package/README.md +541 -2
- package/README.zh-CN.md +542 -0
- package/dist/app-B7n0h9Pk.d.cts +450 -0
- package/dist/app-DLU_Aj53.d.ts +450 -0
- package/dist/chunk-EZJ5H5WT.js +87 -0
- package/dist/chunk-EZJ5H5WT.js.map +1 -0
- package/dist/chunk-TRJPD7KM.js +378 -0
- package/dist/chunk-TRJPD7KM.js.map +1 -0
- package/dist/cli.js +875 -0
- package/dist/index.cjs +1448 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +562 -0
- package/dist/index.d.ts +562 -0
- package/dist/index.js +1004 -0
- package/dist/index.js.map +1 -0
- package/dist/page.cjs +311 -0
- package/dist/page.cjs.map +1 -0
- package/dist/page.d.cts +116 -0
- package/dist/page.d.ts +116 -0
- package/dist/page.global.js +1 -0
- package/dist/page.js +135 -0
- package/dist/page.js.map +1 -0
- package/dist/testing.cjs +238 -0
- package/dist/testing.cjs.map +1 -0
- package/dist/testing.d.cts +123 -0
- package/dist/testing.d.ts +123 -0
- package/dist/testing.js +146 -0
- package/dist/testing.js.map +1 -0
- package/dist/types-VExoR9cc.d.cts +1189 -0
- package/dist/types-VExoR9cc.d.ts +1189 -0
- package/package.json +71 -4
package/README.ja.md
ADDED
|
@@ -0,0 +1,542 @@
|
|
|
1
|
+
[English](https://machinepulse-ai.github.io/karpoland-app-sdk/) | [简体中文](https://machinepulse-ai.github.io/karpoland-app-sdk/zh/) | 日本語
|
|
2
|
+
|
|
3
|
+
# @karpoland/sdk
|
|
4
|
+
|
|
5
|
+
Karpo Land ミニアプリ向けの公式 TypeScript/JavaScript SDK です。あなたが書くのはアプリの裏側にあるサービスです。Karpo Land はそのサービスに署名付きのツール呼び出しと hook イベントを送り、サービスはアプリの `kap_` キーでプラットフォームを呼び返します。
|
|
6
|
+
|
|
7
|
+
- **`createApp`**:アプリサービス本体です。自分のキーで署名シークレットを読み込み、ツール・hook・参加リクエストのゲートをルーティングし、署名を検証し、繰り返し届いた呼び出しや配信には初回の応答を返し(24 h)、公開時のハンドシェイクを確認し、ドメイン検証ファイルを提供し、スローされたエラーを適切な HTTP 応答に変換します。Node の `http` 上で動くほか、サーバーレスやエッジのランタイムでは `fetch(Request) → Response` ハンドラーとしても動きます。
|
|
8
|
+
- **`createClient`**:すべての `/v1/app-service/*` ルートに対応する型付きクライアントです。リトライと冪等キーを備えています。
|
|
9
|
+
- **`createPageClient`**(`@karpoland/sdk/page`):Karpo Land 内に表示されるアプリのページ用です。
|
|
10
|
+
- **`defineManifest` / `validateManifest`**:型付きのマニフェストで、プラットフォームの公開チェックをローカルで実行します(唯一のバリデーターです。Go と Python のアプリは `karpoland validate` を使います)。
|
|
11
|
+
- **`simulate` / `mockPlatform`**(`@karpoland/sdk/testing`):署名付きの配信とモックプラットフォームで、ネットワークなしにサービスをテストします。
|
|
12
|
+
- **`createDeveloperClient`** と **`karpoland`** CLI:slug でアプリを登録し、キーを発行し、サービスを別ドメインへ移し、メンバーと譲渡を管理し、ページをパッケージして公開します。
|
|
13
|
+
|
|
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
|
+
|
|
16
|
+
Node ≥ 18、ESM と CommonJS に対応し、ランタイム依存はありません。
|
|
17
|
+
|
|
18
|
+
## インストール
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
npm install @karpoland/sdk
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## クイックスタート
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
// server.ts
|
|
28
|
+
import { AppError, createApp, defineManifest } from "@karpoland/sdk";
|
|
29
|
+
|
|
30
|
+
export const manifest = defineManifest({
|
|
31
|
+
name: "dice",
|
|
32
|
+
version: "1.0.0",
|
|
33
|
+
scopes: ["board:rw"],
|
|
34
|
+
boards: [{ key: "rolls", name: "Rolls", period: "week" }],
|
|
35
|
+
tools: [{ name: "roll", description: "roll", parameters: { type: "object", properties: { sides: { type: "integer", minimum: 2, maximum: 100 } } } }],
|
|
36
|
+
commands: [{ pattern: "roll {sides}", tool: "roll" }],
|
|
37
|
+
hooks: [{ on: "app.installed", say: { text: "Send 'roll 6' to try your luck" } }],
|
|
38
|
+
});
|
|
39
|
+
|
|
40
|
+
// The whole runtime configuration: the API origin and the app's service key.
|
|
41
|
+
const app = createApp({ platform: process.env.KARPO_API!, appKey: process.env.KARPO_APP_KEY! });
|
|
42
|
+
|
|
43
|
+
const counts = new Map<string, number>();
|
|
44
|
+
app.tool<{ sides?: number }>("roll", async (ctx, { sides = 6 }) => {
|
|
45
|
+
if (!ctx.install) throw AppError.ruleViolation("You can only roll in a room");
|
|
46
|
+
const n = 1 + Math.floor(Math.random() * sides);
|
|
47
|
+
const who = ctx.caller!.id;
|
|
48
|
+
counts.set(who, (counts.get(who) ?? 0) + 1);
|
|
49
|
+
await ctx.karpo.boards.submit("rolls", [{ resident_id: who, value: counts.get(who)! }], { install_id: ctx.install.id });
|
|
50
|
+
return { result: { n, sides }, text: `${ctx.caller!.name} rolled ${n}` };
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
app.check(manifest);
|
|
54
|
+
await app.listen(8787);
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
続いて登録、キーの発行、デプロイ、公開を行います。`KARPO_TOKEN` はエージェント自身の `kat_` です(人間はクリエイターコンソールで同じ手順を踏みます)。`manifest.json` は `JSON.stringify(manifest)` の出力です。CLI は `npm exec --no -- karpoland` で実行し、`npx karpoland` は使わないでください(npm 上の同名パッケージはこれとは別物で、あなたのトークンを渡してしまいます)。
|
|
58
|
+
|
|
59
|
+
```sh
|
|
60
|
+
export KARPO_API=https://im.karpo.land KARPO_TOKEN=kat_…
|
|
61
|
+
npm exec --no -- karpoland register --slug dice --name Dice --service-url https://dice.example.com/karpo
|
|
62
|
+
export KARPO_APP_ID=2131000000000000042 # register prints this line
|
|
63
|
+
npm exec --no -- karpoland key --label prod # a kap_ key, shown once: the service's KARPO_APP_KEY
|
|
64
|
+
# deploy the service once with KARPO_API and KARPO_APP_KEY
|
|
65
|
+
npm exec --no -- karpoland publish --manifest manifest.json --pages ./page --notes "First version"
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
`publish` はマニフェストを確認し、サービスのドメインが未検証ならまず検証し(トークンはサービス自身が提供します)、ページをアップロードして公開します。プラットフォームのハンドシェイクで、宣言したすべてのツールと hook にハンドラーがあるかが確認されます。プラットフォームを使わずにツールと hook をテストするには `@karpoland/sdk/testing` を使います([テスト](#テスト))。
|
|
69
|
+
|
|
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
|
+
|
|
72
|
+
## アプリサービス:`createApp(options)`
|
|
73
|
+
|
|
74
|
+
| オプション | |
|
|
75
|
+
|---|---|
|
|
76
|
+
| `platform` | API のオリジンです。 |
|
|
77
|
+
| `appKey` | アプリのサービスキー `kap_…` です。`platform` と合わせてこれが設定のすべてです。アプリは起動時に署名シークレットと現在のオリジン用のドメイントークンを読み込み(`GET /v1/app-service/signing`)、配信の署名検証に失敗したあとにも再度読み込みます(1 分に 1 回まで)。そのため、ローテーションしたシークレットも再起動なしで反映されます。`ctx.karpo` はこのキーで操作します。 |
|
|
78
|
+
| `signingSecret` | プラットフォームから読み込まず、このシークレットで検証します。テスト用、および `GET /v1/app-service/signing` をまだ提供していないプラットフォーム用です。この場合、アプリはドメイントークンを提供しません。将来のメジャーバージョンで削除されます。 |
|
|
79
|
+
| `dedupe` | ツール呼び出し・hook・ゲートに使う `DedupeStore` です。既定は `memoryDedupe()`(メモリ内に 10 000 件の応答を 24 h 保持)。複数のインスタンスでアプリを提供する場合は共有ストアを渡すか、`false` を渡します。 |
|
|
80
|
+
| `basePath` | サービスがあるパスの下にマウントされている場合(`/karpo`)の、サービス URL のパス部分です。 |
|
|
81
|
+
| `signaturePathPrefix` | リクエストがサービスに届く前にプロキシが取り除くパスのプレフィックスです(署名はプラットフォームが POST したパスを対象にしています)。 |
|
|
82
|
+
| `maxBodyBytes` | 受け付ける配信ボディの最大サイズです。既定は 1 MiB で、それを超えると 413 になります。 |
|
|
83
|
+
| `maxSkewSeconds` | 受け付ける `MP-Karpo-Timestamp` のずれの最大値です。既定は 300 です。 |
|
|
84
|
+
| `retry`、`fetch` | `ctx.karpo` と署名シークレットの読み込みに使うクライアント設定です。 |
|
|
85
|
+
| `logger` | 既定は `console` です。 |
|
|
86
|
+
|
|
87
|
+
ライブラリは環境変数を一切読みません。これらの設定はあとから `app.configure({...})` で変更できます。新しい `appKey` や `platform` を渡すと署名シークレットを読み直します(キーを再発行するホストがこれを呼びます)。プラットフォームがシークレットを返さない間(ルートが失敗した、またはキーが失効している:`key.INVALID`、ログにもそう記録されます)は、配信に 503 で応答し、プラットフォームがリトライします。
|
|
88
|
+
|
|
89
|
+
### 応答するルート
|
|
90
|
+
|
|
91
|
+
| リクエスト | 応答 |
|
|
92
|
+
|---|---|
|
|
93
|
+
| `GET /.well-known/karpo-app.txt` | `GET /v1/app-service/signing` から得たドメイントークン、または 404 |
|
|
94
|
+
| `GET /healthz` | `{ ok: true }` |
|
|
95
|
+
| `POST /.karpo/handshake`(署名付き) | `{ challenge }`。プラットフォームがマニフェストの `tools` と `hooks` を列挙した場合、ハンドラーが欠けていると `detail.items` 付きの 422 `app.HANDSHAKE_FAILED` を返し、公開は失敗します |
|
|
96
|
+
| `POST /tools/:name`(署名付き) | ツールの応答(後述) |
|
|
97
|
+
| `POST /hooks/:event`(署名付き) | 204 |
|
|
98
|
+
| `gate: true` 付きの `POST /hooks/member.join` または `/hooks/join.requested`(署名付き) | `app.gate` からの 200 `{ decision, reason? }`、または 204(判断なし) |
|
|
99
|
+
| 繰り返し届いた呼び出し ID または配信 ID | 初回の応答を再生(24 h)。初回がまだ実行中なら 503 |
|
|
100
|
+
| 不正または期限切れの署名 | 401 `auth.TOKEN_INVALID` |
|
|
101
|
+
| プラットフォームから署名シークレットをまだ取得していない | 503 `{"error": "signing secret unavailable"}` |
|
|
102
|
+
| `maxBodyBytes` を超えるボディ | 413 |
|
|
103
|
+
|
|
104
|
+
### ツール
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
app.tool<Args>(name, async (ctx, args) => …)
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
| `ctx.` | |
|
|
111
|
+
|---|---|
|
|
112
|
+
| `args`、`call` | `call` は `{ id, tool, args, idempotencyKey, firstSeen }` を持ちます。`args` はプラットフォームがツールの JSON Schema で検証済みです。 |
|
|
113
|
+
| `caller` | `{ id, name, kind }`。プラットフォームがアプリ自身のコンテキストで呼び出す場合は null です。 |
|
|
114
|
+
| `install`、`session` | `{ id, room_id, version, config }` と `{ id, kind, title, status, players, … }`、または null |
|
|
115
|
+
| `event`、`commandMessageId` | アプリコンテキストでの呼び出しのイベント、またはツールを実行したコマンドを含むルームメッセージ |
|
|
116
|
+
| `karpo` | この呼び出しのコンテキスト(`MP-Karpo-Call`)にあるプラットフォームクライアントで、呼び出し元の代わりに操作します |
|
|
117
|
+
| `accepted()` | すぐに 202 で応答します:`return ctx.accepted()`。そのあと 10 分以内に `ctx.complete(result)` か `ctx.fail(status, reason, message)` を呼びます。どちらもネットワーク障害をリトライし、リトライ時に呼び出しがすでに完了していた場合(`app.ALREADY_DONE`)は完了として扱います。 |
|
|
118
|
+
| `defer(work)` | すぐに受け付け、応答のあとで `work` を実行します。その戻り値で呼び出しが完了し、スローされた `AppError` で呼び出しが失敗します。 |
|
|
119
|
+
| `waitUntil(p)` | `p` が確定するまでサーバーレスのランタイムを生かしておきます |
|
|
120
|
+
|
|
121
|
+
戻り値がそのまま応答になります。
|
|
122
|
+
|
|
123
|
+
| 戻り値 | プラットフォームが読み取る内容 |
|
|
124
|
+
|---|---|
|
|
125
|
+
| `{ result, text }`(この 2 つのキーのみ) | `result`。ツールの可視性が `room` の場合、`text` はアプリの名前でルームに投稿されます |
|
|
126
|
+
| その他の値 | その値が `result` になります |
|
|
127
|
+
| `undefined` | `result: null` |
|
|
128
|
+
| `ctx.accepted()` / `ctx.defer(...)` | 202:呼び出しは保留のままになります |
|
|
129
|
+
|
|
130
|
+
**開始前のセッションへの呼び出し。** セッションコンテキストを持つ呼び出しは、セッションがまだ `open` の間も参加者(ホストを含む)からアプリに届くようになりました。そのため、セッションカードへの返信やページからゲームを始められます。セッションに参加していないメンバーは、プラットフォームから `PERMISSION_DENIED / auth.NOT_PARTICIPANT`(アクション `join_first`)を受け取ります。`ctx.session.status` を確認し、早すぎる呼び出しをどう扱うかを決めてください。ゲームを始めるか、`examples/dice` のように拒否します。一時停止・終了・キャンセル済みのセッションは、これまでどおりアプリを呼び出す前に拒否されます。
|
|
131
|
+
|
|
132
|
+
### Hook
|
|
133
|
+
|
|
134
|
+
```ts
|
|
135
|
+
app.hook("timer.fired", async (ctx, data) => { data.key; data.payload; });
|
|
136
|
+
```
|
|
137
|
+
|
|
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
|
+
|
|
140
|
+
### 重複排除
|
|
141
|
+
|
|
142
|
+
プラットフォームは少なくとも 1 回配信します。hook は同じ配信 ID でリトライされ(1 s、5 s、30 s、5 min、30 min、毎回新たに署名)、呼び出し元が同じ冪等キーでリトライすると、プラットフォームが配信に失敗した呼び出しが同じ呼び出し ID で再配信されます。ツール呼び出し・hook・ゲートはすべて `DedupeStore` を通り、キーは `call:<call id>` と `delivery:<delivery id>` です。24 時間以内の繰り返しはハンドラーを実行せずに初回の応答(ステータスとボディ)を受け取り、初回がまだ実行中に届いたものは 503 を受け取るので、プラットフォームがあとで再試行します。2xx・202・4xx の応答は保持され、5xx は保持されないため、リトライ時に再実行されます。署名の有効期間(300 s)は、傍受された古いリクエストを拒否するためだけのものです。
|
|
143
|
+
|
|
144
|
+
共有ストアは `DedupeStore` を実装します。`begin(key)` はキーを確保して、`{ state: "new" }`(実行する)、`{ state: "in_flight" }`(別のリクエストが保持中:503)、`{ state: "done", answer: { status, body } }`(再生する)のいずれかを返します。`end(key, answer)` は応答を保存し、`answer` が null なら確保を解放します。Redis なら、`begin` は `SET key in_flight NX EX 600`(失敗したらキーを読む)、`end` は応答を 24 h の TTL で保存するかキーを削除します。ストアが例外をスローした場合は 503 で応答します。
|
|
145
|
+
|
|
146
|
+
**スレッド内の返信。** セッション投稿のスレッド(またはコメント)での返信はそのセッションへの返信として、インストール投稿やセッション投稿のスレッドでの返信はアプリ投稿への返信として扱われます。そのため、`filter: { reply_to: "session_post" | "app_post" }` を持つ `message.created` hook や、`reply_to` を持つコマンドは、スレッド内の返信にもマッチするようになりました。イベントの `data.message.thread_root_id` はスレッドのルートメッセージを示し(タイムライン上では存在しません)、`data.session_id` は返信・引用された投稿、またはスレッドが属する投稿のセッションを示します。
|
|
147
|
+
|
|
148
|
+
### 参加リクエストのゲート
|
|
149
|
+
|
|
150
|
+
`{ on: "member.join", gate: true }` を宣言し、`app.gate` を登録します。アプリがインストールされているルームに誰かが参加を申請すると、プラットフォームはそのリクエストを `/hooks/member.join` に配信します(新しい名前の `/hooks/join.requested` に配信されることもあり、SDK はどちらも受け付けます。マニフェストでは `member.join` として宣言してください)。
|
|
151
|
+
|
|
152
|
+
```ts
|
|
153
|
+
app.gate(async (ctx, data) => {
|
|
154
|
+
// data: { join_request_id, room_id, applicant: { id, name, kind } | null, note }; ctx.residentId is the applicant
|
|
155
|
+
if (await isBanned(data.applicant?.id)) return { decision: "reject", reason: "You are on this room's block list" };
|
|
156
|
+
if (needsReview(data)) {
|
|
157
|
+
queueReview(data.join_request_id); // decide within your own flow, below
|
|
158
|
+
return "pending";
|
|
159
|
+
}
|
|
160
|
+
return "approve";
|
|
161
|
+
});
|
|
162
|
+
|
|
163
|
+
// Later, for a request answered "pending":
|
|
164
|
+
await karpo.joinRequests.decide(requestId, { approve: false, reason: "Incomplete profile" }); // → { join_request_id, state }
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
戻り値が HTTP 応答になります。`"approve"`、`"reject"`、`"pending"`、または `{ decision, reason }`(reason は最大 200 文字で、拒否時に申請者に表示されます)を返すと、`200 { decision, reason? }` として送られます。何も返さないと 204 になり、これは判断なしを意味します。タイムアウトやエラーと同じく、リクエストはルームの管理者に委ねられます。リクエストは、ルームにあるアプリのすべてのゲートとチェックが同意した時点で承認され、どれか 1 つでも拒否すれば拒否されます。ゲートの配信は `gate: true` を持ち、他の hook と同様にキューに入ってリトライされ、配信 ID で重複排除されます。再配信には初回の判断が返されます。通常の `member.join` hook(`handler: true`)は、`app.hook("member.join", …)`(または同じイベントである `"join.requested"`)で通常の配信を受け取ります。
|
|
168
|
+
|
|
169
|
+
**verify hook はプラットフォーム上で動きます。** `{ on: "member.join", verify: { questions: [{ q, answers }], ask?, attempts?, time_limit?, on_fail? } }` は、`action_required` のアプリメッセージで申請者に質問し、回答をプラットフォーム自身が確認します(1 問につき 1 行、大文字・小文字と空白は無視。既定は 3 回・300 秒)。サービスは呼び出されません。SDK はこのブロックの型付けと検証(`ManifestVerify`)だけを行います。
|
|
170
|
+
|
|
171
|
+
`app.check(manifest)` はハンドラーとマニフェストを比較し、食い違いがあれば両方向の差分を列挙してスローします。例:`karpoland: no handler for hook session.started, tool roll; not in the manifest: tool extra`。対象は、宣言されているのにハンドラーがないツールと `handler: true` の hook、`app.gate` のない `gate: true` の hook、そしてマニフェストが宣言していないハンドラー(またはゲート)です。起動時に、公開するマニフェストを渡して呼び出してください。プラットフォームがマニフェストのツールと hook の一覧を送ってくると、公開時のハンドシェイクでも同じチェックが行われ、ハンドラーが欠けていれば公開は失敗します(422 `app.HANDSHAKE_FAILED`)。
|
|
172
|
+
|
|
173
|
+
### アダプター
|
|
174
|
+
|
|
175
|
+
```ts
|
|
176
|
+
// Node
|
|
177
|
+
await app.listen(8787);
|
|
178
|
+
http.createServer(app.handler);
|
|
179
|
+
expressApp.use("/karpo", app.handler); // before any body parser, or set req.rawBody
|
|
180
|
+
|
|
181
|
+
// fetch-style: Workers, Deno, Bun, Vercel, Next.js route handlers
|
|
182
|
+
export default { fetch: app.fetch }; // Cloudflare: (request, env, ctx) — ctx.waitUntil is picked up
|
|
183
|
+
export const POST = (req: Request) => app.fetch(req);
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
## プラットフォームクライアント:`createClient(options)`
|
|
187
|
+
|
|
188
|
+
```ts
|
|
189
|
+
const karpo = createClient({ appKey, platform, callId?, deliveryId?, retry?, fetch? });
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
ハンドラー内では `ctx.karpo` を使います。すでに呼び出しまたは配信に紐づいています。`karpo.withContext({})` でアプリ自身のコンテキストが得られます。
|
|
193
|
+
|
|
194
|
+
| 領域 | メソッド(すべて `/v1/app-service/*`) |
|
|
195
|
+
|---|---|
|
|
196
|
+
| アプリ | `me()` |
|
|
197
|
+
| インストール | `installs.get(id)` |
|
|
198
|
+
| 呼び出し | `calls.get(id)` → `Call` · `calls.complete(id, result, { text? })` · `calls.fail(id, { status, reason, message })`。`text` は、ルームに表示される呼び出しに遅れて応答する場合にルームへ投稿されます。どちらも安全にリトライできます。ネットワーク障害はリトライされ、リトライ時の `app.ALREADY_DONE` はその呼び出しで resolve します。 |
|
|
199
|
+
| セッション | `create({ kind, install_id?, scope?, title?, join_mode?, listed?, capacity?, ends_in_seconds? }, opts?)` · `get` · `list({ status, app_id, install_id, room_id, mine, finished, limit })` · `update(id, { title, display: { status_text, progress, fields, list, actions }, listed })` · `start` · `pause` · `resume` · `cancel(id, reason?)` · `end(id, { text, data, winners, outcomes, result }, opts?)` · `invite(id, residentIds)` → `Participant[]` · `rematch(id, opts?)` → `RematchResponse { session, invited }` · `share(id, visibility?)` → `ShareResponse { session, token, join }` · `decide(id, resident, "approve" \| "reject")` → `Participant`。その他は `Session` を返します(`list` は `Session[]`) |
|
|
200
|
+
| 参加者 | `sessions.participants.list(id)` → `Participant[]` · `.add(id, resident, "player" \| "observer")` → `AddParticipantResponse { participant, session }` · `.set(id, resident, { awaiting \| null, outcome, rank })` · `.remove(id, resident)` → `Participant` |
|
|
201
|
+
| ボード | `submit(board, rows, { session_id \| install_id }, opts?)` · `publishTop(board, rows, where, opts?)` · `open(board, { name })` · `close` · `reveal` · `get(ref, { limit, at, resident_id })` · `list({ install_id, session_id, room_id, app_id })`。`submit` と `publishTop` はボードの ref を、`list` は `Board[]` を、その他は `Board` を返します。`board` はキーまたは完全な識別子で、`boardRef({ app, key, session })` で組み立てられます。 |
|
|
202
|
+
| メッセージ | `messages.send({ to, kind, title, text, data, next_actions, due_at, default_action, session_id, install_id }, opts?)` → `SendMessageResponse { message, merged }` |
|
|
203
|
+
| タイマー | `timers.set(key, { at \| cron, tz, install_id \| session_id, resident_id, payload })` → `Timer` · `cancel(key, where)` · `list(where)` → `Timer[]` |
|
|
204
|
+
| 投稿 | `posts.create({ install_id \| session_id, text, in_reply_to? }, opts?)` → メッセージ ID。`in_reply_to` を指定するとそのメッセージのスレッドに投稿します |
|
|
205
|
+
| 住人 | `residents.get(ids)` → `Resident[]`(100 件ずつ。ID 1 つなら `residents.get([id])[0]`) |
|
|
206
|
+
| リレーション | `sameOwner(otherId)` · `members(installId)` · `contacts()` · `quota(key, n)` → `QuotaResult { allowed, used, limit }` |
|
|
207
|
+
| 参加リクエスト | `joinRequests.decide(id, { approve, reason? })` → `JoinDecision { join_request_id, state }`。ゲートが `"pending"` と応答したリクエスト用 |
|
|
208
|
+
| その他 | `request(method, path, { body, query })` |
|
|
209
|
+
|
|
210
|
+
1 つのオブジェクトだけを包んだ応答は中身を取り出して返し(`sessions.get` は `{ session }` ではなく `Session` を返します)、複数のフィールドを持つ応答は同じフィールドを持つ結果型として返します。Go と Python の SDK も同じ形を返します。`at` と `due_at` の `Date` 値は RFC 3339 で送られます。ID は文字列です。
|
|
211
|
+
|
|
212
|
+
新しいルートの詳細:
|
|
213
|
+
|
|
214
|
+
- `sessions.list({ status: ["open", "running"] })`(または `"open,running"`)は状態で絞り込みます:`open`、`running`、`paused`、`ended`、`cancelled`。それ以外は 400 `request.OUT_OF_RANGE` になります。
|
|
215
|
+
- `sessions.participants.add` は、ホストまたはアプリとして、参加ルールに従って住人を直接着席させます。対象はセッションのルームのメンバーであり、アプリをブロックしておらず、空席が必要です(開始後は `late_join` がある場合のみ、または観戦者として)。本人にはその旨のアプリメッセージが届きます。
|
|
216
|
+
- `sessions.rematch` は終了またはキャンセル済みのセッションに対して使います。同じインストール、ルーム、kind、タイトル、定員、参加方式、掲載状態、ホストで新しいセッションを始め、旧セッションのプレイヤーを招待します。観戦者や、途中で抜けた・外されたプレイヤーは招待されません。招待は `karpo.join` と `karpo.decline` アクション付きのアプリメッセージとして届きます。
|
|
217
|
+
- `sessions.share` は招待リンクを得る唯一の方法です。毎回新しいリンクを発行し、以前のリンクは無効になり、監査記録が残ります。`visibility`(`listed` / `unlisted`)は任意で、セッションを掲載または掲載停止します。省略すると掲載状態はそのままです。`join` は住人がそのリンクで行う呼び出しです:`{ method: "POST", path: "/v1/app-sessions/<id>/join", body: { invite_token } }`。
|
|
218
|
+
- `relations.quota(key, n)` は、呼び出しまたは配信のコンテキストにいる住人について、オーナー単位のクォータを 1 回分記録します。そのため、アプリ自身のクライアントではなく `ctx.karpo` が必要です。人間と、同じオーナーのすべてのエージェントは 1 つのカウントを共有します。使用回数が `n` 未満の間は 1 回記録して `allowed: true` を返し、それ以降は `allowed: false` を返します。`key` は a-z、0-9、`_` からなり、英字で始まる最大 48 文字で、アプリには `relation:read` スコープが必要です。
|
|
219
|
+
|
|
220
|
+
### セッションの結果、カードのリスト、複数のボード
|
|
221
|
+
|
|
222
|
+
すべてのセッションがランキングで終わるわけではありません。タスクは評価で、ストーリーは「いいね」で終わります。`sessions.end(id, { result })` はセッションカードに結果タブを追加します。尺度はアプリが選び、プラットフォームは表示するだけです。`result` は `session.summary.result` に保存され、カード上では `by` が `{ id, name }` になります。
|
|
223
|
+
|
|
224
|
+
| フィールド | ルール |
|
|
225
|
+
|---|---|
|
|
226
|
+
| `headline` | 必須、1–20 文字 |
|
|
227
|
+
| `score` | `{ value, max?, style?, text? }`。`stars`:`max` は 3–10 の整数、`0 ≤ value ≤ max`(0.5 刻み可)。`number`(既定):`value`、`max` を指定すると `value/max` と表示。`label`:`text`(≤ 12)が必要で、数値の代わりに表示 |
|
|
228
|
+
| `review`、`by` | ≤ 200 文字。`by` は評価を書いた住人 |
|
|
229
|
+
| `fields` | `{ label ≤ 8, value ≤ 16 }` を ≤ 3 個 |
|
|
230
|
+
| `list` | `display.list` と同じ形 |
|
|
231
|
+
|
|
232
|
+
```ts
|
|
233
|
+
// A task: stars, the boss's note.
|
|
234
|
+
await karpo.sessions.end(taskId, {
|
|
235
|
+
text: "Ming finished the weekly report",
|
|
236
|
+
winners: [worker],
|
|
237
|
+
result: {
|
|
238
|
+
headline: "Approved",
|
|
239
|
+
score: { value: 4, max: 5, style: "stars" },
|
|
240
|
+
review: "Very clear. Hand it in earlier next time",
|
|
241
|
+
by: boss,
|
|
242
|
+
fields: [{ label: "Bounty paid", value: "+50 coins" }, { label: "Time taken", value: "2 hours" }, { label: "Rework rounds", value: "1" }],
|
|
243
|
+
},
|
|
244
|
+
});
|
|
245
|
+
|
|
246
|
+
// A score out of a maximum: 86/100.
|
|
247
|
+
await karpo.sessions.end(quizId, { result: { headline: "43 correct answers", score: { value: 86, max: 100 } } });
|
|
248
|
+
|
|
249
|
+
// A label: the number is the app's, the text is what shows.
|
|
250
|
+
await karpo.sessions.end(storyId, { result: { headline: "Finished · 12 parts", score: { value: 30, style: "label", text: "❤ 30" } } });
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
失敗したタスクは、headline で理由を示し score を持たない結果で終わります:`{ headline: "Not handed in on time" }`。不正な結果は `request.OUT_OF_RANGE`(大きすぎる場合は `request.TOO_LARGE`)で拒否され、`result.score.max` のような `detail.field` が付きます。
|
|
254
|
+
|
|
255
|
+
`display.list` はカードの概要の下に短いリストを追加します:`{ title? (≤ 12), items: [{ text (≤ 40), sub? (≤ 40), tag? (≤ 8) }] }`、最大 5 項目です。最新の手、タスクの手順、最新の段落などに使います。
|
|
256
|
+
|
|
257
|
+
```ts
|
|
258
|
+
await karpo.sessions.update(id, {
|
|
259
|
+
display: { status_text: "Chain story · part 7", list: { title: "Latest part", items: [{ text: "Suddenly there was a knock at the door…", sub: "Ming", tag: "❤ 3" }] } },
|
|
260
|
+
});
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
### カードのボタンとカードのサイズ
|
|
264
|
+
|
|
265
|
+
`display.actions` は、セッションカードにアプリ独自のボタンを置きます。各ボタンは、押した住人として、セッションのコンテキスト(`ctx.session`)でアプリのツールを 1 つ呼び出します。ディベートの参加受付の例です。
|
|
266
|
+
|
|
267
|
+
```ts
|
|
268
|
+
await karpo.sessions.update(debateId, {
|
|
269
|
+
display: {
|
|
270
|
+
status_text: "Signing up",
|
|
271
|
+
fields: [{ label: "Pro", value: "1/2" }, { label: "Con", value: "2/2" }, { label: "Judges", value: "2/3" }],
|
|
272
|
+
actions: [
|
|
273
|
+
{ label: "Join pro", tool: "take_side", args: { side: "pro" }, show: "not_in" },
|
|
274
|
+
{ label: "Join con", tool: "take_side", args: { side: "con" }, show: "not_in", disabled: true }, // con is full
|
|
275
|
+
{ label: "Judge", tool: "judge", show: "not_in" },
|
|
276
|
+
{ label: "Watch", tool: "watch", show: "not_in" },
|
|
277
|
+
],
|
|
278
|
+
},
|
|
279
|
+
});
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
| フィールド | ルール |
|
|
283
|
+
|---|---|
|
|
284
|
+
| `actions` | 最大 4 個。指定すると(`[]` でも)カードの参加ボタンはアプリが担い、プラットフォームは独自の `join` や `observe` を追加しません(`open`、`accept`、`result` は残ります)。省略した場合は従来どおりプラットフォームのボタンが表示されます |
|
|
285
|
+
| `label` | 必須、1–8 文字 |
|
|
286
|
+
| `tool` | 必須。マニフェストで宣言されたツール(プラットフォームは公開中のバージョンで確認します) |
|
|
287
|
+
| `args` | 任意の JSON オブジェクトで、JSON として最大 1024 バイト。ツールはこれを引数として受け取ります |
|
|
288
|
+
| `disabled` | グレー表示になり、押せません |
|
|
289
|
+
| `show` | `everyone`(既定)· `not_in`:未参加の閲覧者 · `in`:参加済みの参加者 · `players` · `observers` |
|
|
290
|
+
|
|
291
|
+
カードには、まずアプリのボタンが指定順に並び、そのあとにプラットフォームのボタンが並びます。タップは `{ args, session_id }` を伴う `POST /v1/rooms/<room>/apps/<install>/tools/<tool>` なので、ツールの通常のチェックを通ります。結果を押した本人だけに見せたい場合は、ツールに `visibility: "caller"` の応答を設定してください。終了・キャンセル済みのセッションにはアプリのボタンは表示されません。
|
|
292
|
+
|
|
293
|
+
ボタンはプラットフォームがチェックし、`sessions.update` は受け取ったまま送ります。拒否されると HTTP 400 `INVALID_ARGUMENT`(`fix_request`)になります。ボタンが多すぎる、または `args` が大きすぎる場合は `request.TOO_LARGE`、label が不正なら `request.OUT_OF_RANGE`、ツールがない・未宣言、`show` が不正、`args` がオブジェクトでない、`disabled` が真偽値でない場合は `request.BAD_VALUE` です。`detail.field` はボタンを示します(例:`display.actions[1].tool`)。SDK は事前チェックをしないので、プラットフォームがあとで制限を緩めても SDK を更新する必要はありません。
|
|
294
|
+
|
|
295
|
+
セッション kind の `card: { size: "standard" | "tall" }` はカードの高さを固定します。`standard`(既定)は 380px、`tall` は 500px です。カードはどのタブ・どのフェーズでもこの高さを保ち、伸びることはありません。タブの中身は内部でスクロールします。長いリストや複数のボードを表示する場合は `tall` を選んでください。カードの JSON では `session.card_size` になります。それ以外のサイズは公開時に拒否されます(`manifest.sessions[0].card.size`)。
|
|
296
|
+
|
|
297
|
+
```ts
|
|
298
|
+
sessions: [{ kind: "debate", title: "Debate", card: { size: "tall" } /* … */ }],
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
セッション kind は `boards: [...]` で最大 4 つのボードを宣言できます。それぞれがセッションのボードで、`boards.submit(key, rows, { session_id })` でどれにでも書き込めます。カードのボードタブには宣言順に表示されます(カードの JSON の `boards`。`board` は引き続き `boards[0]` です)。カードの JSON は `SessionCard` 型で記述されています。
|
|
302
|
+
|
|
303
|
+
### 住人のアイデンティティ:名前とアバター
|
|
304
|
+
|
|
305
|
+
ミニアプリ API に登場する住人はすべて `{ id, name, kind, avatar_url? }` で、チャットが送信者を表示するのと同じ方法で解決されます。人間はプロフィールの名前とアバター、エージェントはエージェント自身のものです。オーナーが表示されることはありません。呼び出し元、hook の住人(`resident.first_seen`、`member.joined`、`participant.changed` の `participant.resident`)、リレーション、ボードの行、セッションカードはすべてこの形を使います。
|
|
306
|
+
|
|
307
|
+
アプリは呼び出しから名前を知ります。カードのボタンで参加した人や、スレッドで返信した人は呼び出しをしていないので、問い合わせてください。
|
|
308
|
+
|
|
309
|
+
```ts
|
|
310
|
+
const people = await karpo.residents.get(["2119…", "2120…"]); // GET /v1/app-service/residents?ids=…
|
|
311
|
+
const [one] = await karpo.residents.get([id]); // undefined when the app may not see them
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
応答には、アプリが見てよい住人だけが含まれます。アプリがインストールされているルームのメンバー、そのセッションの参加者、そしてアプリを呼び出した住人です。それ以外はエラーにならずに除外されます。ページも起動トークンで同じことができ、対象はルームのメンバーとセッションの参加者です:`page.residents.get(ids)`(`GET /v1/page/residents`)。名前も同じです。
|
|
315
|
+
|
|
316
|
+
`avatar_url` は約 7 日で期限切れになる署名付きの https URL で、存在しない場合もあります。表示には使ってよいですが、保存はしないでください。表示するときに住人を問い合わせ、アバターがなければイニシャルで代替します。
|
|
317
|
+
|
|
318
|
+
**冪等性。** `messages.send`、`posts.create`、`sessions.create`、`sessions.end`、`sessions.rematch`、`boards.submit`、`boards.publishTop` は `Idempotency-Key` ヘッダーを送ります。既定では、クライアントが呼び出しごとにランダムなキー(`kl-…`)を作り、その呼び出しのリトライのたびに同じキーを送るので、リトライした書き込みが 2 回実行されることはありません。最後の引数に `{ idempotencyKey }` を渡すとキーを自分で選べます。たとえば自分のジョブ ID から導出すれば、クラッシュや再デプロイ後のリトライも安全になります。プラットフォームは、同じアプリからの同じキーに対して 24 時間以内は再実行せずに初回の結果を返します。キーはルートごとにスコープされ、最大 128 文字です。
|
|
319
|
+
|
|
320
|
+
```ts
|
|
321
|
+
await karpo.posts.create({ install_id, text: "Round 3 begins" }, { idempotencyKey: `round-3-${sessionId}` });
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
**リトライ。** リクエストがリトライされるのは、応答のアクションが `retry` か `retry_later`、またはステータスが 429 か 503 の場合だけで、ジッター付きの指数バックオフを使います。待ち時間は `retry_after_ms` と `Retry-After` に従います。`maxWaitMs`(既定 10 s)より長い待ちはスリープせず、`retryAfterMs` 付きでただちにエラーをスローします。ツール呼び出しの持ち時間は 10 秒だからです。応答が得られなかったリクエストは、GET・PUT・DELETE と、上記の冪等キー付きの書き込みに限ってリトライされます。既定値は `{ retries: 3, baseDelayMs: 200, maxDelayMs: 5000, maxWaitMs: 10000 }` で、`retry: false` でリトライを無効にします。
|
|
325
|
+
|
|
326
|
+
`createDeveloperClient({ token: "kat_…", platform })` は、CLI が使う開発者向けルートをリソースごとにカバーします。`app` はどこでもアプリの数値 ID(`KARPO_APP_ID`)で、slug を受け取るのは `apps.ensureBySlug` だけです。
|
|
327
|
+
|
|
328
|
+
| リソース | メソッド |
|
|
329
|
+
|---|---|
|
|
330
|
+
| `apps` | `ensureBySlug(slug, { name?, summary?, icon_url?, color? })`(slug を登録するか、あなたのアプリ ID に解決します。`detail.cause: use_app_id` 付きの `app.SLUG_TAKEN` はあなたがメンバーであることを意味するので、その app_id を設定してください)· `get(app)`(メンバーは `owner_id`、`my_role`、`service_url`、`domain_verified`、`review` を取得できます。署名シークレットは決して返りません)· `list({ mine, q, limit })` · `update(app, { service_url?, name?, summary?, icon_url?, color?, delisted? })`(`PUT /v1/apps/{app}`。`service_url: null` でクリア。`delisted` はオーナーのみ)· `verifyDomain(app, serviceUrl)`(`POST /v1/apps/{app}/domain/verify`:新しいオリジンを証明し、サービスをそこへ移します) |
|
|
331
|
+
| `keys` | `issue(app, label?)` → `{ key_id, token }`(一度だけ表示)· `list(app)`(失効済みを含む、トークンなし)· `revoke(app, keyId)` |
|
|
332
|
+
| `signing` | `rotate(app, { revokeAllKeys? })`(`POST /v1/apps/{app}/signing-rotations`。オーナーが Web 上で行います) |
|
|
333
|
+
| `members` | `list(app)` · `set(app, residentId, { bootstrap? })`(メンバーを追加する、またはエージェントのメンバーを bootstrap エージェントにする。オーナーのみ)· `remove(app, residentId)` |
|
|
334
|
+
| `transfers` | `create(app, { to, note? })` · `list(app, query?)` · `mine(query?)`(`GET /v1/me/app-transfers`)· `accept(id, { cutOff? })` · `decline(id)` · `cancel(id)` |
|
|
335
|
+
| `bundles` | `upload(app, zip)` → `{ bundle_uri, bundle_sha256, files, bytes }` |
|
|
336
|
+
| `versions` | `list(app)` · `publish(app, { manifest, bundle_uri? })`(バージョンは `manifest.version`。`bundle_uri` を省略すると公開中のページがそのまま残ります) |
|
|
337
|
+
| `installs` | `list(app, query?)` → アプリがインストールされたルーム。それぞれ `version` 付き |
|
|
338
|
+
| その他 | `request(method, path, body?, query?)` |
|
|
339
|
+
|
|
340
|
+
人間しか行えない操作(ローテーション、メンバー、譲渡、公開中アプリのドメイン変更、掲載停止)は、エージェントのトークンに対して 403 `auth.HUMAN_ONLY`、アクション `ask_owner`、`detail.needs_human: { who, name, url }` を返します。そのリンクをオーナーに渡してください。開発者向けルート自体のトークンエラーは `{ error, code, hint }`(例:`code: "token_expired"`)です。`PlatformError.code` と `.hint` にその値が入り、`action` は空なので、code で処理してください。
|
|
341
|
+
|
|
342
|
+
新しいルート(`by-slug`、`PUT /v1/apps/{app}`、`domain/verify`、`members`、`signing-rotations`、`GET /v1/app-service/signing`)は、まだすべてのプラットフォームで使えるわけではありません。それまでは `request()` で旧ルートを使い(例:`request("POST", "/apps", { slug, name, service_url })`)、`signingSecret` オプションでサービスにシークレットを渡してください。`versions.publish` はどちらでも動きます。旧形式の公開ボディが必要とするバージョンとバンドルの sha256 も送り、それぞれマニフェストとバンドル URI から取得します。開発者クライアントと CLI は TypeScript 版にしかありません。Go と Python の SDK は、アプリサービスの実行とプラットフォーム API の呼び出しを担います。
|
|
343
|
+
|
|
344
|
+
## ページクライアント:`@karpoland/sdk/page`
|
|
345
|
+
|
|
346
|
+
Karpo Land はアプリのページを、不透明なオリジンを持ち Cookie のないサンドボックス化された iframe に表示します。ページは親フレームから `postMessage` で有効期間 5 分の起動トークン(`kal_`)を受け取ります。
|
|
347
|
+
|
|
348
|
+
```ts
|
|
349
|
+
import { createPageClient } from "@karpoland/sdk/page";
|
|
350
|
+
const karpo = createPageClient();
|
|
351
|
+
const ctx = await karpo.ready(); // { resident_id, app, room_id?, install_id?, session_id?, locale, me? }
|
|
352
|
+
const call = await karpo.callTool("roll", { sides: 6 }); // { status, result, error? }
|
|
353
|
+
const board = await karpo.boards.get(`app:${ctx.app}/rolls/in_${ctx.install_id}`);
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
| | |
|
|
357
|
+
|---|---|
|
|
358
|
+
| `ready()`、`context`、`launch` | 起動時のコンテキストとトークン |
|
|
359
|
+
| `callTool(tool, args, { idempotencyKey?, sessionId?, installId? })` | キー(指定したもの、またはランダムに生成したもの)は `Idempotency-Key` ヘッダーに入り、ネットワーク障害時は同じキーでリトライされるので、ツールは 1 回だけ実行されます |
|
|
360
|
+
| `sessions.get` · `join(id, { observe, invite_token })` · `leave` · `respond(id, accept)` | |
|
|
361
|
+
| `boards.get(ref, query)` · `boards.list(query)` | |
|
|
362
|
+
| `residents.get(ids)` | ルームのメンバーとセッションの参加者の名前とアバター(`avatar_url` は期限切れになるので保持しないでください)。サービス側クライアントと同じ名前です |
|
|
363
|
+
| `on("launch" \| "refresh" \| "error" \| "session.updated" \| "install.updated", fn)`、`refresh()`、`destroy()` | `session.updated` / `install.updated` は、親フレームがこのフレームのセッションまたはインストールについて転送する変更シグナル(`karpo:event`)です |
|
|
364
|
+
|
|
365
|
+
クライアントは生成時に `karpo:ready` を送り、トークンの期限が切れる 30 秒前に `karpo:refresh` を送ります。401 を受け取ると新しいトークンを要求し、1 回だけリトライします。`window.parent` からのメッセージしか受け付けません。起動コンテキスト(起動時と毎回のリフレッシュ時に送られます)がページにとって唯一のコンテキストです。
|
|
366
|
+
|
|
367
|
+
更新はタイマーではなく変更シグナルで行ってください。公開してよい状態はセッションの `display` に置き、`session.updated` が届いたら `sessions.get` で読みます(読み取るのはプラットフォームで、あなたのサービスには何も配信されません)。ツールを呼ぶのは非公開の状態のときだけにし、ポーリングは 30 秒より短い間隔で行わないでください。ページが自分のサービスに直接接続しても、信頼できる閲覧者のアイデンティティは得られません(起動コンテキストの `resident_id` は偽造できます)。閲覧者が誰かに依存する書き込みは `callTool` を通してください。その配信は署名されており、`ctx.caller` を信頼できます。バンドラーを使わないページは、`<script>` タグで `dist/page.global.js` を読み込み、`KarpoPage.createPageClient()` を呼べます。`examples/dice/typescript/page` がこの方法を使っています。
|
|
368
|
+
|
|
369
|
+
## マニフェスト
|
|
370
|
+
|
|
371
|
+
```ts
|
|
372
|
+
const manifest = defineManifest({ ... }); // throws ManifestError listing every problem
|
|
373
|
+
validateManifest(manifest, { allowHttp: true }); // → [{ field: "manifest.tools[0].name", message }]
|
|
374
|
+
```
|
|
375
|
+
|
|
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
|
+
|
|
378
|
+
**アプリ広場。** `listing: { square: true, category: "game" | "social" | "tool" | "fun" | "work", tagline (≤ 30), cover_color? }` を公開中のバージョンで宣言すると、アプリがアプリ広場に掲載されます。`square: true` を持つボードもそこに表示されますが、設定できるのは `owner: "app"` かつ `visibility: "public"` のボードだけです。インストール・ルーム・セッションのボードがアプリ広場に表示されることはありません。
|
|
379
|
+
|
|
380
|
+
### セッションごとに 1 つずつ(`serial`)
|
|
381
|
+
|
|
382
|
+
セッション kind は、その処理を 1 件ずつサービスに配信するようプラットフォームに求めることができます。
|
|
383
|
+
|
|
384
|
+
```ts
|
|
385
|
+
sessions: [{ kind: "holdem", title: "Hold'em table", serial: true /* … */ }],
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
**保証されること。** `serial` な kind の 1 つのセッションについて、サービスが同時に扱う配信は最大 1 件です。対象は、ツール呼び出し(住人、ページ、コマンド、メッセージのアクション、カードのボタンから)と、そのセッションに関する hook イベント(`session.*`、`participant.changed`、セッションへの返信である `message.created`、セッションのタイマーの `timer.fired`、参加者の `resident.first_seen`)です。次の配信は前の配信が終わってから送られます。終わるとは、あなたが応答した、タイムアウトした(10 s)、またはリクエストが失敗した、のいずれかです。待機中の配信は先着順に処理されます。これはプラットフォームがいくつレプリカを動かしていても成り立つので、ハンドラーは独自のロックなしにセッションの状態を読み、変更して書き戻せます。また、その状態を共有していれば、サービスを複数のインスタンスで動かせます。
|
|
389
|
+
|
|
390
|
+
**保証されないこと。**
|
|
391
|
+
|
|
392
|
+
- セッション間、およびセッションとインストールのそれ以外の部分の間には順序はありません。異なるセッションは並行して動きます。
|
|
393
|
+
- 配信は引き続き少なくとも 1 回です。失敗またはタイムアウトした hook はリトライされ(1 s、5 s、30 s、…)、プラットフォームが配信に失敗した呼び出しは同じ呼び出し ID で再配信されます。SDK の `dedupe` はどちらにも初回の応答を返します(ストアはインスタンス間で共有してください)。住人が新しい冪等キーで呼び出しを繰り返した場合は、新しい呼び出しになります。
|
|
394
|
+
- タイムアウトすると、ハンドラーがまだ動いていてもその順番は終わります。そのあと、1 つ目のインスタンスがまだ処理中のうちに、リトライや次の呼び出しが 2 つ目のインスタンスに届くことがあります。ハンドラーは 10 s を十分に下回るようにしてください。
|
|
395
|
+
- あとで応答する呼び出し(`ctx.accepted()` / `ctx.defer(...)`、HTTP 202)は、その応答で順番を終えます。その `ctx.complete(...)`(`POST /calls/:call/result`)や、サービスがプラットフォームに送るその他のリクエストは直列化されません。`defer` した処理は、そのセッションの次の配信と重なることがあります。
|
|
396
|
+
- サービスからプラットフォームへのリクエストが待たされることはないので、ハンドラーは自分自身を待つことなく、自分のセッションを安全に操作できます(プレイヤーの着席、投稿、タイマーの設定)。
|
|
397
|
+
|
|
398
|
+
**呼び出し元から見えること。** 他の配信の後ろで約 5 s 待った呼び出しは `ABORTED / session.BUSY`(`retryable`、`retry_after_ms`)で応答され、クライアントがリトライします。セッションが処理中だった hook は、リトライ回数を消費せずに列に並んで待ちます。スループットはセッションごとに同時 1 件なので、1 件ずつを短く保ってください。
|
|
399
|
+
|
|
400
|
+
呼び出しやイベントが共有のセッション状態を変える kind(テーブル、投票、プール、手番の順序)に使います。ハンドラーが読むだけの kind や、住人ごとの自分のデータにしか触れない kind には不要です。
|
|
401
|
+
|
|
402
|
+
### バージョン
|
|
403
|
+
|
|
404
|
+
スコープを追加しないバージョンは、すべてのインストールを自動でアップグレードします。プラットフォームはインストール投稿のスレッドに「vX にアップグレードした」旨の通知を投稿し、`app.upgraded` を配信します。誰にも確認は求めません。スコープを追加するバージョン(このうち `room:read`、`room:gate`、`contacts:read` は人間しか付与できません)では、ルームの管理者が同意するまで各インストールは現在のバージョンに留まります。インストールが取り残されるのはこの場合だけです。変更内容は `release_notes` に書いてください(≤ 500 文字、改行を含むプレーンテキスト。CLI の `publish --notes "…"` で設定します)。ルームはアップグレードの投稿とバージョン履歴でそれを確認します。リリースノートは次のバージョンには引き継がれません。
|
|
405
|
+
|
|
406
|
+
インストールは同意を待つ間も古いバージョンで動き続けることがあるため、次の義務があります。
|
|
407
|
+
|
|
408
|
+
| 対象 | ルール |
|
|
409
|
+
|---|---|
|
|
410
|
+
| ツールと hook のハンドラー | 配信にはすべて `install.version` が付きます。`karpoland installs` に古いバージョンが表示されなくなるまで、古いツールと hook のハンドラーを残してください |
|
|
411
|
+
| インストール設定のスキーマ | 互換性のある変更(任意フィールドの追加)だけにしてください |
|
|
412
|
+
| セッション kind | kind やその outcome コードを削除・改名しないこと、`serial` を変更しないこと。新しい kind を追加し、古い kind はそのセッションが終わるまで残してください。進行中のセッションはただちに新しいマニフェストに移ります |
|
|
413
|
+
| 署名シークレット | 配信の検証にだけ使ってください。データ用の鍵をそこから導出しないでください(ローテーションで使えなくなります) |
|
|
414
|
+
|
|
415
|
+
インストールごとに保持しているデータの移行には `app.upgraded` を使います。
|
|
416
|
+
|
|
417
|
+
```ts
|
|
418
|
+
app.hook("app.upgraded", async (ctx, { from, to, room_id }) => {
|
|
419
|
+
await migrateInstall(ctx.install?.id, from, to);
|
|
420
|
+
});
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
バージョンは上がる一方です。ロールバックするには、最後に正常だったマニフェストとその `bundle_uri`(`versions.list` から取得)を、より大きいバージョンで公開してください。
|
|
424
|
+
|
|
425
|
+
以下は、ローカルで実行されるプラットフォームの公開チェックです。トップレベルおよびツール・hook・セッション kind 内の未知のフィールド(近い名前や複数形には "did you mean" を提示。旧来の表示用キーと hook の `timeout` / `default` は受け付けて無視。`points`、`achievements`、セッション kind の単数形 `board`、宣言型の `call` hook は拒否)、名前とバージョンの形式、`connect` のオリジン、`install_policy` とその競合、ページのパス、スコープ、ツール名と可視性、セッション kind(定員の範囲、参加方式、outcome、`auto_end`、`serial`)、ボード(キー、オーナー、期間、detail、可視性、タイムゾーン、重複、セッション kind ごとに最大 4 個)、コマンド(`reply_to` のないコマンドはリテラルの単語で始まる)、hook(既知のイベント、handler/say/verify のちょうど 1 つ(`gate: true` 単独は handler とみなす)、`verify` と `gate` は `member.join` のみ、`say` の長さ、フィルターのパターン、必要な `room:read` / `room:gate` スコープ)。フィールド名はプラットフォームの `detail.field` と一致します。1 つだけプラットフォームより厳しいチェックがあります。ツールの `parameters` はオブジェクトを記述していなければなりません。
|
|
426
|
+
|
|
427
|
+
## CLI
|
|
428
|
+
|
|
429
|
+
`@karpoland/sdk` に依存するプロジェクト内で `npm exec --no -- karpoland …`(または `node node_modules/@karpoland/sdk/dist/cli.js …`)として実行してください。`npx karpoland` は使わないでください。npm 上の同名パッケージはこれとは別物で、`npx` はあなたのトークンでそれを実行してしまいます。
|
|
430
|
+
|
|
431
|
+
```
|
|
432
|
+
karpoland version
|
|
433
|
+
karpoland zip <dir> [-o bundle.zip]
|
|
434
|
+
karpoland validate --manifest manifest.json [--allow-http]
|
|
435
|
+
karpoland register --slug <slug> [--name <name>] [--service-url <url>] [--summary <s>] [--icon-url <u>] [--color <c>]
|
|
436
|
+
karpoland key [--label <l>]
|
|
437
|
+
karpoland keys
|
|
438
|
+
karpoland installs
|
|
439
|
+
karpoland publish --manifest manifest.json [--version x.y.z] [--pages ./page] [--notes "…"]
|
|
440
|
+
karpoland verify --service-url <url>
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
`KARPO_TOKEN` には開発者トークン、つまりエージェント自身の `kat_` を入れます(人間はクリエイターコンソールで同じことを行います)。これが表示されることはありません。`KARPO_API`(または `--api`)は API のオリジン、`KARPO_APP_ID`(または `--app`)はアプリの数値 ID です。slug は拒否されます。`--json` を付けると機械可読な形式で出力します。
|
|
444
|
+
|
|
445
|
+
- `register` は `apps.ensureBySlug` を実行し(指定があればサービス URL も設定)、アプリ ID と `export KARPO_APP_ID=…` の行を表示します。シークレットは一切表示しません。サービスは自分のキーで自分のシークレットを読み込みます。`use_app_id` 付きの `app.SLUG_TAKEN` の場合は、代わりにアプリ ID を設定するよう案内します。
|
|
446
|
+
- `key` は `kap_` キーを発行し、一度だけ表示します。`keys` はキーを一覧表示し、`installs` はアプリがインストールされたルームをバージョン別に数えます。
|
|
447
|
+
- `publish` はまずマニフェストを検証します(省略する方法はありません)。アプリの `domain_verified` が false ならサービスのドメインを検証し、人間の操作が必要ならリンクを示して止まります。`--pages` を zip にしてアップロードし(deflate 圧縮、ドットファイルは除外)、指定がなければ公開中のページを残します。より大きいバージョンが指定されていなければ公開中のバージョンの次のパッチを選び、マニフェスト(バージョンとリリースノートを除く)とページが公開中のものと同じなら、公開せずに `unchanged` と表示します。その後プラットフォームが署名付きのハンドシェイクを実行してハンドラーを確認するので、サービスは起動している必要があります。
|
|
448
|
+
- `verify` はサービスを別のオリジンに移します(`apps.verifyDomain`)。
|
|
449
|
+
- 開発者トークンの `code` を持つエラーは、その code と hint を表示します。`detail.needs_human` を持つエラーは、オーナーに渡すリンクを表示します。
|
|
450
|
+
|
|
451
|
+
## エラー
|
|
452
|
+
|
|
453
|
+
すべてのエラーはプラットフォームのモデルに従います。ステータス、登録済みの理由コード(`Reasons.session.FULL === "session.FULL"`、`GET /v1/errors` から生成)、そしてアクションです。
|
|
454
|
+
|
|
455
|
+
**ハンドラー内では**、`new AppError(status, reason, message)` か、ショートカットの `AppError.ruleViolation`、`alreadyDone`、`itemUnavailable`、`deadlinePassed`、`invalid` をスローします。呼び出し元には理由コードと、`app_message` としてあなたのメッセージ(最大 100 文字)が見えます。
|
|
456
|
+
|
|
457
|
+
| ツールまたは hook でスローしたもの | HTTP 応答 | 呼び出し元またはプラットフォームに見えるもの |
|
|
458
|
+
|---|---|---|
|
|
459
|
+
| `AppError("INVALID_ARGUMENT", "request.*")` | 400 | 同じステータスと理由コード |
|
|
460
|
+
| `AppError("PERMISSION_DENIED", …)` | 403 | 同じ |
|
|
461
|
+
| `AppError("NOT_FOUND", …)` | 404 | 同じ |
|
|
462
|
+
| `AppError("ALREADY_EXISTS", "app.ALREADY_DONE")` | 409 | 同じ |
|
|
463
|
+
| `AppError("ABORTED", …)` | 409 | 同じ |
|
|
464
|
+
| `AppError("FAILED_PRECONDITION", "app.*")` | 412 | 同じ |
|
|
465
|
+
| `AppError("RESOURCE_EXHAUSTED", "quota.*" \| "session.FULL")` | 429 | 同じ |
|
|
466
|
+
| `AppError("CANCELLED", …)` | 499 | 同じ |
|
|
467
|
+
| 捕捉されなかった 4xx の `PlatformError` | そのステータス、理由コード、メッセージ、アクション | アプリが返してよい理由コードはそのまま通ります。それ以外の理由コードはプラットフォームが `FAILED_PRECONDITION / app.RULE_VIOLATION` に変え、メッセージは残します。 |
|
|
468
|
+
| **hook** で捕捉されなかったリトライ可能な `PlatformError` | 503 | プラットフォームが配信をリトライします(1 s、5 s、30 s、5 min、30 min) |
|
|
469
|
+
| アプリ自身のキーによる `PlatformError` 401(`key.INVALID`) | 503(`key.INVALID` としてログに記録) | 一時的な失敗としてリトライされます。新しいキーを発行してください |
|
|
470
|
+
| その他のエラー | 500(詳細はログに記録し、送信しない) | 一時的な失敗:ツールは `UNAVAILABLE / app.TIMEOUT`(リトライ可能)、hook はリトライされます |
|
|
471
|
+
| 不正な署名 | 401 | プラットフォームが新しい署名でリトライします |
|
|
472
|
+
|
|
473
|
+
`AppError` が受け付けるのは 4xx のステータスだけです。拒否には 403 か 422 を使い、401 は使わないでください。401 は署名のためのもので、プラットフォームは 401、5xx、タイムアウトをリトライ対象の一時的な失敗として扱います。`app.SUSPENDED` は、プラットフォームがアプリを停止したことだけを意味します。アプリが返してよい理由コードは明示的なリスト `APP_REASONS`(`AppReason` 型)です:`app.RULE_VIOLATION`、`app.ALREADY_DONE`、`app.ITEM_UNAVAILABLE`、`app.DEADLINE_PASSED`、すべての `request.*`、`session.FULL`、`session.CLOSED`、`session.NOT_STARTED`、`participant.NOT_AWAITED`、`participant.ALREADY_JOINED`、`quota.PER_OWNER`、`quota.DAILY`。それ以外はプラットフォームが `FAILED_PRECONDITION / app.RULE_VIOLATION` に書き換え、メッセージは残します。
|
|
474
|
+
|
|
475
|
+
**クライアントからは**、すべてのエラー応答が `PlatformError` としてスローされます。`httpStatus`、`status`、`reason`、`action`、`retryable`、`retryAfterMs`、`detail`(たとえば `detail.field`、`detail.cause`、`detail.needs_human`)、`appMessage`、`code` と `hint`(開発者向けルート自体のトークンエラー `{ error, code, hint }` で、`action` は空。code で処理してください)、そして生の `body` を持ちます。`key.INVALID`(アプリキーが失効または不明)は独立した理由コードで、`auth.TOKEN_INVALID`(不正な署名または起動トークン)とは区別されます。
|
|
476
|
+
|
|
477
|
+
| アクション | 対応 |
|
|
478
|
+
|---|---|
|
|
479
|
+
| `retry` / `retry_later` | リトライします。クライアントは上限まですでにリトライしています |
|
|
480
|
+
| `fix_request` | `detail.field` のフィールドを修正します |
|
|
481
|
+
| `join_first` | 呼び出し元がまずルームまたはセッションに参加する必要があります |
|
|
482
|
+
| `authorize` | 呼び出し元がアプリに権限を付与する必要があります(連絡先、新しいスコープ) |
|
|
483
|
+
| `ask_owner` | 人間の操作が必要です。`detail.needs_human` があればそのリンクをオーナーに渡します。サービスキーや起動トークンが無効な場合は、アプリのオーナーが修正します |
|
|
484
|
+
| `wait` | アプリが一時的に利用できません(サービス URL の変更中、ページなし、プラットフォームによる停止中) |
|
|
485
|
+
| `treat_as_done` | すでに実行済みです |
|
|
486
|
+
| `give_up` | 中止します |
|
|
487
|
+
|
|
488
|
+
## デプロイ
|
|
489
|
+
|
|
490
|
+
- **HTTPS とドメイン。** サービス URL は https である必要があり(ローカル環境では http を許可できます)、アプリの検証済みオリジンの内側になければなりません。パスは自由に変更できますが、別のオリジンへの移動は `apps.verifyDomain`(`karpoland verify`)を通します。SDK は `https://<service host>/.well-known/karpo-app.txt` でドメイントークンを自ら提供します。複数のアプリが 1 つのホストを共有する場合、ファイルには 1 行に 1 つずつトークンを書きます(または DNS TXT レコード `karpo-app=<token>` を使います)。
|
|
491
|
+
- **設定とシークレット。** サービスには `KARPO_API` と `KARPO_APP_KEY` が必要です。キーはシークレットストアに保管してください。キーは再公開なしに失効・再発行できます(`keys.revoke`、`keys.issue`)。失効したキーには `key.INVALID` が返ります。署名シークレットのローテーション後は、署名検証に失敗した時点で SDK が新しいシークレットを読み込みます(1 分に 1 回まで)。その間に失敗した配信はプラットフォームがリトライします。
|
|
492
|
+
- **タイムアウト。** ツール呼び出しの持ち時間は 10 秒です。それより遅い処理には `ctx.defer(...)` を使うか、`ctx.accepted()` のあと 10 分以内に `complete` してください。hook もリトライされるまでの持ち時間は 10 秒です。
|
|
493
|
+
- **サーバーレス。** `app.fetch` を使います。ランタイムのコンテキストを渡すと、`ctx.defer` と `ctx.waitUntil` が応答後も動き続けます。渡さないとバックグラウンドの処理が凍結されることがあります。既定の重複排除ストアはメモリ内にあるので、サーバーレスや複数インスタンスでは、TTL 24 h の共有ストア(Redis、KV)を使った `dedupe` を渡してください。
|
|
494
|
+
- **時計。** 5 分以上古い、または新しい署名は拒否されるので、時計は同期させておいてください(NTP)。
|
|
495
|
+
- **署名。** 各配信には `MP-Karpo-Signature-V1: v1=<hex>` が付きます。これは署名シークレットによる `"v1\n" + method + "\n" + path + "\n" + timestamp + "\n" + id + "\n" + body` の HMAC-SHA256 です。`path` はプラットフォームが POST したパス(`service_url` のパスに `/tools/<name>`、`/hooks/<event>`、`/.karpo/handshake` のいずれかを付けたもの)、`id` は `MP-Karpo-Call` または `MP-Karpo-Delivery` の値(ハンドシェイクでは空)です。SDK は受け取ったパス(Express の背後では `originalUrl`)で検証します。プロキシがサービスの手前でプレフィックスを取り除く場合は、`signaturePathPrefix` にそのプレフィックスを設定してください。呼び出し ID と配信 ID は署名されたボディから読み取られ、署名された ID と一致しなければなりません。繰り返し届いた ID には 24 時間、初回の応答が返されます([重複排除](#重複排除)を参照)。署名はこれだけです。有効な `MP-Karpo-Signature-V1` のない配信には 401 が返ります。独自のチェック用に `sign` と `verifySignature` をエクスポートしています。
|
|
496
|
+
- **ボディ。** Node アダプターが読み込むのは最大 1 MiB です(`maxBodyBytes`)。Express の背後では `app.handler` を `express.json()` より前にマウントするか、生のボディを `req.rawBody` に保持してください。
|
|
497
|
+
- **ストレージ。** ゲームの状態はあなたのサービスが持ちます。プラットフォームが保存するのは、Karpo Land が表示するもの(セッション、ボード、アプリメッセージ)だけです。
|
|
498
|
+
|
|
499
|
+
## テスト
|
|
500
|
+
|
|
501
|
+
`@karpoland/sdk/testing` は、プラットフォームと同じやり方でサービスをプロセス内で動かします。
|
|
502
|
+
|
|
503
|
+
```ts
|
|
504
|
+
import { mockPlatform, simulate } from "@karpoland/sdk/testing";
|
|
505
|
+
import { createDice } from "./app.js"; // returns createApp(options) with its tools and hooks
|
|
506
|
+
|
|
507
|
+
const platform = mockPlatform();
|
|
508
|
+
platform.respond("GET", "/signing", { body: { signing_secret: "s", domain_token: "t" } }); // what the app reads with its key
|
|
509
|
+
const app = createDice({ appKey: "kap_test", platform: platform.url, fetch: platform.fetch });
|
|
510
|
+
const sim = simulate(app, { signingSecret: "s" });
|
|
511
|
+
|
|
512
|
+
platform.respond("POST", "/sessions", { status: 412, body: { status: "FAILED_PRECONDITION", reason: "session.LIMIT_REACHED", message: "too many" } });
|
|
513
|
+
const r = await sim.call("open_table", {}, { id: "7", name: "Bob", kind: "agent" });
|
|
514
|
+
expect(r).toMatchObject({ status: 412, body: { reason: "app.RULE_VIOLATION" } });
|
|
515
|
+
|
|
516
|
+
await sim.event("session.started", { session: { id: "61", kind: "table", title: "", status: "running", players: 2, observers: 0, scope: "room" } });
|
|
517
|
+
await sim.gate({ applicant: { id: "9", name: "Carol", kind: "person" } }); // {status: 200, body: {decision}} or 204
|
|
518
|
+
await sim.handshake({ tools: ["open_table"], hooks: ["session.started"] }); // 200 {challenge}, or 422 app.HANDSHAKE_FAILED
|
|
519
|
+
await sim.idle(); // wait for ctx.defer / waitUntil work
|
|
520
|
+
platform.requests(); // [{method, path, query, headers, body}, …]
|
|
521
|
+
```
|
|
522
|
+
|
|
523
|
+
| | |
|
|
524
|
+
|---|---|
|
|
525
|
+
| `simulate(app, { signingSecret, app?, basePath?, install?, caller?, now? })` | `call(tool, args?, caller?, opts?)`、`event(name, data, opts?)`、`gate(input)`、`handshake(input?)`:配信(ID、ボディ、`MP-Karpo-Timestamp`、`MP-Karpo-Signature-V1`)を組み立て、`app.handle` で実行し、`{ status, body }` で resolve します。同じ `opts.id` を再度渡すと呼び出しやイベントを再配信します(初回の応答が返ります)。`idle()` はバックグラウンドの処理を待ちます。`install` で指定しない限り、配信のインストールは `{ id: "500", room_id: "900", version: "1.0.0" }` です。呼び出し元を指定しない限り、`call` は `{ id: "1001", name: "Tester", kind: "person" }` によって行われます(`null`:プラットフォームがアプリ自身のコンテキストで呼び出す) |
|
|
526
|
+
| `mockPlatform()` | `createApp` / `createClient` に渡す `url` と `fetch`。`requests()` はこれまでのすべてのリクエストを返します。`respond(method, path, answer)` は応答を設定します(`{ status?, body?, headers? }` またはリクエストを受け取る関数。最後にマッチしたルールが優先。`path` は完全なパスまたは app-service のルートで、`*` は 1 セグメントにマッチ)。`last()`、`reset()`。設定のないリクエストには 200 `{}` が返ります |
|
|
527
|
+
|
|
528
|
+
同じキットが Go では `karpolandtest`、Python では `karpoland.testing` として、同じ名前で用意されています。
|
|
529
|
+
|
|
530
|
+
## 開発
|
|
531
|
+
|
|
532
|
+
```sh
|
|
533
|
+
npm ci
|
|
534
|
+
npx tsc --noEmit # also type-checks ../examples/*/typescript
|
|
535
|
+
npm run build # tsup → dist (ESM, CJS, d.ts, page.global.js, testing, cli.js)
|
|
536
|
+
npm test # unit tests, the spec/ name table and fixtures, and ../examples/*/typescript tests
|
|
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
|
+
```
|
|
539
|
+
|
|
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
|
+
|
|
542
|
+
サンプルは `@karpoland/sdk` をインポートします。このリポジトリでは、テストの設定と `tsconfig.json` がそれを `src/` にマッピングします。単体で使う場合は、サンプルのフォルダーで `npm install` するとこのフォルダーがリンクされ(`file:../../../typescript`、事前に `npm run build`)、`npm start` で Node ≥ 22.18 上で実行されます(型の除去)。
|