@tyvm/knowhow-app-sdk 0.0.0-stage → 0.1.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/README.md +141 -2
- package/dist/index.cjs +1141 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +528 -0
- package/dist/index.d.ts +528 -0
- package/dist/index.js +1101 -0
- package/dist/index.js.map +1 -0
- package/dist/knowhow-sdk.iife.js +1 -0
- package/package.json +37 -4
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,528 @@
|
|
|
1
|
+
/** Closed capability list v1. */
|
|
2
|
+
declare const CAPABILITIES: readonly ["db:app", "files:app", "ai:complete", "ai:transcribe", "ai:image", "tools:expose"];
|
|
3
|
+
type Capability = (typeof CAPABILITIES)[number];
|
|
4
|
+
|
|
5
|
+
declare const PROTOCOL_VERSION: 1;
|
|
6
|
+
/** Provider method names (v1). Breaking changes ship as new names (`kh_x_v2`). */
|
|
7
|
+
declare const Methods: {
|
|
8
|
+
readonly Protocol: "kh_protocol";
|
|
9
|
+
readonly Connect: "kh_connect";
|
|
10
|
+
readonly Session: "kh_session";
|
|
11
|
+
readonly Disconnect: "kh_disconnect";
|
|
12
|
+
readonly DbQuery: "kh_db_query";
|
|
13
|
+
readonly DbExec: "kh_db_exec";
|
|
14
|
+
readonly DbBatch: "kh_db_batch";
|
|
15
|
+
readonly KvGet: "kh_kv_get";
|
|
16
|
+
readonly KvSet: "kh_kv_set";
|
|
17
|
+
readonly KvDelete: "kh_kv_delete";
|
|
18
|
+
readonly FilesList: "kh_files_list";
|
|
19
|
+
readonly FilesRead: "kh_files_read";
|
|
20
|
+
readonly FilesWrite: "kh_files_write";
|
|
21
|
+
readonly FilesStat: "kh_files_stat";
|
|
22
|
+
readonly FilesDelete: "kh_files_delete";
|
|
23
|
+
readonly FilesUploadStart: "kh_files_upload_start";
|
|
24
|
+
readonly FilesUploadComplete: "kh_files_upload_complete";
|
|
25
|
+
readonly FilesDownloadUrl: "kh_files_download_url";
|
|
26
|
+
readonly AiComplete: "kh_ai_complete";
|
|
27
|
+
readonly AiTranscribe: "kh_ai_transcribe";
|
|
28
|
+
readonly AiImage: "kh_ai_image";
|
|
29
|
+
readonly SpendGet: "kh_spend_get";
|
|
30
|
+
readonly AppEnv: "kh_app_env";
|
|
31
|
+
readonly ToolsRegister: "kh_tools_register";
|
|
32
|
+
readonly ToolsResult: "kh_tools_result";
|
|
33
|
+
readonly UiNotify: "kh_ui_notify";
|
|
34
|
+
};
|
|
35
|
+
/** Provider events. */
|
|
36
|
+
declare const Events: {
|
|
37
|
+
readonly Connect: "connect";
|
|
38
|
+
readonly Disconnect: "disconnect";
|
|
39
|
+
readonly SessionChanged: "sessionChanged";
|
|
40
|
+
readonly ToolCall: "toolCall";
|
|
41
|
+
readonly Message: "message";
|
|
42
|
+
};
|
|
43
|
+
type JsonPrimitive = string | number | boolean | null;
|
|
44
|
+
type JsonValue = JsonPrimitive | JsonValue[] | {
|
|
45
|
+
[key: string]: JsonValue;
|
|
46
|
+
};
|
|
47
|
+
type JsonObject = {
|
|
48
|
+
[key: string]: JsonValue;
|
|
49
|
+
};
|
|
50
|
+
type HostKind$1 = "web" | "extension" | "desktop" | "mobile";
|
|
51
|
+
interface HostInfo {
|
|
52
|
+
kind: HostKind$1;
|
|
53
|
+
version: string;
|
|
54
|
+
}
|
|
55
|
+
interface ProtocolResult {
|
|
56
|
+
protocol: typeof PROTOCOL_VERSION;
|
|
57
|
+
methods: string[];
|
|
58
|
+
host: HostInfo;
|
|
59
|
+
}
|
|
60
|
+
interface SessionInfo {
|
|
61
|
+
/**
|
|
62
|
+
* App id of a registered app. For a self-hosted site session (no Knowhow app entry) this is
|
|
63
|
+
* `site:<origin>` so code that keys on `appId` keeps working; check `site` to tell the two apart.
|
|
64
|
+
*/
|
|
65
|
+
appId: string;
|
|
66
|
+
user: {
|
|
67
|
+
displayName: string;
|
|
68
|
+
};
|
|
69
|
+
capabilities: Capability[];
|
|
70
|
+
/**
|
|
71
|
+
* Present only for self-hosted site sessions: the site's real origin, as observed by the host
|
|
72
|
+
* (never self-claimed by the page). Such sessions are billed to the visitor and limited to
|
|
73
|
+
* ai:* and db:app (+ host-only tools).
|
|
74
|
+
*/
|
|
75
|
+
site?: {
|
|
76
|
+
origin: string;
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
type SqlParam = string | number | boolean | null;
|
|
80
|
+
interface SqlStatement {
|
|
81
|
+
sql: string;
|
|
82
|
+
params?: SqlParam[];
|
|
83
|
+
}
|
|
84
|
+
interface DbQueryResult {
|
|
85
|
+
rows: Array<Record<string, JsonValue>>;
|
|
86
|
+
columns: string[];
|
|
87
|
+
}
|
|
88
|
+
interface DbExecResult {
|
|
89
|
+
changes: number;
|
|
90
|
+
lastInsertRowid: number | string | null;
|
|
91
|
+
}
|
|
92
|
+
interface DbBatchResult {
|
|
93
|
+
results: Array<DbQueryResult | DbExecResult>;
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* Where scoped app files live (`files:app`):
|
|
97
|
+
* - "user": private to the signed-in user (default)
|
|
98
|
+
* - "org": shared with the organization (subject to org folder policies)
|
|
99
|
+
*/
|
|
100
|
+
type FilesScope = "user" | "org";
|
|
101
|
+
interface AppFileInfo {
|
|
102
|
+
id: string;
|
|
103
|
+
name: string;
|
|
104
|
+
/** Path relative to the app's files root. */
|
|
105
|
+
path: string;
|
|
106
|
+
size: number;
|
|
107
|
+
mime: string;
|
|
108
|
+
updatedAt: string;
|
|
109
|
+
/** Set by the scoped API. */
|
|
110
|
+
scope?: FilesScope;
|
|
111
|
+
}
|
|
112
|
+
type FilesReadResult = {
|
|
113
|
+
text: string;
|
|
114
|
+
url?: undefined;
|
|
115
|
+
} | {
|
|
116
|
+
url: string;
|
|
117
|
+
text?: undefined;
|
|
118
|
+
};
|
|
119
|
+
interface AiMessage {
|
|
120
|
+
role: "system" | "user" | "assistant";
|
|
121
|
+
content: string;
|
|
122
|
+
}
|
|
123
|
+
interface AiCompleteParams {
|
|
124
|
+
messages: AiMessage[];
|
|
125
|
+
model?: string;
|
|
126
|
+
maxTokens?: number;
|
|
127
|
+
}
|
|
128
|
+
interface AiCompleteResult {
|
|
129
|
+
content: string;
|
|
130
|
+
model: string;
|
|
131
|
+
usage?: {
|
|
132
|
+
inputTokens?: number;
|
|
133
|
+
outputTokens?: number;
|
|
134
|
+
costUsd?: number;
|
|
135
|
+
};
|
|
136
|
+
}
|
|
137
|
+
type AiTranscribeTimestamp = "word" | "segment";
|
|
138
|
+
interface AiTranscribeParams {
|
|
139
|
+
/** Base64 or data URL ("data:audio/mpeg;base64,..."). */
|
|
140
|
+
audio: string;
|
|
141
|
+
/** e.g. "audio.mp3" (the extension tells the provider the format). */
|
|
142
|
+
fileName?: string;
|
|
143
|
+
/** Default "whisper-1". */
|
|
144
|
+
model?: string;
|
|
145
|
+
language?: string;
|
|
146
|
+
prompt?: string;
|
|
147
|
+
/** Default ["word", "segment"]. */
|
|
148
|
+
timestamps?: AiTranscribeTimestamp[];
|
|
149
|
+
}
|
|
150
|
+
interface AiTranscribeSegment {
|
|
151
|
+
start: number;
|
|
152
|
+
end: number;
|
|
153
|
+
text: string;
|
|
154
|
+
}
|
|
155
|
+
interface AiTranscribeWord {
|
|
156
|
+
start: number;
|
|
157
|
+
end: number;
|
|
158
|
+
word: string;
|
|
159
|
+
}
|
|
160
|
+
interface AiTranscribeResult {
|
|
161
|
+
text: string;
|
|
162
|
+
language?: string;
|
|
163
|
+
duration?: number;
|
|
164
|
+
model: string;
|
|
165
|
+
segments: AiTranscribeSegment[];
|
|
166
|
+
/** [] if the provider gave none. */
|
|
167
|
+
words: AiTranscribeWord[];
|
|
168
|
+
}
|
|
169
|
+
type AiImageSize = "1024x1024" | "1024x1792" | "1792x1024";
|
|
170
|
+
interface AiImageParams {
|
|
171
|
+
prompt: string;
|
|
172
|
+
/** Default "dall-e-3"; "gpt-image-1.5" when `images` is given. Editing works with gpt-image*, gemini-*-image, grok-imagine-image. */
|
|
173
|
+
model?: string;
|
|
174
|
+
size?: AiImageSize;
|
|
175
|
+
/** 1..4 */
|
|
176
|
+
n?: number;
|
|
177
|
+
/**
|
|
178
|
+
* Edit / compose instead of generate: 1..{@link AI_IMAGE_MAX_INPUTS} source images as `data:image/...;base64,` URLs.
|
|
179
|
+
* The first is the image being edited; the rest are references (style / objects to composite).
|
|
180
|
+
*/
|
|
181
|
+
images?: string[];
|
|
182
|
+
/** Inpainting mask (PNG data URL, transparent = repaint). Needs `images`; only OpenAI models honour it. */
|
|
183
|
+
mask?: string;
|
|
184
|
+
}
|
|
185
|
+
interface AiImageItem {
|
|
186
|
+
dataUrl?: string;
|
|
187
|
+
url?: string;
|
|
188
|
+
revisedPrompt?: string;
|
|
189
|
+
}
|
|
190
|
+
interface AiImageResult {
|
|
191
|
+
images: AiImageItem[];
|
|
192
|
+
model: string;
|
|
193
|
+
}
|
|
194
|
+
/** Current spend limit + usage of this app/site for the signed-in user (no capability needed). */
|
|
195
|
+
interface SpendView {
|
|
196
|
+
spendLimitUsd: number;
|
|
197
|
+
spendPeriod: "day" | "month" | "total";
|
|
198
|
+
/** USD spent in the current period. */
|
|
199
|
+
spentUsd: number;
|
|
200
|
+
/** Lifetime USD spent. */
|
|
201
|
+
spentUsdTotal: number;
|
|
202
|
+
/** ISO time the period counter resets; null for "total". */
|
|
203
|
+
periodResetsAt: string | null;
|
|
204
|
+
aiRequestsTotal: number;
|
|
205
|
+
}
|
|
206
|
+
/**
|
|
207
|
+
* The environment the app is running in ("prod", "dev", ...). `vars` are the environment's
|
|
208
|
+
* NON-SECRET variables, read at runtime (never baked into the build, so promoting a build from dev to
|
|
209
|
+
* prod picks up prod's values). Secrets are never returned. No capability needed.
|
|
210
|
+
*/
|
|
211
|
+
interface AppEnvView {
|
|
212
|
+
name: string;
|
|
213
|
+
vars: Record<string, string>;
|
|
214
|
+
}
|
|
215
|
+
interface ToolDefinition {
|
|
216
|
+
name: string;
|
|
217
|
+
description: string;
|
|
218
|
+
/** JSON Schema describing the tool arguments. */
|
|
219
|
+
parameters: JsonObject;
|
|
220
|
+
/**
|
|
221
|
+
* Optional hint: true when the tool never changes state (list/search/read). Hosts may auto-run
|
|
222
|
+
* read-only tools; everything else (readOnly absent or false) is treated as mutating and should go
|
|
223
|
+
* through the host's approval UI.
|
|
224
|
+
*/
|
|
225
|
+
readOnly?: boolean;
|
|
226
|
+
}
|
|
227
|
+
type NotifyLevel = "info" | "success" | "warning" | "error";
|
|
228
|
+
|
|
229
|
+
/** EIP-1193-like error codes used by every provider/host/backend. */
|
|
230
|
+
declare const ErrorCodes: {
|
|
231
|
+
readonly USER_REJECTED: 4001;
|
|
232
|
+
readonly UNAUTHORIZED: 4100;
|
|
233
|
+
readonly UNSUPPORTED_METHOD: 4200;
|
|
234
|
+
readonly RATE_LIMITED: 4290;
|
|
235
|
+
/** The app/site hit its USD AI spend limit. `data`: SpendLimitReachedData. */
|
|
236
|
+
readonly SPEND_LIMIT_REACHED: 4291;
|
|
237
|
+
readonly DISCONNECTED: 4900;
|
|
238
|
+
readonly INVALID_PARAMS: -32602;
|
|
239
|
+
readonly INTERNAL: -32603;
|
|
240
|
+
};
|
|
241
|
+
interface RpcErrorPayload {
|
|
242
|
+
code: number;
|
|
243
|
+
message: string;
|
|
244
|
+
data?: unknown;
|
|
245
|
+
}
|
|
246
|
+
declare class ProviderRpcError extends Error {
|
|
247
|
+
readonly code: number;
|
|
248
|
+
readonly data?: unknown;
|
|
249
|
+
constructor(code: number, message: string, data?: unknown);
|
|
250
|
+
toJSON(): RpcErrorPayload;
|
|
251
|
+
static fromPayload(payload: RpcErrorPayload): ProviderRpcError;
|
|
252
|
+
/** Normalize anything thrown into a payload suitable for the wire. */
|
|
253
|
+
static toPayload(err: unknown): RpcErrorPayload;
|
|
254
|
+
}
|
|
255
|
+
/** `error.data` of an ErrorCodes.SPEND_LIMIT_REACHED error. */
|
|
256
|
+
interface SpendLimitReachedData {
|
|
257
|
+
spentUsd: number;
|
|
258
|
+
limitUsd: number;
|
|
259
|
+
period: "day" | "month" | "total";
|
|
260
|
+
scope: "app" | "site";
|
|
261
|
+
appId?: string;
|
|
262
|
+
siteId?: string;
|
|
263
|
+
origin?: string;
|
|
264
|
+
}
|
|
265
|
+
type ProviderListener = (...args: unknown[]) => void;
|
|
266
|
+
/** EIP-1193-like provider. */
|
|
267
|
+
interface KnowhowProvider {
|
|
268
|
+
request<T = unknown>(args: {
|
|
269
|
+
method: string;
|
|
270
|
+
params?: unknown;
|
|
271
|
+
}): Promise<T>;
|
|
272
|
+
on(event: string, listener: ProviderListener): void;
|
|
273
|
+
removeListener(event: string, listener: ProviderListener): void;
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
/** Provider call signature (same shape as the SDK's internal `call`). */
|
|
277
|
+
type FilesCall = <M extends string>(method: M, params?: unknown) => Promise<unknown>;
|
|
278
|
+
interface FilesOptions {
|
|
279
|
+
/** "user" (default): private to the signed-in user. "org": shared with the organization. */
|
|
280
|
+
scope?: FilesScope;
|
|
281
|
+
}
|
|
282
|
+
interface PutOptions extends FilesOptions {
|
|
283
|
+
contentType?: string;
|
|
284
|
+
/** Called with bytes sent so far (browser XHR upload progress). */
|
|
285
|
+
onProgress?: (loaded: number, total: number) => void;
|
|
286
|
+
signal?: AbortSignal;
|
|
287
|
+
}
|
|
288
|
+
interface GetOptions extends FilesOptions {
|
|
289
|
+
onProgress?: (loaded: number, total: number) => void;
|
|
290
|
+
signal?: AbortSignal;
|
|
291
|
+
/** Inclusive byte range (HTTP Range), e.g. `{ start: 0, end: 1023 }` for the first KiB. */
|
|
292
|
+
range?: {
|
|
293
|
+
start: number;
|
|
294
|
+
end?: number;
|
|
295
|
+
};
|
|
296
|
+
}
|
|
297
|
+
/** Data accepted by `files.put`. */
|
|
298
|
+
type FileData = Blob | ArrayBuffer | ArrayBufferView;
|
|
299
|
+
/**
|
|
300
|
+
* `knowhow.files` scoped storage (capability `files:app`).
|
|
301
|
+
*
|
|
302
|
+
* Files live under an app-sandboxed root chosen by Knowhow (never by the app): for a website
|
|
303
|
+
* `/apps/<host[:port]>[/<app-id>]/…`, for a registered app its own folder. Paths you pass are always
|
|
304
|
+
* relative to that root; `..`, absolute paths and backslashes are rejected by the backend.
|
|
305
|
+
*/
|
|
306
|
+
declare function createFilesApi(call: FilesCall): {
|
|
307
|
+
/** Folder listing (≤ 1000 entries) of the scoped storage; `prefix` is a folder relative to the root. */
|
|
308
|
+
listScoped(prefix?: string, opts?: FilesOptions): Promise<AppFileInfo[]>;
|
|
309
|
+
stat(path: string, opts?: FilesOptions): Promise<AppFileInfo | null>;
|
|
310
|
+
delete(path: string, opts?: FilesOptions): Promise<boolean>;
|
|
311
|
+
/** Short-lived presigned download URL (usable as `<video src>`; S3 serves Range requests). */
|
|
312
|
+
url(path: string, opts?: FilesOptions): Promise<string>;
|
|
313
|
+
/** Download to a Blob (optionally a byte range) with progress. */
|
|
314
|
+
get(path: string, opts?: GetOptions): Promise<Blob>;
|
|
315
|
+
/**
|
|
316
|
+
* Upload (any size up to 2 GiB - 1 byte): asks the host for a presigned URL, PUTs the bytes straight to
|
|
317
|
+
* storage (they never pass through the provider), then verifies the upload.
|
|
318
|
+
*/
|
|
319
|
+
put(path: string, data: FileData, opts?: PutOptions): Promise<AppFileInfo>;
|
|
320
|
+
};
|
|
321
|
+
|
|
322
|
+
declare const SDK_VERSION = "0.1.0";
|
|
323
|
+
interface GetProviderOptions {
|
|
324
|
+
/** How long to wait for the parent to transfer a port (default 5000ms). */
|
|
325
|
+
handshakeTimeoutMs?: number;
|
|
326
|
+
/**
|
|
327
|
+
* When framed AND an injected (extension/desktop) provider is also present, how long to wait for
|
|
328
|
+
* the parent frame to answer before falling back to the injected provider (default 1500ms).
|
|
329
|
+
*/
|
|
330
|
+
parentProbeMs?: number;
|
|
331
|
+
/**
|
|
332
|
+
* Which host wins when both are available. "host" (default): the Knowhow page framing this app
|
|
333
|
+
* (it already knows the app, owns the side chat and the app's tools). "injected": the extension/desktop.
|
|
334
|
+
*/
|
|
335
|
+
prefer?: "host" | "injected";
|
|
336
|
+
/** Resend interval for `kh:hello` while waiting (default 250ms). */
|
|
337
|
+
helloIntervalMs?: number;
|
|
338
|
+
/** Override window (tests). */
|
|
339
|
+
window?: Window;
|
|
340
|
+
}
|
|
341
|
+
type DiscoveredKind = "embedded" | "injected";
|
|
342
|
+
interface DiscoveredProvider {
|
|
343
|
+
provider: KnowhowProvider;
|
|
344
|
+
kind: DiscoveredKind;
|
|
345
|
+
/** Announced provider name (injected only). */
|
|
346
|
+
providerName?: string;
|
|
347
|
+
}
|
|
348
|
+
/**
|
|
349
|
+
* The parent origin must be who actually frames us: `location.ancestorOrigins[0]` where available
|
|
350
|
+
* (Chromium/Safari), else the `document.referrer` origin (when it is not our own origin, i.e. we were
|
|
351
|
+
* not reached by in-app navigation). When neither is available the init message's own origin is used.
|
|
352
|
+
*/
|
|
353
|
+
declare function isTrustedParentOrigin(win: Window, origin: string): boolean;
|
|
354
|
+
/**
|
|
355
|
+
* Starts listening for the host's per-load `kh:init` (origin + nonce). Idempotent. Called when the SDK
|
|
356
|
+
* is created so the init is not missed if the app asks for the provider later than the iframe `load`.
|
|
357
|
+
*/
|
|
358
|
+
declare function watchParentInit(win: Window): void;
|
|
359
|
+
/**
|
|
360
|
+
* Discovery order (default `prefer: "host"`):
|
|
361
|
+
* - framed: parent iframe MessagePort handshake first. If an injected provider is also present the
|
|
362
|
+
* parent only gets `parentProbeMs` to answer, then we fall back to the injected provider. This keeps
|
|
363
|
+
* the extension from hijacking apps opened inside the Knowhow site (whose host owns the session,
|
|
364
|
+
* side chat and app tools), while apps framed by non-Knowhow pages still reach the extension.
|
|
365
|
+
* - top-level: announced/injected provider.
|
|
366
|
+
* - otherwise throw.
|
|
367
|
+
* `prefer: "injected"` restores injected-first.
|
|
368
|
+
* (Mock mode is handled by the `knowhow` facade.)
|
|
369
|
+
*/
|
|
370
|
+
declare function discoverProvider(opts?: GetProviderOptions): Promise<DiscoveredProvider>;
|
|
371
|
+
declare function getProvider(opts?: GetProviderOptions): Promise<KnowhowProvider>;
|
|
372
|
+
|
|
373
|
+
/** Optional pluggable DB (e.g. backed by sql.js). Receives raw method name + params. */
|
|
374
|
+
type MockDbHandler = (method: string, params: unknown) => Promise<unknown> | unknown;
|
|
375
|
+
interface MockOptions {
|
|
376
|
+
user?: {
|
|
377
|
+
displayName: string;
|
|
378
|
+
};
|
|
379
|
+
/** Provide a db implementation (e.g. sql.js) — otherwise db calls throw. */
|
|
380
|
+
db?: MockDbHandler;
|
|
381
|
+
/** Environment returned by `knowhow.app.env()` (default `{ name: "dev", vars: {} }`). */
|
|
382
|
+
env?: {
|
|
383
|
+
name: string;
|
|
384
|
+
vars?: Record<string, string>;
|
|
385
|
+
};
|
|
386
|
+
}
|
|
387
|
+
interface MockProvider extends KnowhowProvider {
|
|
388
|
+
/** Simulate the host calling an app tool. Resolves with the handler result. */
|
|
389
|
+
callTool(name: string, args?: Record<string, JsonValue>): Promise<unknown>;
|
|
390
|
+
}
|
|
391
|
+
/** In-memory provider for local development outside Knowhow. Never touches storage APIs. */
|
|
392
|
+
declare function createMockProvider(opts?: MockOptions): MockProvider;
|
|
393
|
+
|
|
394
|
+
type ToolHandler = (args: JsonObject) => Promise<JsonValue | void> | JsonValue | void;
|
|
395
|
+
interface RegisterToolInput {
|
|
396
|
+
name: string;
|
|
397
|
+
description: string;
|
|
398
|
+
/** JSON schema for the arguments. */
|
|
399
|
+
parameters: JsonObject;
|
|
400
|
+
/** True for tools that never change state (list/search/read); hosts may auto-run them without approval. */
|
|
401
|
+
readOnly?: boolean;
|
|
402
|
+
handler: ToolHandler;
|
|
403
|
+
}
|
|
404
|
+
interface CreateKnowhowOptions extends GetProviderOptions {
|
|
405
|
+
/** Custom provider factory (tests, embedding). Defaults to discovery. */
|
|
406
|
+
getProvider?: () => Promise<KnowhowProvider>;
|
|
407
|
+
/**
|
|
408
|
+
* App id or alias this app claims when connecting through an injected provider (browser extension,
|
|
409
|
+
* desktop shell). Falls back to `<meta name="knowhow-app-id">`. Ignored by iframe hosts, which
|
|
410
|
+
* already know which app they loaded. Leave it unset for a self-hosted site (no Knowhow app entry): the
|
|
411
|
+
* extension then connects the page as a site, identified by its origin.
|
|
412
|
+
*/
|
|
413
|
+
appId?: string;
|
|
414
|
+
}
|
|
415
|
+
interface ConnectOptions {
|
|
416
|
+
/** Overrides the configured / meta-tag app id for this connect call. */
|
|
417
|
+
appId?: string;
|
|
418
|
+
}
|
|
419
|
+
/** Where (if anywhere) a Knowhow host is reachable from this page. */
|
|
420
|
+
type HostKind = "embedded" | "injected" | "mock" | "none";
|
|
421
|
+
interface HostDetection {
|
|
422
|
+
kind: HostKind;
|
|
423
|
+
/** Announced provider name (injected hosts only), e.g. "Knowhow Extension". */
|
|
424
|
+
providerName?: string;
|
|
425
|
+
}
|
|
426
|
+
interface DetectOptions {
|
|
427
|
+
/** How long to wait for a late provider announcement (default 300ms). */
|
|
428
|
+
timeoutMs?: number;
|
|
429
|
+
}
|
|
430
|
+
type Listener = (data: unknown) => void;
|
|
431
|
+
declare function createKnowhow(options?: CreateKnowhowOptions): {
|
|
432
|
+
/** Resolve the provider and fetch protocol info. */
|
|
433
|
+
ready(): Promise<ProtocolResult>;
|
|
434
|
+
readonly session: SessionInfo | null;
|
|
435
|
+
/** True if the connected host supports `method` (after ready()). */
|
|
436
|
+
supports(method: string): boolean;
|
|
437
|
+
/**
|
|
438
|
+
* Ask the host for a session. Iframe hosts know the app already. Injected hosts (extension, desktop)
|
|
439
|
+
* resolve a registered app from an app id or alias — pass `{ appId }`, call `configure({ appId })`, or add
|
|
440
|
+
* the meta tag. With NO app id the extension opens a *self-hosted site* session instead: bound to the page's
|
|
441
|
+
* real origin, limited to ai:* / db:app, billed to the visitor (`session.site.origin` is set).
|
|
442
|
+
*/
|
|
443
|
+
connect: (capabilities?: Capability[], opts?: ConnectOptions) => Promise<SessionInfo>;
|
|
444
|
+
/**
|
|
445
|
+
* Set defaults before connecting. `prefer` picks the host when an app is framed by Knowhow AND an
|
|
446
|
+
* extension/desktop provider is injected: "host" (default) or "injected". Must be set before the
|
|
447
|
+
* provider is first resolved.
|
|
448
|
+
*/
|
|
449
|
+
configure(opts: {
|
|
450
|
+
appId?: string;
|
|
451
|
+
prefer?: "host" | "injected";
|
|
452
|
+
}): void;
|
|
453
|
+
/** Which host the SDK actually connected through (after ready()/detect()), or null if unresolved. */
|
|
454
|
+
readonly host: HostDetection | null;
|
|
455
|
+
/** The app id/alias that will be claimed on connect (config → meta tag), if any. */
|
|
456
|
+
readonly appId: string | undefined;
|
|
457
|
+
/**
|
|
458
|
+
* Non-throwing host detection for building a connect screen. Never prompts the user:
|
|
459
|
+
* "embedded" = inside a Knowhow iframe host, "injected" = an extension/desktop provider announced
|
|
460
|
+
* itself, "none" = standalone (offer install / open-in-Knowhow / mock). When framed this performs the
|
|
461
|
+
* (shared, non-prompting) parent handshake so it reports the host that will actually be used.
|
|
462
|
+
*/
|
|
463
|
+
detect(opts?: DetectOptions): Promise<HostDetection>;
|
|
464
|
+
disconnect(): Promise<void>;
|
|
465
|
+
db: {
|
|
466
|
+
query: (sql: string, params?: SqlParam[]) => Promise<DbQueryResult>;
|
|
467
|
+
exec: (sql: string, params?: SqlParam[]) => Promise<DbExecResult>;
|
|
468
|
+
batch: (statements: SqlStatement[]) => Promise<DbBatchResult>;
|
|
469
|
+
};
|
|
470
|
+
kv: {
|
|
471
|
+
get<T extends JsonValue = JsonValue>(key: string): Promise<T | null>;
|
|
472
|
+
set(key: string, value: JsonValue): Promise<void>;
|
|
473
|
+
delete(key: string): Promise<void>;
|
|
474
|
+
};
|
|
475
|
+
files: {
|
|
476
|
+
/**
|
|
477
|
+
* `list(prefix, { scope })` lists the scoped app storage (works for websites too).
|
|
478
|
+
* `list(path)` WITHOUT options is the legacy listing of a registered app's `data` folder.
|
|
479
|
+
*/
|
|
480
|
+
list(path?: string, opts?: FilesOptions): Promise<AppFileInfo[]>;
|
|
481
|
+
read: (path: string) => Promise<FilesReadResult>;
|
|
482
|
+
write(path: string, text: string): Promise<{
|
|
483
|
+
id: string;
|
|
484
|
+
}>;
|
|
485
|
+
stat: (path: string, opts?: FilesOptions) => Promise<AppFileInfo | null>;
|
|
486
|
+
delete: (path: string, opts?: FilesOptions) => Promise<boolean>;
|
|
487
|
+
url: (path: string, opts?: FilesOptions) => Promise<string>;
|
|
488
|
+
get: (path: string, opts?: GetOptions) => Promise<Blob>;
|
|
489
|
+
put: (path: string, data: FileData, opts?: PutOptions) => Promise<AppFileInfo>;
|
|
490
|
+
};
|
|
491
|
+
ai: {
|
|
492
|
+
complete: (params: AiCompleteParams) => Promise<AiCompleteResult>;
|
|
493
|
+
/** Speech-to-text (capability "ai:transcribe"). Audio ≤ 25 MB decoded; billed to the user's org. */
|
|
494
|
+
transcribe: (params: AiTranscribeParams) => Promise<AiTranscribeResult>;
|
|
495
|
+
/** Image generation (capability "ai:image"); `n` ≤ 4. Billed to the user's org. */
|
|
496
|
+
image: (params: AiImageParams) => Promise<AiImageResult>;
|
|
497
|
+
};
|
|
498
|
+
app: {
|
|
499
|
+
/**
|
|
500
|
+
* The environment this app runs in: `{name, vars}` ("prod" | "dev" | ...). Variables are the
|
|
501
|
+
* environment's non-secret config, read at runtime; no capability needed.
|
|
502
|
+
*/
|
|
503
|
+
env: () => Promise<AppEnvView>;
|
|
504
|
+
};
|
|
505
|
+
spend: {
|
|
506
|
+
/** This app's AI spend limit + usage for the signed-in user (no capability needed). */
|
|
507
|
+
get: () => Promise<SpendView>;
|
|
508
|
+
};
|
|
509
|
+
tools: {
|
|
510
|
+
/** Register (or replace) a tool whose handler runs in this app. */
|
|
511
|
+
register(tool: RegisterToolInput): Promise<void>;
|
|
512
|
+
unregister(name: string): Promise<void>;
|
|
513
|
+
};
|
|
514
|
+
ui: {
|
|
515
|
+
notify(message: string, level?: NotifyLevel): Promise<void>;
|
|
516
|
+
};
|
|
517
|
+
/** Subscribe to provider events (connect, disconnect, sessionChanged, message). Returns unsubscribe. */
|
|
518
|
+
on(event: string, cb: Listener): () => void;
|
|
519
|
+
/** Mock mode only: simulate the host invoking one of this app's registered tools. */
|
|
520
|
+
mockCallTool(name: string, args?: JsonObject): Promise<unknown>;
|
|
521
|
+
/** Switch to the in-memory mock provider (call before any other API). */
|
|
522
|
+
mock(opts?: MockOptions): void;
|
|
523
|
+
};
|
|
524
|
+
type KnowhowSDK = ReturnType<typeof createKnowhow>;
|
|
525
|
+
/** Default singleton. */
|
|
526
|
+
declare const knowhow: KnowhowSDK;
|
|
527
|
+
|
|
528
|
+
export { type AiImageParams, type AiImageResult, type AiImageSize, type AiTranscribeParams, type AiTranscribeResult, type AppEnvView, type AppFileInfo, CAPABILITIES, type Capability, type ConnectOptions, type CreateKnowhowOptions, type DetectOptions, type DiscoveredKind, type DiscoveredProvider, ErrorCodes, Events, type FileData, type FilesOptions, type FilesScope, type GetOptions, type GetProviderOptions, type HostDetection, type HostKind, type JsonObject, type JsonValue, type KnowhowSDK, Methods, type MockDbHandler, type MockOptions, type MockProvider, ProviderRpcError, type PutOptions, type RegisterToolInput, SDK_VERSION, type SessionInfo, type SpendLimitReachedData, type SpendView, type ToolDefinition, type ToolHandler, createFilesApi, createKnowhow, createMockProvider, discoverProvider, getProvider, isTrustedParentOrigin, knowhow, watchParentInit };
|