@kitionstage/sdk 0.0.0-stage → 0.5.2-stage.2
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 +73 -2
- package/dist/LICENSE +177 -0
- package/dist/THIRD_PARTY_NOTICES +28 -0
- package/dist/lib/assets/kitEngine.worker-3iMvwtlI.js +12732 -0
- package/dist/lib/assets/loro_wasm_bg-Gulzks_0.wasm +0 -0
- package/dist/lib/chunks/batch-BWpAyHvP.js +789 -0
- package/dist/lib/chunks/canonical-BIWfVCL-.js +87 -0
- package/dist/lib/chunks/envelope-D6MGY-ZN.js +61 -0
- package/dist/lib/chunks/replica-D8w3I4sn.js +2472 -0
- package/dist/lib/chunks/runtime-BVJHE1Pg.js +997 -0
- package/dist/lib/chunks/session-BqXC9a1-.js +281 -0
- package/dist/lib/chunks/toolIds-BCeSGHpV.js +821 -0
- package/dist/lib/chunks/workspaceTree-Destqupf.js +23 -0
- package/dist/lib/convergence/index.js +1035 -0
- package/dist/lib/convergence/node.js +8 -0
- package/dist/lib/embed-server/callbacks.js +37 -0
- package/dist/lib/embed-server/cli.js +19 -0
- package/dist/lib/embed-server/index.js +272 -0
- package/dist/lib/extensions/index.js +439 -0
- package/dist/lib/extensions/panel.html +208 -0
- package/dist/lib/extensions/runtime.js +198 -0
- package/dist/lib/extensions/sandbox.html +35 -0
- package/dist/lib/kdm/index.js +437 -0
- package/dist/lib/kit-dev-host/checkUiIds.mjs +44 -0
- package/dist/lib/kit-dev-host/index.js +308 -0
- package/dist/lib/kit-dev-host/lineRow.mjs +47 -0
- package/dist/lib/kit-dev-host/modeSmoke.mjs +178 -0
- package/dist/lib/kit-editor/index.js +6481 -0
- package/dist/lib/kit-editor/styles.css +807 -0
- package/dist/lib/kit-editor/workspaceTree.js +1 -0
- package/dist/lib/kit-engine/index.js +7 -0
- package/dist/lib/kit-host/index.js +530 -0
- package/dist/lib/kit-ui-protocol/index.js +336 -0
- package/dist/lib/node-only/embed-server-callbacks.js +2 -0
- package/dist/lib/node-only/embed-server.js +2 -0
- package/dist/lib/sync/index.js +1008 -0
- package/dist/lib/sync/openToken.js +201 -0
- package/dist/lib/sync/replicaVersions.js +51 -0
- package/dist/standalone/chunks/batch-CAGYk6m4.js +789 -0
- package/dist/standalone/chunks/client-B9xkOcvf.js +772 -0
- package/dist/standalone/chunks/collab-CTQZ9h7J.js +1022 -0
- package/dist/standalone/chunks/comment-Ds9t8xSE.js +94 -0
- package/dist/standalone/chunks/comments-uVDS8Wxp.js +41 -0
- package/dist/standalone/chunks/document-B5MMuYyN.js +324 -0
- package/dist/standalone/chunks/envelope-GX4Cynkx.js +7612 -0
- package/dist/standalone/chunks/index-BEgEEnhU.js +287 -0
- package/dist/standalone/chunks/index-EEl8hGbP.js +1967 -0
- package/dist/standalone/chunks/kits-Cp51mDlw.js +9 -0
- package/dist/standalone/chunks/replica-Di2iCPiD.js +3281 -0
- package/dist/standalone/chunks/replicaVersions-C3rJxnk9.js +50 -0
- package/dist/standalone/chunks/touched-T9jKJjxn.js +78 -0
- package/dist/standalone/index.js +12 -0
- package/dist/standalone/script/index.js +339 -0
- package/dist/standalone/script/kits/board.js +5 -0
- package/dist/standalone/script/kits/cad.js +5 -0
- package/dist/standalone/script/kits/design.js +5 -0
- package/dist/standalone/script/kits/doc.js +5 -0
- package/dist/standalone/script/kits/film.js +5 -0
- package/dist/standalone/script/kits/html.js +5 -0
- package/dist/standalone/script/kits/index.js +38 -0
- package/dist/standalone/script/kits/layout.js +5 -0
- package/dist/standalone/script/kits/motion.js +5 -0
- package/dist/standalone/script/kits/note.js +5 -0
- package/dist/standalone/script/kits/pdf.js +5 -0
- package/dist/standalone/script/kits/photo.js +5 -0
- package/dist/standalone/script/kits/scene.js +5 -0
- package/dist/standalone/script/kits/sheet.js +5 -0
- package/dist/standalone/script/kits/slide.js +5 -0
- package/dist/standalone/script/kits/table.js +5 -0
- package/dist/standalone/script/kits/vector.js +5 -0
- package/dist/standalone/script/node.js +401 -0
- package/dist/standalone/script/proxy.js +254 -0
- package/dist/types/convergence/src/adapter.d.ts +131 -0
- package/dist/types/convergence/src/engine.d.ts +66 -0
- package/dist/types/convergence/src/index.d.ts +21 -0
- package/dist/types/convergence/src/net.d.ts +52 -0
- package/dist/types/convergence/src/node.d.ts +6 -0
- package/dist/types/convergence/src/report.d.ts +56 -0
- package/dist/types/convergence/src/rng.d.ts +12 -0
- package/dist/types/convergence/src/scenarios.d.ts +15 -0
- package/dist/types/convergence/src/state.d.ts +67 -0
- package/dist/types/embed/src/agent.d.ts +88 -0
- package/dist/types/embed/src/blobs.d.ts +2 -0
- package/dist/types/embed/src/collab.d.ts +250 -0
- package/dist/types/embed/src/comments.d.ts +30 -0
- package/dist/types/embed/src/errors.d.ts +24 -0
- package/dist/types/embed/src/handlers.d.ts +92 -0
- package/dist/types/embed/src/index.d.ts +20 -0
- package/dist/types/embed/src/mount.d.ts +39 -0
- package/dist/types/embed/src/replicaStore.d.ts +3 -0
- package/dist/types/embed/src/rooms.d.ts +40 -0
- package/dist/types/embed/src/schemas.d.ts +7 -0
- package/dist/types/embed/src/syncClients.d.ts +28 -0
- package/dist/types/embed/src/theme.d.ts +7 -0
- package/dist/types/embed/src/types.d.ts +596 -0
- package/dist/types/embed/src/ui.d.ts +33 -0
- package/dist/types/embed/src/version.d.ts +2 -0
- package/dist/types/embed-server/src/callbacks.d.ts +30 -0
- package/dist/types/embed-server/src/cli.d.ts +1 -0
- package/dist/types/embed-server/src/index.d.ts +19 -0
- package/dist/types/embed-server/src/page.d.ts +15 -0
- package/dist/types/embed-server/src/server.d.ts +39 -0
- package/dist/types/embed-server/src/session.d.ts +22 -0
- package/dist/types/extensions/src/gate.d.ts +17 -0
- package/dist/types/extensions/src/generated/runtime.d.ts +8 -0
- package/dist/types/extensions/src/host.d.ts +135 -0
- package/dist/types/extensions/src/index.d.ts +13 -0
- package/dist/types/extensions/src/manifest.d.ts +82 -0
- package/dist/types/extensions/src/protocol.d.ts +159 -0
- package/dist/types/extensions/src/rpc.d.ts +52 -0
- package/dist/types/extensions/src/runtime/document.d.ts +40 -0
- package/dist/types/extensions/src/runtime/index.d.ts +10 -0
- package/dist/types/extensions/src/runtime/panel.d.ts +19 -0
- package/dist/types/extensions/src/runtime/runtime.d.ts +54 -0
- package/dist/types/extensions/src/runtime/worker.d.ts +1 -0
- package/dist/types/extensions/src/sandbox.d.ts +41 -0
- package/dist/types/kdm/src/args.d.ts +12 -0
- package/dist/types/kdm/src/batch.d.ts +118 -0
- package/dist/types/kdm/src/canonical.d.ts +25 -0
- package/dist/types/kdm/src/comment.d.ts +114 -0
- package/dist/types/kdm/src/diff.d.ts +125 -0
- package/dist/types/kdm/src/envelope.d.ts +27 -0
- package/dist/types/kdm/src/errors.d.ts +28 -0
- package/dist/types/kdm/src/footprint.d.ts +21 -0
- package/dist/types/kdm/src/ids.d.ts +57 -0
- package/dist/types/kdm/src/index.d.ts +18 -0
- package/dist/types/kdm/src/marks.d.ts +32 -0
- package/dist/types/kdm/src/op.d.ts +124 -0
- package/dist/types/kdm/src/origin.d.ts +41 -0
- package/dist/types/kdm/src/overlay.d.ts +92 -0
- package/dist/types/kdm/src/projection.d.ts +29 -0
- package/dist/types/kdm/src/read.d.ts +90 -0
- package/dist/types/kdm/src/replica.d.ts +403 -0
- package/dist/types/kdm/src/schema.d.ts +185 -0
- package/dist/types/kdm/src/testing.d.ts +28 -0
- package/dist/types/kdm/src/toolIds.d.ts +61 -0
- package/dist/types/kdm/src/touched.d.ts +24 -0
- package/dist/types/kdm/src/tx.d.ts +215 -0
- package/dist/types/kdm/src/value.d.ts +23 -0
- package/dist/types/kit-dev-host/src/checkNoPaths.d.ts +19 -0
- package/dist/types/kit-dev-host/src/checkUiIds.d.mts +2 -0
- package/dist/types/kit-dev-host/src/index.d.ts +179 -0
- package/dist/types/kit-dev-host/src/lineRow.d.mts +14 -0
- package/dist/types/kit-dev-host/src/memoryFiles.d.ts +15 -0
- package/dist/types/kit-dev-host/src/modeSmoke.d.mts +8 -0
- package/dist/types/kit-editor/src/CommandDialog.d.ts +22 -0
- package/dist/types/kit-editor/src/CommentsPanel.d.ts +45 -0
- package/dist/types/kit-editor/src/CustomizeDialog.d.ts +32 -0
- package/dist/types/kit-editor/src/HostButtons.d.ts +11 -0
- package/dist/types/kit-editor/src/RenderFailure.d.ts +7 -0
- package/dist/types/kit-editor/src/TextSink.d.ts +6 -0
- package/dist/types/kit-editor/src/brand.d.ts +2 -0
- package/dist/types/kit-editor/src/catalogMenus.d.ts +27 -0
- package/dist/types/kit-editor/src/chart.d.ts +138 -0
- package/dist/types/kit-editor/src/conflicts.d.ts +12 -0
- package/dist/types/kit-editor/src/drawing.d.ts +83 -0
- package/dist/types/kit-editor/src/editor.d.ts +544 -0
- package/dist/types/kit-editor/src/engine/KitCanvas.d.ts +70 -0
- package/dist/types/kit-editor/src/engine/backdrop.d.ts +32 -0
- package/dist/types/kit-editor/src/engine/createKitFile.d.ts +12 -0
- package/dist/types/kit-editor/src/engine/decorations.d.ts +14 -0
- package/dist/types/kit-editor/src/engine/engineOverlays.d.ts +197 -0
- package/dist/types/kit-editor/src/engine/engineTools.d.ts +116 -0
- package/dist/types/kit-editor/src/engine/kitDraft.d.ts +70 -0
- package/dist/types/kit-editor/src/engine/kitEngine.d.ts +390 -0
- package/dist/types/kit-editor/src/engine/kitEngine.worker.d.ts +30 -0
- package/dist/types/kit-editor/src/engine/kitHost.d.ts +41 -0
- package/dist/types/kit-editor/src/engine/kitModel.d.ts +32 -0
- package/dist/types/kit-editor/src/engine/kitModelRunner.d.ts +99 -0
- package/dist/types/kit-editor/src/engine/kitModule.d.ts +185 -0
- package/dist/types/kit-editor/src/engine/kitShortcuts.d.ts +32 -0
- package/dist/types/kit-editor/src/engine/kitTools.d.ts +79 -0
- package/dist/types/kit-editor/src/engine/lazyFonts.d.ts +34 -0
- package/dist/types/kit-editor/src/engine/lentFiles.d.ts +29 -0
- package/dist/types/kit-editor/src/engine/rasterViewport.d.ts +178 -0
- package/dist/types/kit-editor/src/engine/readOnly.d.ts +78 -0
- package/dist/types/kit-editor/src/engine/refusal.d.ts +39 -0
- package/dist/types/kit-editor/src/engine/replica.d.ts +23 -0
- package/dist/types/kit-editor/src/engine/useKitDocument.d.ts +154 -0
- package/dist/types/kit-editor/src/engine/workerRelay.d.ts +62 -0
- package/dist/types/kit-editor/src/files.d.ts +74 -0
- package/dist/types/kit-editor/src/frame/EditorFrame.d.ts +74 -0
- package/dist/types/kit-editor/src/frame/FocusBar.d.ts +10 -0
- package/dist/types/kit-editor/src/frame/MenuNodes.d.ts +20 -0
- package/dist/types/kit-editor/src/frame/MenuRibbon.d.ts +8 -0
- package/dist/types/kit-editor/src/frame/ModeButton.d.ts +7 -0
- package/dist/types/kit-editor/src/frame/menus.d.ts +64 -0
- package/dist/types/kit-editor/src/frame/modes.d.ts +51 -0
- package/dist/types/kit-editor/src/frame/useFrameLayout.d.ts +34 -0
- package/dist/types/kit-editor/src/host.d.ts +127 -0
- package/dist/types/kit-editor/src/index.d.ts +85 -0
- package/dist/types/kit-editor/src/ink.d.ts +26 -0
- package/dist/types/kit-editor/src/lease.d.ts +53 -0
- package/dist/types/kit-editor/src/oneInFlight.d.ts +7 -0
- package/dist/types/kit-editor/src/phrases.d.ts +25 -0
- package/dist/types/kit-editor/src/presence.d.ts +79 -0
- package/dist/types/kit-editor/src/strings.d.ts +6 -0
- package/dist/types/kit-editor/src/toolIcons.d.ts +32 -0
- package/dist/types/kit-editor/src/uiCatalog.d.ts +59 -0
- package/dist/types/kit-editor/src/uiConfig.d.ts +53 -0
- package/dist/types/kit-editor/src/uiContext.d.ts +65 -0
- package/dist/types/kit-editor/src/uiStore.d.ts +20 -0
- package/dist/types/kit-editor/src/useCommentAnchors.d.ts +29 -0
- package/dist/types/kit-editor/src/useKitSession.d.ts +115 -0
- package/dist/types/kit-editor/src/workspaceTree.d.ts +5 -0
- package/dist/types/kit-engine/src/contract.d.ts +154 -0
- package/dist/types/kit-engine/src/index.d.ts +2 -0
- package/dist/types/kit-engine/src/session.d.ts +133 -0
- package/dist/types/kit-host/src/files.d.ts +163 -0
- package/dist/types/kit-host/src/index.d.ts +315 -0
- package/dist/types/kit-ui-protocol/src/index.d.ts +1145 -0
- package/dist/types/loro-crdt.d.ts +9 -0
- package/dist/types/script/kits/board.d.ts +534 -0
- package/dist/types/script/kits/cad.d.ts +2937 -0
- package/dist/types/script/kits/design.d.ts +3213 -0
- package/dist/types/script/kits/doc.d.ts +2575 -0
- package/dist/types/script/kits/film.d.ts +4067 -0
- package/dist/types/script/kits/html.d.ts +38 -0
- package/dist/types/script/kits/index.d.ts +20 -0
- package/dist/types/script/kits/layout.d.ts +3483 -0
- package/dist/types/script/kits/motion.d.ts +4826 -0
- package/dist/types/script/kits/note.d.ts +631 -0
- package/dist/types/script/kits/pdf.d.ts +829 -0
- package/dist/types/script/kits/photo.d.ts +7574 -0
- package/dist/types/script/kits/scene.d.ts +2962 -0
- package/dist/types/script/kits/sheet.d.ts +2419 -0
- package/dist/types/script/kits/slide.d.ts +1894 -0
- package/dist/types/script/kits/table.d.ts +654 -0
- package/dist/types/script/kits/vector.d.ts +5167 -0
- package/dist/types/script/src/agentRelay.d.ts +48 -0
- package/dist/types/script/src/capabilities.d.ts +21 -0
- package/dist/types/script/src/document.d.ts +87 -0
- package/dist/types/script/src/drafts.d.ts +141 -0
- package/dist/types/script/src/exchange.d.ts +30 -0
- package/dist/types/script/src/headless.d.ts +190 -0
- package/dist/types/script/src/index.d.ts +15 -0
- package/dist/types/script/src/kitModel.d.ts +17 -0
- package/dist/types/script/src/kits.d.ts +8 -0
- package/dist/types/script/src/node.d.ts +42 -0
- package/dist/types/script/src/port.d.ts +89 -0
- package/dist/types/script/src/proxy.d.ts +132 -0
- package/dist/types/script/src/room.d.ts +162 -0
- package/dist/types/script/src/sources.d.ts +73 -0
- package/dist/types/sync/src/backoff.d.ts +9 -0
- package/dist/types/sync/src/blobSection.d.ts +23 -0
- package/dist/types/sync/src/capabilities.d.ts +20 -0
- package/dist/types/sync/src/client.d.ts +253 -0
- package/dist/types/sync/src/framing.d.ts +35 -0
- package/dist/types/sync/src/hash.d.ts +2 -0
- package/dist/types/sync/src/index.d.ts +19 -0
- package/dist/types/sync/src/leases.d.ts +82 -0
- package/dist/types/sync/src/openToken.d.ts +104 -0
- package/dist/types/sync/src/protocol.d.ts +484 -0
- package/dist/types/sync/src/relay.d.ts +52 -0
- package/dist/types/sync/src/replicaVersions.d.ts +17 -0
- package/dist/types/sync/src/saveMachine.d.ts +83 -0
- package/dist/types/sync/src/saveRun.d.ts +52 -0
- package/dist/types/sync/src/transport.d.ts +19 -0
- package/package.json +229 -4
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
import { SyncLeases } from './leases.js';
|
|
2
|
+
import { type AccountSettings, type AgentRunResult, type BlobGetResult, type BlobHasResult, type ChangesPushResult, type ClientInfo, type ExportGetResult, type HelloResult, type HistoryGetResult, type HistoryListResult, type HistoryRestoreResult, type Presence, type PreviewGetResult, type PrivateRoomCreateResult, type Role, type RoomCreateResult, type RoomListing, type RoomsListResult, type RoomJoinResult, type RoomLinkResult, type RoomMembersResult, type RoomOpenResult, type OpenScope, type RoomResolveResult, type SaveBeginResult, type SnapshotGetResult, type SnapshotPreference } from './protocol.js';
|
|
3
|
+
import type { ConnectionState, TransportFactory } from './transport.js';
|
|
4
|
+
import type { SaveFailure, SaveState, SaveTrigger } from './saveMachine.js';
|
|
5
|
+
export type { ConnectionState } from './transport.js';
|
|
6
|
+
/**
|
|
7
|
+
* How a client with no replica of a document starts (protocol 1.8): `shallow: true` asks for a
|
|
8
|
+
* shallow snapshot of the room's latest state (standard 2.0 rule M16a), `prefer: 'shallow'` lets
|
|
9
|
+
* the server choose one for a large document. A server before 1.8 answers a full snapshot.
|
|
10
|
+
*/
|
|
11
|
+
export type SnapshotStart = {
|
|
12
|
+
shallow?: boolean;
|
|
13
|
+
prefer?: SnapshotPreference;
|
|
14
|
+
};
|
|
15
|
+
export type SyncClientOptions = {
|
|
16
|
+
createTransport: TransportFactory;
|
|
17
|
+
client?: ClientInfo;
|
|
18
|
+
capabilities?: string[];
|
|
19
|
+
/**
|
|
20
|
+
* The start `snapshot` and a `join` with `since: null` ask for unless they are given their own
|
|
21
|
+
* (protocol 1.8; omitted: full snapshots). History reads go to the server either way
|
|
22
|
+
* (`history`, `historyAt`), so a shallow replica never needs its own.
|
|
23
|
+
*/
|
|
24
|
+
start?: SnapshotStart;
|
|
25
|
+
random?: () => number;
|
|
26
|
+
setTimeout?: (run: () => void, ms: number) => unknown;
|
|
27
|
+
clearTimeout?: (handle: unknown) => void;
|
|
28
|
+
};
|
|
29
|
+
type ChangeNotice = {
|
|
30
|
+
changes: Uint8Array;
|
|
31
|
+
seq?: number;
|
|
32
|
+
from?: string;
|
|
33
|
+
};
|
|
34
|
+
/** A token, or what answers one: asked again on every connection attempt, so it can refresh. */
|
|
35
|
+
export type SyncToken = string | (() => string | Promise<string>);
|
|
36
|
+
export declare class SyncClient {
|
|
37
|
+
private readonly options;
|
|
38
|
+
private url;
|
|
39
|
+
private token;
|
|
40
|
+
private transport;
|
|
41
|
+
private decoder;
|
|
42
|
+
private nextId;
|
|
43
|
+
private pending;
|
|
44
|
+
private pushQueue;
|
|
45
|
+
private joined;
|
|
46
|
+
/** The highest server `seq` seen for each joined doc (join, pull, or push ack), for re-joining
|
|
47
|
+
* after a reconnect without a KDM version of its own. */
|
|
48
|
+
private lastSeq;
|
|
49
|
+
private changesListeners;
|
|
50
|
+
private presenceListeners;
|
|
51
|
+
private accessListeners;
|
|
52
|
+
/** This person's role in each joined room, as its last join or `room/access` said. */
|
|
53
|
+
private roles;
|
|
54
|
+
private stateListeners;
|
|
55
|
+
private roomsListeners;
|
|
56
|
+
private accountListeners;
|
|
57
|
+
private resolvedListeners;
|
|
58
|
+
private saveListeners;
|
|
59
|
+
private reconnectAttempt;
|
|
60
|
+
private reconnectTimer;
|
|
61
|
+
private closed;
|
|
62
|
+
private readyForPushes;
|
|
63
|
+
private connectionState;
|
|
64
|
+
private hello;
|
|
65
|
+
constructor(options: SyncClientOptions);
|
|
66
|
+
get state(): ConnectionState;
|
|
67
|
+
/** The handshake result from the most recent successful `sync/hello`. */
|
|
68
|
+
get principal(): import("./protocol.js").Principal | undefined;
|
|
69
|
+
/**
|
|
70
|
+
* The scope of an open-token connection (protocol 1.10, RM1), from the most recent handshake:
|
|
71
|
+
* its one file generation and role; `undefined` for any other connection or before the first.
|
|
72
|
+
*/
|
|
73
|
+
get open(): OpenScope | undefined;
|
|
74
|
+
/**
|
|
75
|
+
* The room of this open-token connection's file generation (protocol 1.10, `room/resolve`);
|
|
76
|
+
* `claim: true` asks for the seed claim when it has none (an editor only, RM5).
|
|
77
|
+
*/
|
|
78
|
+
resolveRoom(claim?: boolean): Promise<RoomResolveResult>;
|
|
79
|
+
/**
|
|
80
|
+
* Starts a save of `docId`'s room (protocol 1.10, `save/begin`, D3): answers the change to write
|
|
81
|
+
* and its authors, with the room in `force-save` by this session; `conflict` while another runs.
|
|
82
|
+
*/
|
|
83
|
+
saveBegin(docId: string, trigger: SaveTrigger): Promise<SaveBeginResult>;
|
|
84
|
+
/** Ends this session's save of `seq` (protocol 1.10, `save/end`): the `version` it wrote, or why it failed. */
|
|
85
|
+
saveEnd(docId: string, seq: number, outcome: {
|
|
86
|
+
version: string;
|
|
87
|
+
} | {
|
|
88
|
+
error: SaveFailure;
|
|
89
|
+
}): Promise<void>;
|
|
90
|
+
/** Hears `docId`'s room save state change (protocol 1.10, `save/changed`). */
|
|
91
|
+
onSave(docId: string, listener: (save: SaveState) => void): () => void;
|
|
92
|
+
/** Hears the connection's file generation get its room (protocol 1.10, `room/resolved`). */
|
|
93
|
+
onRoomResolved(listener: (docId: string) => void): () => void;
|
|
94
|
+
/**
|
|
95
|
+
* Everything the server listed in its most recent `sync/hello`: protocol capabilities (`leases`,
|
|
96
|
+
* `headless`, a server's own names) and capability sets; empty before the first handshake. A
|
|
97
|
+
* reconnect may change it (a principal's plan): read it again when the state turns `online`.
|
|
98
|
+
*/
|
|
99
|
+
get capabilities(): readonly string[];
|
|
100
|
+
/**
|
|
101
|
+
* The Kition kit platform's capability sets the server serves this principal (rule CS2), such as
|
|
102
|
+
* `KitModel 1.0` and `KitCollab 1.1`: the `Name major.minor` entries of `capabilities`.
|
|
103
|
+
*/
|
|
104
|
+
get capabilitySets(): readonly string[];
|
|
105
|
+
/** Whether the server serves the capability set `set` (such as `'KitCollab 1.1'`); false before the first handshake. */
|
|
106
|
+
supports(set: string): boolean;
|
|
107
|
+
onState(listener: (state: ConnectionState) => void): () => void;
|
|
108
|
+
/**
|
|
109
|
+
* Connects and performs `sync/hello`; resolves once the handshake succeeds. A `token` function
|
|
110
|
+
* is called for every connection attempt (reconnects too), so a short-lived token is fresh.
|
|
111
|
+
*/
|
|
112
|
+
connect(url: string, token: SyncToken): Promise<HelloResult>;
|
|
113
|
+
close(): void;
|
|
114
|
+
/**
|
|
115
|
+
* Joins `docId`'s room, or re-joins it after a reconnect. `since` is the server seq the caller
|
|
116
|
+
* already has every change up to (omitted: the highest `seq` this client has itself seen for
|
|
117
|
+
* `docId`, or `null` with none yet, which asks for everything from the room's snapshot).
|
|
118
|
+
*
|
|
119
|
+
* A busy room's catch-up does not fit in one `room/join` reply, so the server pages it (`more`,
|
|
120
|
+
* Kition platform `docs/platform/reference/sync-protocol.md` section 3); this repeats `room/join` with `since` set to each page's
|
|
121
|
+
* `seq` until `more` is `false`, combining every page's `changes` into the one result this
|
|
122
|
+
* resolves with. `presence` and `role` are from the last page.
|
|
123
|
+
*
|
|
124
|
+
* A join with `since: null` (a client with no replica yet) may start from a shallow snapshot
|
|
125
|
+
* (protocol 1.8): `start` (else the client's `start` option) asks for one. The result then says
|
|
126
|
+
* `snapshot` and `shallow`, and `changes[0]` is the shallow snapshot to load as a new replica.
|
|
127
|
+
*/
|
|
128
|
+
join(docId: string, since?: number | null, start?: SnapshotStart): Promise<RoomJoinResult>;
|
|
129
|
+
leave(docId: string): void;
|
|
130
|
+
push(docId: string, changes: Uint8Array): Promise<ChangesPushResult>;
|
|
131
|
+
onChanges(docId: string, listener: (notice: ChangeNotice) => void): () => void;
|
|
132
|
+
setPresence(docId: string, state: unknown): void;
|
|
133
|
+
onPresence(docId: string, listener: (peers: Presence[]) => void): () => void;
|
|
134
|
+
/** Blobs, scoped to the document whose room uses them (protocol 1.5). */
|
|
135
|
+
/**
|
|
136
|
+
* Leases for coordinated objects (protocol 1.5, `lease/*`): `acquire`, `release`, `hold` (kept
|
|
137
|
+
* renewed), the rooms' lease lists (`list`, `onChanged`), and `mine`. `available` is false while
|
|
138
|
+
* offline or against a server that does not list the `leases` capability.
|
|
139
|
+
*/
|
|
140
|
+
readonly leases: SyncLeases;
|
|
141
|
+
readonly blobs: {
|
|
142
|
+
has: (docId: string, hashes: string[]) => Promise<BlobHasResult>;
|
|
143
|
+
put: (docId: string, data: Uint8Array, mime: string) => Promise<{
|
|
144
|
+
hash: string;
|
|
145
|
+
}>;
|
|
146
|
+
get: (docId: string, hash: string) => Promise<BlobGetResult>;
|
|
147
|
+
};
|
|
148
|
+
/**
|
|
149
|
+
* The room's snapshot, for a client with no replica yet, and the `seq` it reflects; `join` with
|
|
150
|
+
* that `seq` next. `start` (else the client's `start` option) may ask for a shallow one
|
|
151
|
+
* (protocol 1.8), which the result then says (`shallow`).
|
|
152
|
+
*/
|
|
153
|
+
snapshot(docId: string, start?: SnapshotStart): Promise<SnapshotGetResult>;
|
|
154
|
+
createRoom(docId: string, snapshot: Uint8Array, name: string, kit: string): Promise<RoomCreateResult>;
|
|
155
|
+
/**
|
|
156
|
+
* Makes a private room (protocol 1.9, `room/create` with `private: true`): it syncs the document
|
|
157
|
+
* to this person's own devices, with no share link until they mint one (`createLink`), which
|
|
158
|
+
* shares it. A server before 1.9 makes an ordinary room and answers its link.
|
|
159
|
+
*/
|
|
160
|
+
createPrivateRoom(docId: string, snapshot: Uint8Array, name: string, kit: string): Promise<PrivateRoomCreateResult | RoomCreateResult>;
|
|
161
|
+
/**
|
|
162
|
+
* One page of the rooms this person is a member of, most recently changed first (protocol 1.9,
|
|
163
|
+
* `rooms/list`); pass the answered `cursor` for the next page (`null`: none).
|
|
164
|
+
*/
|
|
165
|
+
listRooms(options?: {
|
|
166
|
+
cursor?: string;
|
|
167
|
+
limit?: number;
|
|
168
|
+
}): Promise<RoomsListResult>;
|
|
169
|
+
/** Every room this person is a member of, all pages of `listRooms`, keyed by `docId`. */
|
|
170
|
+
listAllRooms(): Promise<RoomListing[]>;
|
|
171
|
+
/**
|
|
172
|
+
* Hears this person's document list change (protocol 1.9, `rooms/changed`): `room` is the entry
|
|
173
|
+
* now, or `null` when they are no longer a member.
|
|
174
|
+
*/
|
|
175
|
+
onRoomsChanged(listener: (docId: string, room: RoomListing | null) => void): () => void;
|
|
176
|
+
/** This person's account settings on the server (protocol 1.9, `account/settings`). */
|
|
177
|
+
accountSettings(): Promise<AccountSettings>;
|
|
178
|
+
/** Changes this person's account settings (protocol 1.9, `account/update`); answers them all. */
|
|
179
|
+
updateAccountSettings(patch: Partial<AccountSettings>): Promise<AccountSettings>;
|
|
180
|
+
/** Hears this person's account settings change on any of their devices (protocol 1.9, `account/changed`). */
|
|
181
|
+
onAccountChanged(listener: (settings: AccountSettings) => void): () => void;
|
|
182
|
+
/** Resolves `shareLink` to the room it points to; `join(result.docId, ...)` actually joins it. */
|
|
183
|
+
openRoom(shareLink: string): Promise<RoomOpenResult>;
|
|
184
|
+
/** Mints another share link to `docId`'s room granting `role` (protocol 1.4, `room/link`; `commenter` since 1.6). */
|
|
185
|
+
createLink(docId: string, role: Exclude<Role, 'owner'>): Promise<RoomLinkResult>;
|
|
186
|
+
/** The room's members and working share links (protocol 1.6, `room/members`; owner or editor). */
|
|
187
|
+
members(docId: string): Promise<RoomMembersResult>;
|
|
188
|
+
/** Changes another member's role (protocol 1.6, `room/setRole`; owner only). */
|
|
189
|
+
setRole(docId: string, principalId: string, role: Exclude<Role, 'owner'>): Promise<void>;
|
|
190
|
+
/** Removes another member from the room (protocol 1.6, `room/removeMember`; owner only). */
|
|
191
|
+
removeMember(docId: string, principalId: string): Promise<void>;
|
|
192
|
+
/** Revokes one of the room's share links (protocol 1.6, `room/revokeLink`; owner only). */
|
|
193
|
+
revokeLink(docId: string, shareLink: string): Promise<void>;
|
|
194
|
+
/**
|
|
195
|
+
* Hears this person's role in `docId`'s room change (protocol 1.6, `room/access`): the owner set
|
|
196
|
+
* a new one, or removed them (`null`; the room is then no longer joined, and not re-joined on a
|
|
197
|
+
* reconnect).
|
|
198
|
+
*/
|
|
199
|
+
onAccess(docId: string, listener: (role: Role | null) => void): () => void;
|
|
200
|
+
/** The room's history checkpoints, newest first (protocol 1.5, `history/list`). */
|
|
201
|
+
history(docId: string, options?: {
|
|
202
|
+
before?: number;
|
|
203
|
+
limit?: number;
|
|
204
|
+
}): Promise<HistoryListResult>;
|
|
205
|
+
/** The document as of `seq` (protocol 1.5, `history/get`). */
|
|
206
|
+
historyAt(docId: string, seq: number): Promise<HistoryGetResult>;
|
|
207
|
+
/**
|
|
208
|
+
* Restores the joined room's document as of `seq` as one new change (protocol 1.5,
|
|
209
|
+
* `history/restore`); the change arrives as `changes/pull` like anyone else's.
|
|
210
|
+
*/
|
|
211
|
+
restore(docId: string, seq: number): Promise<HistoryRestoreResult>;
|
|
212
|
+
/**
|
|
213
|
+
* A picture of `docId`'s room as of its latest change, rendered by the kit on a server that runs
|
|
214
|
+
* kits headless (protocol 1.7, `preview/get`; the server lists `headless`).
|
|
215
|
+
*/
|
|
216
|
+
preview(docId: string, options?: {
|
|
217
|
+
page?: number;
|
|
218
|
+
size?: number;
|
|
219
|
+
}): Promise<PreviewGetResult>;
|
|
220
|
+
/** `docId`'s room as a file in `format`, saved by the kit on the server (protocol 1.7, `export/get`). */
|
|
221
|
+
exportFile(docId: string, format?: string): Promise<ExportGetResult>;
|
|
222
|
+
/**
|
|
223
|
+
* Runs an object-model batch on the joined room's document in the server's headless kit, as an
|
|
224
|
+
* agent acting for this person (protocol 1.7, `agent/run`); the change arrives as `changes/pull`.
|
|
225
|
+
*/
|
|
226
|
+
runAgent(docId: string, batch: unknown, prompt?: string): Promise<AgentRunResult>;
|
|
227
|
+
private openConnection;
|
|
228
|
+
private sendHello;
|
|
229
|
+
/** Re-joins every room this client had joined, each with the highest `seq` it last saw for it
|
|
230
|
+
* (never re-fetching history it already has), and delivers whatever catch-up changes come back.
|
|
231
|
+
* A role that changed while the connection was down (a host's new open token, an owner's change
|
|
232
|
+
* whose `room/access` notice could not arrive) is reported to `onAccess` listeners. */
|
|
233
|
+
private rejoinAll;
|
|
234
|
+
/** Sends every queued push, in order, waiting for each one to settle (or be requeued by a
|
|
235
|
+
* disconnect) before sending the next. */
|
|
236
|
+
private flushQueue;
|
|
237
|
+
private handleDisconnect;
|
|
238
|
+
private scheduleReconnect;
|
|
239
|
+
private clearReconnectTimer;
|
|
240
|
+
private setState;
|
|
241
|
+
private failPending;
|
|
242
|
+
/** Sends one push and resolves once it settles (success, failure, or being requeued by a
|
|
243
|
+
* disconnect) -- never the push's own promise, which stays pending across a requeue. */
|
|
244
|
+
private sendPush;
|
|
245
|
+
private request;
|
|
246
|
+
private sendNotification;
|
|
247
|
+
private handleFrame;
|
|
248
|
+
private handleNotification;
|
|
249
|
+
private emitChanges;
|
|
250
|
+
/** Keeps the highest server `seq` seen for `docId`, across joins, pulls, and push acks. */
|
|
251
|
+
private bumpSeq;
|
|
252
|
+
private subscribe;
|
|
253
|
+
}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The wire framing: a JSON text frame carries a message whose `bins` field says how many binary
|
|
3
|
+
* frames follow it, each a payload one of the message's `{"$bin": n}` markers points to. Mirrors
|
|
4
|
+
* `kition-sync-protocol`'s Rust `framing` module; this side builds and reads the markers rather
|
|
5
|
+
* than typed `Bin` fields, since params and results here already carry real `Uint8Array`s.
|
|
6
|
+
*/
|
|
7
|
+
export type Frame = string | Uint8Array;
|
|
8
|
+
export type Bin = {
|
|
9
|
+
$bin: number;
|
|
10
|
+
};
|
|
11
|
+
export declare function isBin(value: unknown): value is Bin;
|
|
12
|
+
/** Registers binary payloads as a message is built, handing out the `Bin` marker for each. */
|
|
13
|
+
export declare class Outgoing {
|
|
14
|
+
private readonly bins;
|
|
15
|
+
bin(data: Uint8Array): Bin;
|
|
16
|
+
/** The text frame first, then each registered payload as a binary frame, in order. */
|
|
17
|
+
finish(message: Record<string, unknown>): Frame[];
|
|
18
|
+
}
|
|
19
|
+
/** Reassembles an incoming stream of frames into complete messages; feed one frame at a time. */
|
|
20
|
+
export declare class Decoder {
|
|
21
|
+
private pendingMessage;
|
|
22
|
+
private remaining;
|
|
23
|
+
private collected;
|
|
24
|
+
/** Returns the completed message once every binary frame it declared has arrived. Throws on
|
|
25
|
+
* a frame out of sequence (never corrupts state the caller could keep feeding). */
|
|
26
|
+
feed(frame: Frame): {
|
|
27
|
+
message: Record<string, unknown>;
|
|
28
|
+
bins: Uint8Array[];
|
|
29
|
+
} | undefined;
|
|
30
|
+
private feedText;
|
|
31
|
+
private feedBinary;
|
|
32
|
+
}
|
|
33
|
+
/** Resolves one `Bin` marker against a decoded message's binary frames. */
|
|
34
|
+
export declare function readBin(value: unknown, bins: Uint8Array[]): Uint8Array;
|
|
35
|
+
export declare function readBins(values: unknown, bins: Uint8Array[]): Uint8Array[];
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@kition/sdk/sync`: the client for the open sync protocol `kition-sync/1` (Kition platform docs/platform/reference/sync-protocol.md).
|
|
3
|
+
* `SyncClient` connects over an injectable `SyncTransport`, reconnects with backoff, re-joins
|
|
4
|
+
* every joined room with the caller's latest local version, and queues pushes made while
|
|
5
|
+
* offline, flushing them in order once reconnected. `startRelay` relays one document's KDM replica
|
|
6
|
+
* to and from its room through it. `LORO_REPLICA_VERSIONS`, the version handling the relay needs,
|
|
7
|
+
* is in `@kition/sdk/sync/replicaVersions`, loaded on demand, since it loads the CRDT engine.
|
|
8
|
+
*/
|
|
9
|
+
export { capabilitySetsOf, parseCapabilitySet, servesCapabilitySet } from './capabilities.js';
|
|
10
|
+
export { blobHashCandidates, decodeBlobSection, encodeBlobSection, type BlobEntry } from './blobSection.js';
|
|
11
|
+
export { SyncClient, type SnapshotStart, type SyncClientOptions, type SyncToken } from './client.js';
|
|
12
|
+
export type { Bin, Frame } from './framing.js';
|
|
13
|
+
export { HEADLESS_CAPABILITY, OPEN_ROOMS_CAPABILITY, type OpenScope, type RoomResolveResult, type RoomResolvedParams, type SaveAuthor, type SaveBeginResult, type SaveChangedParams, SYNC_PROTOCOL, SyncRpcError, type AgentRunResult, type BlobGetResult, type BlobHasResult, type ChangesPullParams, type Checkpoint, type ChangesPushResult, type ClientInfo, type ErrorCode, type ExportGetResult, type HelloParams, type HelloResult, type HistoryGetResult, type HistoryListResult, type HistoryRestoreResult, type Lease, type Member, ROLE_RANK, type RoomAccessParams, type RoomMembersResult, type ShareLink, type LeaseChangedParams, type Presence, type PresenceUpdateParams, type PreviewGetResult, type Principal, type Role, type AccountSettings, type PrivateRoomCreateResult, type RoomCreateResult, type RoomListing, type RoomsChangedParams, type RoomsListResult, type RoomJoinResult, type RoomLinkResult, type RoomOpenResult, type ServerInfo, type SnapshotGetResult, type SnapshotPreference, } from './protocol.js';
|
|
14
|
+
export { DocumentLeases, SyncLeases, leaseHolder, scopesCollide, type LeaseHold } from './leases.js';
|
|
15
|
+
export { initialSaveState, mustSave, saveTransition, type SaveEvent, type SaveFailure, type SaveOutcome, type SaveState, type SaveStatus, type SaveTrigger } from './saveMachine.js';
|
|
16
|
+
export { classifySaveError, runSave, type SaveRun, type SaveRunOptions } from './saveRun.js';
|
|
17
|
+
export { startRelay, type Relay, type RelayOptions, type RelayReplica, type RelaySync } from './relay.js';
|
|
18
|
+
export type { ReplicaVersions } from './replicaVersions.js';
|
|
19
|
+
export type { ConnectionState, SyncTransport, TransportFactory } from './transport.js';
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Leases for coordinated objects (`kition-sync/1` 1.5, Kition platform docs/platform/reference/sync-protocol.md section 8): a
|
|
3
|
+
* session takes a short lease on a scope (a KDM object id, a kit-named scope, or `*` for the whole
|
|
4
|
+
* document) before an edit that does not merge meaningfully, and hears every room's lease list.
|
|
5
|
+
* `SyncClient.leases` is one of these, wired to the client's connection.
|
|
6
|
+
*/
|
|
7
|
+
import { type Lease } from './protocol.js';
|
|
8
|
+
/** What the lease side needs from the client it belongs to. */
|
|
9
|
+
export type LeaseLink = {
|
|
10
|
+
request: (method: string, params: Record<string, unknown>) => Promise<unknown>;
|
|
11
|
+
/** Whether the connection is up and the server listed the `leases` capability. */
|
|
12
|
+
available: () => boolean;
|
|
13
|
+
setTimeout?: (run: () => void, ms: number) => unknown;
|
|
14
|
+
clearTimeout?: (handle: unknown) => void;
|
|
15
|
+
};
|
|
16
|
+
/** A lease kept alive (`SyncLeases.hold`) until released or lost with the connection. */
|
|
17
|
+
export type LeaseHold = {
|
|
18
|
+
readonly lease: Lease;
|
|
19
|
+
/** Ends the lease (`lease/release`) and stops renewing it. */
|
|
20
|
+
release: () => Promise<void>;
|
|
21
|
+
/** Hears the lease being lost (the connection dropped, or a renewal was refused). */
|
|
22
|
+
onLost: (listener: () => void) => () => void;
|
|
23
|
+
};
|
|
24
|
+
/** The lease that holds a colliding scope, from a refused `lease/acquire` (`conflict`). */
|
|
25
|
+
export declare function leaseHolder(error: unknown): Lease | undefined;
|
|
26
|
+
/** Whether two scopes collide: equal, or either is `*` (the whole document). */
|
|
27
|
+
export declare function scopesCollide(a: string, b: string): boolean;
|
|
28
|
+
export declare class SyncLeases {
|
|
29
|
+
private readonly link;
|
|
30
|
+
private readonly lists;
|
|
31
|
+
private readonly listeners;
|
|
32
|
+
private readonly holds;
|
|
33
|
+
/** This connection's session, learned from the first lease it was granted; reset with the connection. */
|
|
34
|
+
private session;
|
|
35
|
+
constructor(link: LeaseLink);
|
|
36
|
+
/** Whether the server keeps leases and the connection is up: without, there is nobody to coordinate with. */
|
|
37
|
+
get available(): boolean;
|
|
38
|
+
/** Takes (or renews) the lease on `scope` for `ttl` ms. Rejects `conflict` (see `leaseHolder`) when another session holds it. */
|
|
39
|
+
acquire(docId: string, scope: string, ttl?: number): Promise<Lease>;
|
|
40
|
+
/** Ends this session's lease on `scope` (harmless when it holds none). */
|
|
41
|
+
release(docId: string, scope: string): Promise<void>;
|
|
42
|
+
/**
|
|
43
|
+
* Takes the lease on `scope` and renews it at half its `ttl` until `release` (or the connection
|
|
44
|
+
* drops, which loses it: the server ends a session's leases with the session). Holding a scope
|
|
45
|
+
* already held renews it and answers a new hold that replaces the old one.
|
|
46
|
+
*/
|
|
47
|
+
hold(docId: string, scope: string, ttl?: number): Promise<LeaseHold>;
|
|
48
|
+
/** The room's leases as last heard (`lease/changed`); empty before any and while offline. */
|
|
49
|
+
list(docId: string): Lease[];
|
|
50
|
+
/** Hears `docId`'s lease list each time it changes; answers an unsubscribe. */
|
|
51
|
+
onChanged(docId: string, listener: (leases: Lease[]) => void): () => void;
|
|
52
|
+
/** Whether `lease` is this connection's own. */
|
|
53
|
+
mine(lease: Lease): boolean;
|
|
54
|
+
/** `lease/changed` from the server (the client routes it here). */
|
|
55
|
+
receive(params: Record<string, unknown>): void;
|
|
56
|
+
/** The connection dropped: the server ended this session's leases, and the lists are stale. */
|
|
57
|
+
disconnected(): void;
|
|
58
|
+
/** Left `docId`'s room: its list no longer applies, and nothing there is held any more. */
|
|
59
|
+
left(docId: string): void;
|
|
60
|
+
private set;
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* One document's leases as an editor's host serves them to its kit: `acquire` holds a scope
|
|
64
|
+
* (renewed until released), `release` ends it, and `dispose` (the editor closed) releases what is
|
|
65
|
+
* still held. Without a server that keeps leases, or while offline, there is nobody to coordinate
|
|
66
|
+
* with: `acquire` answers `null` and the edit goes ahead (an edit made then lands as a conflict
|
|
67
|
+
* object if someone else held the lease meanwhile). A refusal rejects as `lease/acquire` did
|
|
68
|
+
* (`conflict` with the holder, see `leaseHolder`; `forbidden` for a viewer).
|
|
69
|
+
*/
|
|
70
|
+
export declare class DocumentLeases {
|
|
71
|
+
private readonly leases;
|
|
72
|
+
readonly docId: string;
|
|
73
|
+
private readonly holds;
|
|
74
|
+
constructor(leases: SyncLeases, docId: string);
|
|
75
|
+
acquire(scope: string, ttl?: number): Promise<Lease | null>;
|
|
76
|
+
release(scope: string): Promise<void>;
|
|
77
|
+
list(): Lease[];
|
|
78
|
+
onChanged(listener: (leases: Lease[]) => void): () => void;
|
|
79
|
+
mine(lease: Lease): boolean;
|
|
80
|
+
/** Releases every lease still held for this editor. */
|
|
81
|
+
dispose(): void;
|
|
82
|
+
}
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Open tokens (`ko1.`), managed co-editing (Kition platform docs/platform/managed-collab.md,
|
|
3
|
+
* section 1): a host signs one person's permissions on one file version; Kition Server and the
|
|
4
|
+
* kit host verify them offline against the host's public keys. The Rust twin is the
|
|
5
|
+
* `kition-open-token` crate; both are held to `crates/kition-open-token/tests/vectors.json`.
|
|
6
|
+
*
|
|
7
|
+
* `ko1.` base64url(claims JSON) `.` base64url(Ed25519 signature over the middle segment's ASCII).
|
|
8
|
+
* Uses WebCrypto (`crypto.subtle`, Ed25519 and SHA-256): browsers and Node 20+.
|
|
9
|
+
*/
|
|
10
|
+
import type { Role } from './protocol.js';
|
|
11
|
+
export declare const OPEN_TOKEN_PREFIX = "ko1.";
|
|
12
|
+
export declare const OPEN_TOKEN_TYPE = "kition-open";
|
|
13
|
+
export declare const OPEN_TOKEN_MAX_TTL = 3600;
|
|
14
|
+
export declare const OPEN_TOKEN_CLOCK_SKEW = 60;
|
|
15
|
+
/** What the person may do with the file (OT1, OT5): `edit` implies `comment`. */
|
|
16
|
+
export type OpenPerms = {
|
|
17
|
+
edit: boolean;
|
|
18
|
+
comment: boolean;
|
|
19
|
+
download: boolean;
|
|
20
|
+
share: boolean;
|
|
21
|
+
export: boolean;
|
|
22
|
+
};
|
|
23
|
+
export type OpenTokenClaims = {
|
|
24
|
+
v: 1;
|
|
25
|
+
typ: typeof OPEN_TOKEN_TYPE;
|
|
26
|
+
kid: string;
|
|
27
|
+
/** The host that signed it (`[A-Za-z0-9._-]`); its keys name it (I2). */
|
|
28
|
+
iss: string;
|
|
29
|
+
/** The Kition Server it is for (I2). */
|
|
30
|
+
aud: string;
|
|
31
|
+
tenant: string;
|
|
32
|
+
/** The person: the host's user id. */
|
|
33
|
+
sub: string;
|
|
34
|
+
name: string;
|
|
35
|
+
/** The host's immutable resource id of the file. */
|
|
36
|
+
file: string;
|
|
37
|
+
/** The host content revision the session opens. */
|
|
38
|
+
version: string;
|
|
39
|
+
/** The co-editing generation: one room per `(tenant, file, doc_key)`. */
|
|
40
|
+
doc_key: string;
|
|
41
|
+
perms: OpenPerms;
|
|
42
|
+
watermark: {
|
|
43
|
+
text: string;
|
|
44
|
+
} | null;
|
|
45
|
+
iat: number;
|
|
46
|
+
exp: number;
|
|
47
|
+
jti?: string;
|
|
48
|
+
};
|
|
49
|
+
/** A host's public key (raw 32-byte Ed25519, base64url): it signs only for `tenant`, as `iss` (OT2, I2). */
|
|
50
|
+
export type OpenTokenKey = {
|
|
51
|
+
kid: string;
|
|
52
|
+
publicKey: string;
|
|
53
|
+
tenant: string;
|
|
54
|
+
iss: string;
|
|
55
|
+
};
|
|
56
|
+
export type OpenTokenErrorCode = 'malformed' | 'version' | 'unknown-key' | 'signature' | 'issuer' | 'audience' | 'duplicate-key' | 'claims' | 'expired' | 'not-yet-valid';
|
|
57
|
+
export declare class OpenTokenError extends Error {
|
|
58
|
+
readonly code: OpenTokenErrorCode;
|
|
59
|
+
constructor(code: OpenTokenErrorCode);
|
|
60
|
+
}
|
|
61
|
+
/** Whether `tenant` is a tenant name: 2 to 40 lowercase letters, digits, and inner hyphens. */
|
|
62
|
+
export declare function isTenant(tenant: string): boolean;
|
|
63
|
+
/** Refuses a key set with two keys of one `(tenant, kid)` (I3), as the Rust crate's `HostKeys::new` does. */
|
|
64
|
+
export declare function checkOpenTokenKeys(keys: readonly OpenTokenKey[]): void;
|
|
65
|
+
/** Verifies `token` for the server `audience` at `now` (Unix seconds) against `keys` (OT3, I2); throws `OpenTokenError`. */
|
|
66
|
+
export declare function verifyOpenToken(token: string, keys: readonly OpenTokenKey[], audience: string, now?: number): Promise<OpenTokenClaims>;
|
|
67
|
+
/**
|
|
68
|
+
* The claims of `token` without checking its signature or times: for a page that shows what its
|
|
69
|
+
* token says (the watermark, which buttons to offer), never for deciding what it allows.
|
|
70
|
+
*/
|
|
71
|
+
export declare function decodeOpenToken(token: string): OpenTokenClaims;
|
|
72
|
+
/** Whether `token` is an open token by its prefix (a `ks1.` sync token is not). */
|
|
73
|
+
export declare function isOpenToken(token: unknown): token is string;
|
|
74
|
+
/** The Server principal of verified claims, `t:<tenant>:<iss>:<sub>` (I2). */
|
|
75
|
+
export declare function openTokenPrincipal(claims: Pick<OpenTokenClaims, 'tenant' | 'iss' | 'sub'>): string;
|
|
76
|
+
/** The sync role `perms` grant (OT1): `editor`, `commenter`, or `viewer`; never `owner`. */
|
|
77
|
+
export declare function openTokenRole(perms: OpenPerms): Exclude<Role, 'owner'>;
|
|
78
|
+
/**
|
|
79
|
+
* The `doc_key` of `file`'s co-editing `generation` (section 1.3): the first 32 characters of
|
|
80
|
+
* base64url(SHA-256("kition-doc-key\n" + file + "\n" + generation)).
|
|
81
|
+
*/
|
|
82
|
+
export declare function deriveDocKey(file: string, generation: number): Promise<string>;
|
|
83
|
+
/**
|
|
84
|
+
* Signs `claims` (for a host server in Node: Kition One uses the Rust crate instead) with an
|
|
85
|
+
* Ed25519 `privateKey` (a WebCrypto key with `sign`). `v`, `typ` and `kid` are set here; the
|
|
86
|
+
* claims are checked first and written with sorted keys.
|
|
87
|
+
*/
|
|
88
|
+
export declare function signOpenToken(claims: Omit<OpenTokenClaims, 'v' | 'typ' | 'kid'>, kid: string, privateKey: CryptoKey): Promise<string>;
|
|
89
|
+
/**
|
|
90
|
+
* What a kit host opens the kit with for a verified token: read-only
|
|
91
|
+
* without `edit`, comments without `comment`, the display permissions, and the watermark.
|
|
92
|
+
*/
|
|
93
|
+
export declare function openTokenDocument(claims: Pick<OpenTokenClaims, 'perms' | 'watermark'>): {
|
|
94
|
+
readOnly: boolean;
|
|
95
|
+
canComment: boolean;
|
|
96
|
+
permissions: {
|
|
97
|
+
download: boolean;
|
|
98
|
+
export: boolean;
|
|
99
|
+
share: boolean;
|
|
100
|
+
};
|
|
101
|
+
watermark: {
|
|
102
|
+
text: string;
|
|
103
|
+
} | null;
|
|
104
|
+
};
|