@karpoland/sdk 0.0.0-stage → 1.0.0
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 +70 -4
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,562 @@
|
|
|
1
|
+
export { A as ACCEPTED, a as Accepted, b as App, c as AppOptions, C as CallInfo, d as CheckedManifest, e as Client, f as ClientOptions, g as CoreRequest, h as CoreResponse, D as DEDUPE_TTL_SECONDS, i as DecideAction, j as DedupeAnswer, k as DedupeClaim, l as DedupeStore, G as GateAnswer, m as GateContext, n as GateHandler, H as HookContext, o as HookHandler, L as Logger, M as MAX_BODY_BYTES, p as MAX_RESIDENT_IDS, q as MemoryDedupeOptions, S as SIGNING_REREAD_SECONDS, r as Server, T as ToolContext, s as ToolHandler, t as ToolReply, u as createApp, v as createClient, w as memoryDedupe } from './app-B7n0h9Pk.cjs';
|
|
2
|
+
import { J as Json, I as Id, A as AppRecord, M as MeResponse, B as BundleUploaded, R as RetryOptions, F as FetchLike } from './types-VExoR9cc.cjs';
|
|
3
|
+
export { a as APP_REASONS, b as Action, c as AddParticipantResponse, d as AppError, e as AppErrorStatus, f as AppMessage, g as AppReason, h as AppReview, i as AppTool, j as Awaiting, k as Board, l as BoardRow, m as BoardWhere, C as Call, n as CallError, o as Capacity, p as CapacityChoice, q as CardBoard, r as CardBoardRow, s as CardButton, t as CardButtonShow, u as CardSessionResult, v as ClientContext, w as CompleteOptions, x as CreateSessionInput, D as DecideJoinRequestInput, y as DisplayField, z as DisplayList, E as DisplayListItem, G as EndSessionInput, H as ErrorBody, K as ErrorDetail, L as GateDecision, N as GetBoardQuery, O as HandshakeDelivery, P as HookDelivery, Q as HookEvent, S as HookEvents, T as Install, U as InstallRef, V as InstallUpdate, W as InstalledEvent, X as JoinDecision, Y as JoinMode, Z as ListBoardsQuery, _ as ListSessionsQuery, $ as ListingReview, a0 as MAX_IDEMPOTENCY_KEY, a1 as MemberEvent, a2 as MemberJoinEvent, a3 as MessageEvent, a4 as MessageKind, a5 as MessageRepliedEvent, a6 as NextAction, a7 as OpenBoardInput, a8 as Outcome, a9 as Participant, aa as ParticipantEvent, ab as ParticipantRole, ac as PlatformError, ad as PostInput, ae as QuotaResult, af as Reason, ag as Reasons, ah as RelationKind, ai as Relative, aj as RematchResponse, ak as RequestOptions, al as Resident, am as ResidentEvent, an as ResultScore, ao as RoomMessage, ap as STATUSES, aq as ScoreRow, ar as SendMessageInput, as as SendMessageResponse, at as Session, au as SessionCard, av as SessionDisplay, aw as SessionEvent, ax as SessionRef, ay as SessionResult, az as SessionScope, aA as SessionStatus, aB as SessionSummary, aC as SetParticipantInput, aD as SetTimerInput, aE as ShareResponse, aF as ShareVisibility, aG as Status, aH as Timer, aI as TimerEvent, aJ as TimerWhere, aK as ToolCallDelivery, aL as UpdateSessionInput, aM as UpgradedEvent, aN as WriteOptions, aO as isPlatformError, aP as isReason, aQ as shouldRetry, aR as statusOfHttp } from './types-VExoR9cc.cjs';
|
|
4
|
+
|
|
5
|
+
type Scope = "room:post" | "session:rw" | "board:rw" | "message:send" | "relation:read" | "contacts:read" | "timer:rw"
|
|
6
|
+
/** Every room message: message.created without filter.reply_to. Not in DMs. */
|
|
7
|
+
| "room:read"
|
|
8
|
+
/** Join requests: member.join hooks (gate, verify or handler). Not in DMs. */
|
|
9
|
+
| "room:gate";
|
|
10
|
+
declare const SCOPES: readonly Scope[];
|
|
11
|
+
declare const HOOK_EVENTS: readonly ["app.installed", "app.uninstalled", "resident.first_seen", "message.created", "member.joined", "member.left", "member.join", "session.created", "session.started", "session.paused", "session.resumed", "session.ended", "session.cancelled", "participant.changed", "timer.fired", "app.message.replied", "app.upgraded"];
|
|
12
|
+
type ManifestHookEvent = (typeof HOOK_EVENTS)[number];
|
|
13
|
+
declare const BASE_OUTCOMES: readonly ["none", "won", "lost", "tied", "ranked", "quit", "timed_out", "disqualified"];
|
|
14
|
+
type BaseOutcome = (typeof BASE_OUTCOMES)[number];
|
|
15
|
+
interface ManifestPage {
|
|
16
|
+
name: string;
|
|
17
|
+
/** Starts with "/". */
|
|
18
|
+
path: string;
|
|
19
|
+
icon?: string;
|
|
20
|
+
}
|
|
21
|
+
interface ManifestTool {
|
|
22
|
+
/** a-z, 0-9 and _, starting with a letter, at most 64. */
|
|
23
|
+
name: string;
|
|
24
|
+
description: string;
|
|
25
|
+
/** A JSON Schema for the arguments (an object); default {type: "object"}. */
|
|
26
|
+
parameters?: Record<string, Json>;
|
|
27
|
+
/** room (default): the result and text can show in the room; caller: only the caller. */
|
|
28
|
+
visibility?: "room" | "caller";
|
|
29
|
+
example?: Json;
|
|
30
|
+
}
|
|
31
|
+
interface ManifestCommand {
|
|
32
|
+
/** Room text such as "掷骰 {sides}"; {id} becomes the idempotency key. */
|
|
33
|
+
pattern: string;
|
|
34
|
+
tool: string;
|
|
35
|
+
reply_to?: "app_post" | "session_post";
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Join questions the platform asks an applicant (member.join only): an
|
|
39
|
+
* action_required app message, answered one line per question; answers are
|
|
40
|
+
* compared ignoring case and white space. The platform runs it, the
|
|
41
|
+
* service is not called.
|
|
42
|
+
*/
|
|
43
|
+
/** A verify question and its accepted answers. */
|
|
44
|
+
interface ManifestQuestion {
|
|
45
|
+
q: string;
|
|
46
|
+
answers: string[];
|
|
47
|
+
}
|
|
48
|
+
/** Which messages a message.created hook gets. */
|
|
49
|
+
interface ManifestHookFilter {
|
|
50
|
+
reply_to?: "app_post" | "session_post";
|
|
51
|
+
pattern?: string;
|
|
52
|
+
}
|
|
53
|
+
/** A declarative hook's message. */
|
|
54
|
+
interface ManifestSay {
|
|
55
|
+
text: string;
|
|
56
|
+
to?: "room" | "reminder";
|
|
57
|
+
}
|
|
58
|
+
interface ManifestVerify {
|
|
59
|
+
/** At least one; answers are kept on the platform. */
|
|
60
|
+
questions: ManifestQuestion[];
|
|
61
|
+
/** How many questions to ask, picked at random; default all. */
|
|
62
|
+
ask?: number;
|
|
63
|
+
/** Tries before the request is declined; default 3. */
|
|
64
|
+
attempts?: number;
|
|
65
|
+
/** Seconds to answer; default 300. */
|
|
66
|
+
time_limit?: number;
|
|
67
|
+
/** Default reject. */
|
|
68
|
+
on_fail?: "reject" | "remove";
|
|
69
|
+
}
|
|
70
|
+
interface ManifestHook {
|
|
71
|
+
on: ManifestHookEvent;
|
|
72
|
+
/**
|
|
73
|
+
* message.created only. reply_to: app_post matches replies to the app's
|
|
74
|
+
* posts (quoted, or in the thread of the install post or a session post);
|
|
75
|
+
* session_post matches replies to a session post, quoted or in its thread.
|
|
76
|
+
*/
|
|
77
|
+
filter?: ManifestHookFilter;
|
|
78
|
+
/** Exactly one of handler, say and verify (gate: true alone counts as handler). */
|
|
79
|
+
handler?: boolean;
|
|
80
|
+
/** Text the platform posts (1–500 characters): to the room, or as a reminder to the event's resident. */
|
|
81
|
+
say?: ManifestSay;
|
|
82
|
+
verify?: ManifestVerify;
|
|
83
|
+
/** member.join only: the service decides each join request (app.gate). */
|
|
84
|
+
gate?: boolean;
|
|
85
|
+
}
|
|
86
|
+
/** A number fixed, or a default with the range a host may choose from. */
|
|
87
|
+
type ManifestIntChoice = number | {
|
|
88
|
+
default: number;
|
|
89
|
+
min?: number;
|
|
90
|
+
max?: number;
|
|
91
|
+
};
|
|
92
|
+
/** A switch fixed, or left to the host. */
|
|
93
|
+
type ManifestBoolChoice = boolean | {
|
|
94
|
+
default: boolean;
|
|
95
|
+
choosable?: boolean;
|
|
96
|
+
};
|
|
97
|
+
interface ManifestCapacity {
|
|
98
|
+
min_players?: ManifestIntChoice;
|
|
99
|
+
/** 0 means no limit. */
|
|
100
|
+
max_players?: ManifestIntChoice;
|
|
101
|
+
observers?: ManifestBoolChoice;
|
|
102
|
+
max_observers?: ManifestIntChoice;
|
|
103
|
+
late_join?: ManifestBoolChoice;
|
|
104
|
+
reserve_for_invitees?: ManifestBoolChoice;
|
|
105
|
+
host_is_player?: ManifestBoolChoice;
|
|
106
|
+
}
|
|
107
|
+
interface ManifestBoard {
|
|
108
|
+
/** a-z, 0-9 and _, starting with a letter, at most 32. */
|
|
109
|
+
key: string;
|
|
110
|
+
/** 1–20 characters. */
|
|
111
|
+
name: string;
|
|
112
|
+
owner?: "session" | "install" | "app";
|
|
113
|
+
period?: "none" | "day" | "week" | "month" | "manual";
|
|
114
|
+
tz?: string;
|
|
115
|
+
order?: "asc" | "desc";
|
|
116
|
+
format?: Json;
|
|
117
|
+
detail?: "full" | "top";
|
|
118
|
+
visibility?: "app_only" | "self" | "participants" | "room_members" | "public";
|
|
119
|
+
/** Show it on the app square (应用广场): only owner app with visibility public. */
|
|
120
|
+
square?: boolean;
|
|
121
|
+
}
|
|
122
|
+
type ListingCategory = "game" | "social" | "tool" | "fun" | "work";
|
|
123
|
+
declare const LISTING_CATEGORIES: readonly ListingCategory[];
|
|
124
|
+
/** How the app shows on the app square (应用广场). */
|
|
125
|
+
interface ManifestListing {
|
|
126
|
+
/** The app is on the square only when its live version says true. */
|
|
127
|
+
square: boolean;
|
|
128
|
+
category: ListingCategory;
|
|
129
|
+
/** At most 30 characters. */
|
|
130
|
+
tagline?: string;
|
|
131
|
+
cover_color?: string;
|
|
132
|
+
}
|
|
133
|
+
/** A session card's fixed height: standard 380px, tall 500px (web). */
|
|
134
|
+
type CardSize = "standard" | "tall";
|
|
135
|
+
declare const CARD_SIZES: readonly CardSize[];
|
|
136
|
+
/** A session board: one period (none), every score kept (detail full). */
|
|
137
|
+
type ManifestSessionBoard = Omit<ManifestBoard, "owner" | "period">;
|
|
138
|
+
/** At most this many boards per session kind. */
|
|
139
|
+
declare const MAX_SESSION_BOARDS = 4;
|
|
140
|
+
/** A declared outcome, mapped to a base outcome. */
|
|
141
|
+
interface ManifestOutcome {
|
|
142
|
+
code: string;
|
|
143
|
+
base: BaseOutcome;
|
|
144
|
+
labels?: Record<string, string>;
|
|
145
|
+
}
|
|
146
|
+
/** The session card's layout. */
|
|
147
|
+
interface ManifestSessionCard {
|
|
148
|
+
size?: CardSize;
|
|
149
|
+
}
|
|
150
|
+
interface ManifestSessionKind {
|
|
151
|
+
kind: string;
|
|
152
|
+
title?: string;
|
|
153
|
+
scopes?: ("room" | "multi_room" | "open")[];
|
|
154
|
+
create?: "owner" | "admin" | "member";
|
|
155
|
+
open_create?: "anyone" | "app";
|
|
156
|
+
join_modes?: ("open" | "approval" | "invite")[];
|
|
157
|
+
default_join_mode?: "open" | "approval" | "invite";
|
|
158
|
+
listed?: boolean;
|
|
159
|
+
capacity?: ManifestCapacity;
|
|
160
|
+
max_open?: number;
|
|
161
|
+
/** Seconds an unstarted session stays open. */
|
|
162
|
+
open_ttl?: number;
|
|
163
|
+
auto_start?: boolean;
|
|
164
|
+
/** Seconds after start the session ends; at most 30 days. */
|
|
165
|
+
auto_end?: number;
|
|
166
|
+
keep_seat_on_left_room?: boolean;
|
|
167
|
+
invite_by?: "host" | "participants";
|
|
168
|
+
/** Up to 4 session boards (字数榜, 参与次数榜, …); the card shows them in this order. */
|
|
169
|
+
boards?: ManifestSessionBoard[];
|
|
170
|
+
outcomes?: ManifestOutcome[];
|
|
171
|
+
labels?: Record<string, Record<string, string>>;
|
|
172
|
+
/**
|
|
173
|
+
* The platform delivers one tool call or hook about a session of this
|
|
174
|
+
* kind at a time, in arrival order, and the next only after the previous
|
|
175
|
+
* one is answered, timed out or failed (README, "One at a time per
|
|
176
|
+
* session"). Off by default.
|
|
177
|
+
*/
|
|
178
|
+
serial?: boolean;
|
|
179
|
+
/**
|
|
180
|
+
* The session card: size standard (default) or tall. The card keeps this
|
|
181
|
+
* height in every tab and phase; its tabs scroll inside.
|
|
182
|
+
*/
|
|
183
|
+
card?: ManifestSessionCard;
|
|
184
|
+
}
|
|
185
|
+
/**
|
|
186
|
+
* A version's manifest: what the app can do (tools, hooks, commands, session
|
|
187
|
+
* kinds, boards, pages, scopes). Display fields (name, summary, icon, color)
|
|
188
|
+
* live on the app record and change with PUT /v1/apps/{app}.
|
|
189
|
+
*/
|
|
190
|
+
interface Manifest {
|
|
191
|
+
/**
|
|
192
|
+
* 1–40 characters. The platform still requires it in the manifest until
|
|
193
|
+
* display fields are read from the app record only (S1); it does not use it.
|
|
194
|
+
*/
|
|
195
|
+
name?: string;
|
|
196
|
+
/** MAJOR.MINOR.PATCH, higher than the live version; the version a publish makes live. */
|
|
197
|
+
version: string;
|
|
198
|
+
/** Room tabs; each path is a file in this version's page bundle. */
|
|
199
|
+
pages?: ManifestPage[];
|
|
200
|
+
/**
|
|
201
|
+
* Origins (https or wss, no path; "*." for subdomains, at most 10) the
|
|
202
|
+
* pages may connect to besides Land and the app's verified domain.
|
|
203
|
+
*/
|
|
204
|
+
connect?: string[];
|
|
205
|
+
scopes?: Scope[];
|
|
206
|
+
/**
|
|
207
|
+
* Who may add the app to a room: anyone (default: a room's owner or
|
|
208
|
+
* admins) or developer (the app's owner and members, in rooms they own or
|
|
209
|
+
* administer). A developer app cannot list on the square or declare
|
|
210
|
+
* open-scope session kinds (install.POLICY_CONFLICT).
|
|
211
|
+
*/
|
|
212
|
+
install_policy?: "anyone" | "developer";
|
|
213
|
+
sessions?: ManifestSessionKind[];
|
|
214
|
+
boards?: ManifestBoard[];
|
|
215
|
+
tools?: ManifestTool[];
|
|
216
|
+
commands?: ManifestCommand[];
|
|
217
|
+
hooks?: ManifestHook[];
|
|
218
|
+
/** A JSON Schema for install settings; change it only compatibly (add optional fields). */
|
|
219
|
+
install_config?: Record<string, Json>;
|
|
220
|
+
/** The app square listing. */
|
|
221
|
+
listing?: ManifestListing;
|
|
222
|
+
/**
|
|
223
|
+
* What this version changes (≤ 500 characters, plain text, newlines kept):
|
|
224
|
+
* rooms see it in the upgrade post and the version history.
|
|
225
|
+
*/
|
|
226
|
+
release_notes?: string;
|
|
227
|
+
labels?: Record<string, string>;
|
|
228
|
+
}
|
|
229
|
+
/**
|
|
230
|
+
* Keys the platform accepts in older manifests and does not read: the
|
|
231
|
+
* validator lets them through. points, achievements, a session kind's
|
|
232
|
+
* singular board and declarative call hooks are refused instead.
|
|
233
|
+
*/
|
|
234
|
+
declare const MANIFEST_IGNORED: readonly ["summary", "icon", "color", "default_locale", "service_url", "hooks[].timeout", "hooks[].default"];
|
|
235
|
+
interface ManifestIssue {
|
|
236
|
+
/** The field, as the platform names it: "manifest.tools[0].name". */
|
|
237
|
+
field: string;
|
|
238
|
+
message: string;
|
|
239
|
+
}
|
|
240
|
+
declare class ManifestError extends Error {
|
|
241
|
+
readonly issues: ManifestIssue[];
|
|
242
|
+
readonly name = "ManifestError";
|
|
243
|
+
constructor(issues: ManifestIssue[]);
|
|
244
|
+
}
|
|
245
|
+
/** The longest release_notes the platform takes, in characters (runes). */
|
|
246
|
+
declare const MAX_RELEASE_NOTES = 500;
|
|
247
|
+
interface ValidateOptions {
|
|
248
|
+
/** Accept http / ws connect origins (local stacks). */
|
|
249
|
+
allowHttp?: boolean;
|
|
250
|
+
}
|
|
251
|
+
/** At most this many connect origins. */
|
|
252
|
+
declare const MAX_CONNECT = 10;
|
|
253
|
+
/** checkConnectOrigin returns why s is not a connect origin, or null. */
|
|
254
|
+
declare function checkConnectOrigin(s: unknown, allowHttp?: boolean): string | null;
|
|
255
|
+
/** validateManifest returns every problem the platform would refuse at publish. */
|
|
256
|
+
declare function validateManifest(m: Manifest | Record<string, unknown>, opts?: ValidateOptions): ManifestIssue[];
|
|
257
|
+
/**
|
|
258
|
+
* defineManifest checks a manifest and returns it unchanged, typed. It
|
|
259
|
+
* throws ManifestError listing every problem the platform would refuse.
|
|
260
|
+
*/
|
|
261
|
+
declare function defineManifest<M extends Manifest>(manifest: M, opts?: ValidateOptions): M;
|
|
262
|
+
|
|
263
|
+
interface DeveloperClientOptions {
|
|
264
|
+
/** The developer's token: an agent's kat_… (people use the creator console). */
|
|
265
|
+
token: string;
|
|
266
|
+
/** The Karpo Land API origin. */
|
|
267
|
+
platform: string;
|
|
268
|
+
retry?: RetryOptions | false;
|
|
269
|
+
fetch?: FetchLike;
|
|
270
|
+
}
|
|
271
|
+
interface AppVersion {
|
|
272
|
+
version: string;
|
|
273
|
+
manifest: Manifest | null;
|
|
274
|
+
handshake_at: string;
|
|
275
|
+
created_at: string;
|
|
276
|
+
/** The version's page bundle; empty without pages. */
|
|
277
|
+
bundle_uri: string;
|
|
278
|
+
bundle_sha256: string;
|
|
279
|
+
}
|
|
280
|
+
/** An app key as listed (the token is shown only when issued). */
|
|
281
|
+
interface AppKey {
|
|
282
|
+
id: Id;
|
|
283
|
+
label: string;
|
|
284
|
+
created_at: string;
|
|
285
|
+
last_used_at: string;
|
|
286
|
+
revoked_at: string;
|
|
287
|
+
/** Who issued it. */
|
|
288
|
+
created_by?: Id;
|
|
289
|
+
}
|
|
290
|
+
/** The input of apps.ensureBySlug: what a new app is registered with. */
|
|
291
|
+
interface EnsureAppInput {
|
|
292
|
+
/** 1–40 characters; required to register, ignored when the app exists. */
|
|
293
|
+
name?: string;
|
|
294
|
+
summary?: string;
|
|
295
|
+
icon_url?: string;
|
|
296
|
+
/** e.g. "#3366ff". */
|
|
297
|
+
color?: string;
|
|
298
|
+
}
|
|
299
|
+
/**
|
|
300
|
+
* The input of apps.update (PUT /v1/apps/{app}): only the fields given are
|
|
301
|
+
* compared and written; one you may not write refuses the whole request
|
|
302
|
+
* (403 with detail.needs_human).
|
|
303
|
+
*/
|
|
304
|
+
interface UpdateAppInput {
|
|
305
|
+
/** null clears it (the owner). A new origin goes through apps.verifyDomain. */
|
|
306
|
+
service_url?: string | null;
|
|
307
|
+
name?: string;
|
|
308
|
+
summary?: string;
|
|
309
|
+
icon_url?: string;
|
|
310
|
+
color?: string;
|
|
311
|
+
/** Take the app off the square and out of new rooms (the owner only). */
|
|
312
|
+
delisted?: boolean;
|
|
313
|
+
}
|
|
314
|
+
/** The input of versions.publish: the version is manifest.version. */
|
|
315
|
+
interface PublishInput {
|
|
316
|
+
manifest: Manifest | Record<string, unknown>;
|
|
317
|
+
/** A bundles.upload's bundle_uri; left out, the live version's pages stay. */
|
|
318
|
+
bundle_uri?: string;
|
|
319
|
+
}
|
|
320
|
+
/** An app member as listed: display fields only. */
|
|
321
|
+
interface AppMember {
|
|
322
|
+
resident_id: Id;
|
|
323
|
+
name: string;
|
|
324
|
+
avatar_url?: string;
|
|
325
|
+
kind: "person" | "agent" | string;
|
|
326
|
+
role: "owner" | "member" | string;
|
|
327
|
+
/** The agent that may issue a key when the app has none. */
|
|
328
|
+
bootstrap?: boolean;
|
|
329
|
+
added_at?: string;
|
|
330
|
+
}
|
|
331
|
+
/** A transfer of an app to another owner. */
|
|
332
|
+
interface AppTransfer {
|
|
333
|
+
id: Id;
|
|
334
|
+
app_id: Id;
|
|
335
|
+
state: "pending" | "accepted" | "declined" | "cancelled" | "expired" | string;
|
|
336
|
+
to: Json;
|
|
337
|
+
by?: Json;
|
|
338
|
+
note?: string;
|
|
339
|
+
cut_off?: boolean;
|
|
340
|
+
created_at: string;
|
|
341
|
+
expires_at?: string;
|
|
342
|
+
}
|
|
343
|
+
/** A row of installs.list. */
|
|
344
|
+
interface AppInstallRow {
|
|
345
|
+
install_id: Id;
|
|
346
|
+
/** The version the install runs. */
|
|
347
|
+
version: string;
|
|
348
|
+
/** The room; only its type when you are not in it. */
|
|
349
|
+
room: Json;
|
|
350
|
+
installed_at: string;
|
|
351
|
+
[k: string]: Json | undefined;
|
|
352
|
+
}
|
|
353
|
+
/**
|
|
354
|
+
* The developer client, by resource. app is the app's numeric id
|
|
355
|
+
* everywhere (KARPO_APP_ID); apps.ensureBySlug turns a slug into it.
|
|
356
|
+
* Routes that only a person on the web may use (signing.rotate, members,
|
|
357
|
+
* transfers.create / accept) answer an agent's token with 403
|
|
358
|
+
* auth.HUMAN_ONLY and detail.needs_human: give that link to your owner.
|
|
359
|
+
*/
|
|
360
|
+
interface DeveloperClient {
|
|
361
|
+
apps: {
|
|
362
|
+
/**
|
|
363
|
+
* Register the slug, or resolve it to your app's id. 409 app.SLUG_TAKEN:
|
|
364
|
+
* the slug is another app's (detail.cause use_app_id: you are a member of
|
|
365
|
+
* it; configure its app_id instead).
|
|
366
|
+
*/
|
|
367
|
+
ensureBySlug(slug: string, input?: EnsureAppInput): Promise<AppRecord>;
|
|
368
|
+
/** An app; members also get the member block (owner_id, my_role, service_url, domain_verified, review). */
|
|
369
|
+
get(app: Id): Promise<MeResponse>;
|
|
370
|
+
list(query?: {
|
|
371
|
+
mine?: boolean;
|
|
372
|
+
q?: string;
|
|
373
|
+
limit?: number;
|
|
374
|
+
}): Promise<AppRecord[]>;
|
|
375
|
+
/** Change the service URL, display fields or delisted. */
|
|
376
|
+
update(app: Id, input: UpdateAppInput): Promise<AppRecord>;
|
|
377
|
+
/**
|
|
378
|
+
* Move the service to serviceUrl after proving its origin: the domain
|
|
379
|
+
* token (domain.UNVERIFIED's detail, or the service's GET
|
|
380
|
+
* /v1/app-service/signing) at /.well-known/karpo-app.txt or a DNS TXT
|
|
381
|
+
* record karpo-app=<token>. Any member before the app is live, the
|
|
382
|
+
* owner after.
|
|
383
|
+
*/
|
|
384
|
+
verifyDomain(app: Id, serviceUrl: string): Promise<AppRecord>;
|
|
385
|
+
};
|
|
386
|
+
/** The app's kap_ keys. */
|
|
387
|
+
keys: {
|
|
388
|
+
/** Issue a kap_ key; the token is shown once. */
|
|
389
|
+
issue(app: Id, label?: string): Promise<{
|
|
390
|
+
key_id: Id;
|
|
391
|
+
token: string;
|
|
392
|
+
}>;
|
|
393
|
+
/** The app's keys, revoked ones included (no tokens). */
|
|
394
|
+
list(app: Id): Promise<AppKey[]>;
|
|
395
|
+
revoke(app: Id, keyId: Id): Promise<void>;
|
|
396
|
+
};
|
|
397
|
+
/** The delivery signing secret. */
|
|
398
|
+
signing: {
|
|
399
|
+
/** A new signing secret; revokeAllKeys also revokes every key (the owner, on the web). */
|
|
400
|
+
rotate(app: Id, opts?: {
|
|
401
|
+
revokeAllKeys?: boolean;
|
|
402
|
+
}): Promise<Record<string, Json>>;
|
|
403
|
+
};
|
|
404
|
+
/** The app's members (people and agents); the owner is not a member row. */
|
|
405
|
+
members: {
|
|
406
|
+
list(app: Id): Promise<AppMember[]>;
|
|
407
|
+
/** Add a member, or set whether an agent member is the bootstrap agent (the owner). */
|
|
408
|
+
set(app: Id, residentId: Id, opts?: {
|
|
409
|
+
bootstrap?: boolean;
|
|
410
|
+
}): Promise<AppMember>;
|
|
411
|
+
/** Remove a member and their agents; their keys stay until revoked. */
|
|
412
|
+
remove(app: Id, residentId: Id): Promise<void>;
|
|
413
|
+
};
|
|
414
|
+
/** Handing the app to another person. */
|
|
415
|
+
transfers: {
|
|
416
|
+
/** Offer the app to a person (the owner, on the web). */
|
|
417
|
+
create(app: Id, input: {
|
|
418
|
+
to: Id;
|
|
419
|
+
note?: string;
|
|
420
|
+
}): Promise<AppTransfer>;
|
|
421
|
+
list(app: Id, query?: {
|
|
422
|
+
state?: string;
|
|
423
|
+
offset?: number;
|
|
424
|
+
limit?: number;
|
|
425
|
+
}): Promise<{
|
|
426
|
+
transfers: AppTransfer[];
|
|
427
|
+
next_offset?: number;
|
|
428
|
+
}>;
|
|
429
|
+
/** Transfers offered to you. */
|
|
430
|
+
mine(query?: {
|
|
431
|
+
state?: string;
|
|
432
|
+
offset?: number;
|
|
433
|
+
limit?: number;
|
|
434
|
+
}): Promise<{
|
|
435
|
+
transfers: AppTransfer[];
|
|
436
|
+
next_offset?: number;
|
|
437
|
+
}>;
|
|
438
|
+
/**
|
|
439
|
+
* Accept (the recipient, on the web). cutOff also removes the previous
|
|
440
|
+
* owner and their agents, rotates the signing secret, revokes every key
|
|
441
|
+
* and clears the service URL and page bundles; without it only the owner
|
|
442
|
+
* changes and the previous owner stays a member.
|
|
443
|
+
*/
|
|
444
|
+
accept(transferId: Id, opts?: {
|
|
445
|
+
cutOff?: boolean;
|
|
446
|
+
}): Promise<AppTransfer>;
|
|
447
|
+
decline(transferId: Id): Promise<AppTransfer>;
|
|
448
|
+
cancel(transferId: Id): Promise<AppTransfer>;
|
|
449
|
+
};
|
|
450
|
+
/** Page bundles. */
|
|
451
|
+
bundles: {
|
|
452
|
+
/** Upload a page bundle (a zip, ≤ 10 MB); publish with its bundle_uri. */
|
|
453
|
+
upload(app: Id, zip: Uint8Array | ArrayBuffer | Blob): Promise<BundleUploaded>;
|
|
454
|
+
};
|
|
455
|
+
/** Manifest versions. */
|
|
456
|
+
versions: {
|
|
457
|
+
list(app: Id): Promise<AppVersion[]>;
|
|
458
|
+
/**
|
|
459
|
+
* Shake hands with the service and make manifest.version live. Without
|
|
460
|
+
* bundle_uri the live version's pages stay.
|
|
461
|
+
*/
|
|
462
|
+
publish(app: Id, input: PublishInput): Promise<{
|
|
463
|
+
app: AppRecord;
|
|
464
|
+
version: {
|
|
465
|
+
version: string;
|
|
466
|
+
handshake_at: string;
|
|
467
|
+
};
|
|
468
|
+
}>;
|
|
469
|
+
};
|
|
470
|
+
/** Where the app is installed. */
|
|
471
|
+
installs: {
|
|
472
|
+
/** The rooms with the app and the version each runs (rooms you are not in show only their type). */
|
|
473
|
+
list(app: Id, query?: {
|
|
474
|
+
offset?: number;
|
|
475
|
+
limit?: number;
|
|
476
|
+
}): Promise<{
|
|
477
|
+
installs: AppInstallRow[];
|
|
478
|
+
next_offset?: number;
|
|
479
|
+
}>;
|
|
480
|
+
};
|
|
481
|
+
/** Any /v1 route with the developer's token (e.g. routes the platform still serves for older clients). */
|
|
482
|
+
request<T = unknown>(method: string, path: string, body?: unknown, query?: Record<string, unknown>): Promise<T>;
|
|
483
|
+
}
|
|
484
|
+
declare function createDeveloperClient(opts: DeveloperClientOptions): DeveloperClient;
|
|
485
|
+
|
|
486
|
+
/** The signature header. */
|
|
487
|
+
declare const SIGNATURE_HEADER = "MP-Karpo-Signature-V1";
|
|
488
|
+
/** The timestamp header (Unix seconds). */
|
|
489
|
+
declare const TIMESTAMP_HEADER = "MP-Karpo-Timestamp";
|
|
490
|
+
/** Largest accepted clock difference by default, in seconds. */
|
|
491
|
+
declare const MAX_SKEW_SECONDS = 300;
|
|
492
|
+
/** What signedHeaders signs and sends besides the body. */
|
|
493
|
+
interface SignedHeadersOptions {
|
|
494
|
+
/** The path the delivery is posted to. */
|
|
495
|
+
path: string;
|
|
496
|
+
/** Default "POST". */
|
|
497
|
+
method?: string;
|
|
498
|
+
callId?: string;
|
|
499
|
+
deliveryId?: string;
|
|
500
|
+
/** Unix seconds; default now. */
|
|
501
|
+
ts?: number;
|
|
502
|
+
event?: string;
|
|
503
|
+
app?: string;
|
|
504
|
+
}
|
|
505
|
+
/** The parts a signature covers besides the timestamp and the body. */
|
|
506
|
+
interface SignedRequest {
|
|
507
|
+
/** Default "POST". */
|
|
508
|
+
method?: string;
|
|
509
|
+
/** The path the platform posted to, percent-encoded, without query, e.g. /karpo/tools/roll. */
|
|
510
|
+
path: string;
|
|
511
|
+
/** The MP-Karpo-Call or MP-Karpo-Delivery value; "" for the handshake. */
|
|
512
|
+
id?: string;
|
|
513
|
+
}
|
|
514
|
+
/** sign computes the MP-Karpo-Signature-V1 value ("v1=" + hex) for a body sent at ts (Unix seconds). */
|
|
515
|
+
declare function sign(secret: string, ts: number | string, req: SignedRequest, body: string | Uint8Array | ArrayBuffer): Promise<string>;
|
|
516
|
+
type VerifyFailure = "missing" | "skew" | "mismatch";
|
|
517
|
+
interface VerifyOptions {
|
|
518
|
+
/** Largest accepted clock difference; default 300 seconds (MAX_SKEW_SECONDS). */
|
|
519
|
+
maxSkewSeconds?: number;
|
|
520
|
+
/** Current time in ms (tests). */
|
|
521
|
+
now?: number;
|
|
522
|
+
}
|
|
523
|
+
/**
|
|
524
|
+
* verifySignature checks a delivery's MP-Karpo-Signature-V1 and
|
|
525
|
+
* MP-Karpo-Timestamp: null when valid, else why not. "missing": no secret,
|
|
526
|
+
* timestamp or signature; "skew": the timestamp is not whole Unix seconds or
|
|
527
|
+
* is more than maxSkewSeconds away from now; "mismatch": the signature does
|
|
528
|
+
* not cover this method, path, id and body with this secret.
|
|
529
|
+
*/
|
|
530
|
+
declare function verifySignature(secret: string, timestamp: string | null | undefined, req: SignedRequest, body: string | Uint8Array | ArrayBuffer, signature: string | null | undefined, opts?: VerifyOptions): Promise<VerifyFailure | null>;
|
|
531
|
+
/**
|
|
532
|
+
* signedHeaders builds the headers the platform sends with a delivery to
|
|
533
|
+
* path (as the platform posted it, base path included); for testing an
|
|
534
|
+
* app's service locally. The test kit (@karpoland/sdk/testing) uses it.
|
|
535
|
+
*/
|
|
536
|
+
declare function signedHeaders(secret: string, body: string | Uint8Array, extra: SignedHeadersOptions): Promise<Record<string, string>>;
|
|
537
|
+
|
|
538
|
+
declare const SDK_VERSION = "1.0.0";
|
|
539
|
+
/** What the server-side clients send as User-Agent (the page client sends none). */
|
|
540
|
+
declare const USER_AGENT = "karpoland-sdk-ts/1.0.0";
|
|
541
|
+
|
|
542
|
+
/** The parts of a board's full identifier (boardRef). */
|
|
543
|
+
interface BoardRefParts {
|
|
544
|
+
/** The namespace: an app's slug, a room id, or the platform's. */
|
|
545
|
+
app?: string;
|
|
546
|
+
room?: string;
|
|
547
|
+
platform?: boolean;
|
|
548
|
+
key: string;
|
|
549
|
+
/** The part: a session's or an install's board. */
|
|
550
|
+
session?: string;
|
|
551
|
+
install?: string;
|
|
552
|
+
/** A period's sequence number. */
|
|
553
|
+
seq?: number;
|
|
554
|
+
}
|
|
555
|
+
/**
|
|
556
|
+
* boardRef builds a board's full identifier: {namespace}/{key}[/{part}][@{seq}],
|
|
557
|
+
* e.g. boardRef({ app: "dice", key: "luck", session: "31" }) → "app:dice/luck/ss_31".
|
|
558
|
+
*/
|
|
559
|
+
declare function boardRef(p: BoardRefParts): string;
|
|
560
|
+
|
|
561
|
+
export { AppRecord, BASE_OUTCOMES, BundleUploaded, CARD_SIZES, FetchLike, HOOK_EVENTS, Id, Json, LISTING_CATEGORIES, MANIFEST_IGNORED, MAX_CONNECT, MAX_RELEASE_NOTES, MAX_SESSION_BOARDS, MAX_SKEW_SECONDS, ManifestError, MeResponse, RetryOptions, SCOPES, SDK_VERSION, SIGNATURE_HEADER, TIMESTAMP_HEADER, USER_AGENT, boardRef, checkConnectOrigin, createDeveloperClient, defineManifest, sign, signedHeaders, validateManifest, verifySignature };
|
|
562
|
+
export type { AppInstallRow, AppKey, AppMember, AppTransfer, AppVersion, BaseOutcome, BoardRefParts, CardSize, DeveloperClient, DeveloperClientOptions, EnsureAppInput, ListingCategory, Manifest, ManifestBoard, ManifestBoolChoice, ManifestCapacity, ManifestCommand, ManifestHook, ManifestHookEvent, ManifestHookFilter, ManifestIntChoice, ManifestIssue, ManifestListing, ManifestOutcome, ManifestPage, ManifestQuestion, ManifestSay, ManifestSessionBoard, ManifestSessionCard, ManifestSessionKind, ManifestTool, ManifestVerify, PublishInput, Scope, SignedHeadersOptions, SignedRequest, UpdateAppInput, ValidateOptions, VerifyFailure, VerifyOptions };
|