@ancientpantheon/khronoton-core 0.1.1 → 0.3.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/CHANGELOG.md +25 -0
- package/README.md +83 -3
- package/dist/PactCodeMirror-HQTGE2K3.js +64 -0
- package/dist/chunk-DK4CDPXH.js +379 -0
- package/dist/chunk-U3F5HEHO.js +1639 -0
- package/dist/context-BKtdrA2B.d.ts +363 -0
- package/dist/handlers/batch.d.ts +21 -0
- package/dist/handlers/batch.js +57 -0
- package/dist/handlers/context.d.ts +94 -0
- package/dist/handlers/context.js +75 -0
- package/dist/handlers/cronoton.d.ts +70 -0
- package/dist/handlers/cronoton.js +165 -0
- package/dist/handlers/execute.d.ts +30 -0
- package/dist/handlers/execute.js +227 -0
- package/dist/handlers/http.d.ts +85 -0
- package/dist/handlers/http.js +84 -0
- package/dist/handlers/index.d.ts +27 -0
- package/dist/handlers/index.js +34 -0
- package/dist/handlers/read.d.ts +29 -0
- package/dist/handlers/read.js +94 -0
- package/dist/hooks/index.d.ts +143 -0
- package/dist/hooks/index.js +2 -0
- package/dist/provider/index.d.ts +421 -0
- package/dist/provider/index.js +675 -0
- package/dist/server/executor-signers.d.ts +29 -0
- package/dist/server/executor-signers.js +60 -0
- package/dist/server/executor.d.ts +53 -0
- package/dist/server/executor.js +280 -0
- package/dist/server/index.d.ts +27 -0
- package/dist/server/index.js +51 -0
- package/dist/server/loop.d.ts +36 -0
- package/dist/server/loop.js +51 -0
- package/dist/server/pure/capability.d.ts +31 -0
- package/dist/server/pure/capability.js +63 -0
- package/dist/server/pure/fingerprint.d.ts +8 -0
- package/dist/server/pure/fingerprint.js +44 -0
- package/dist/server/pure/runtime-args.d.ts +34 -0
- package/dist/server/pure/runtime-args.js +99 -0
- package/dist/server/resolvers.d.ts +140 -0
- package/dist/server/resolvers.js +200 -0
- package/dist/server/schema.d.ts +31 -0
- package/dist/server/schema.js +93 -0
- package/dist/server/seams.d.ts +231 -0
- package/dist/server/seams.js +34 -0
- package/dist/server/store/claim.d.ts +59 -0
- package/dist/server/store/claim.js +97 -0
- package/dist/server/store/cronoton.d.ts +79 -0
- package/dist/server/store/cronoton.js +268 -0
- package/dist/server/store/errors.d.ts +26 -0
- package/dist/server/store/errors.js +40 -0
- package/dist/server/store/fires.d.ts +77 -0
- package/dist/server/store/fires.js +170 -0
- package/dist/server/store/index.d.ts +26 -0
- package/dist/server/store/index.js +33 -0
- package/dist/server/store/manual-batch.d.ts +38 -0
- package/dist/server/store/manual-batch.js +110 -0
- package/dist/server/store/mappers.d.ts +21 -0
- package/dist/server/store/mappers.js +62 -0
- package/dist/server/tick.d.ts +83 -0
- package/dist/server/tick.js +235 -0
- package/dist/server/types.d.ts +220 -0
- package/dist/server/types.js +14 -0
- package/dist/types-u_nUX1Bg.d.ts +222 -0
- package/dist/ui/index.d.ts +235 -0
- package/dist/ui/index.js +3646 -0
- package/dist/ui.css +35 -0
- package/package.json +64 -5
|
@@ -0,0 +1,421 @@
|
|
|
1
|
+
import { ReactNode } from 'react';
|
|
2
|
+
import { H as HandlerRequest, h as HandlerResponse, K as KhronotonProviderProps, i as KhronotonAdapter, j as SignerSource } from '../context-BKtdrA2B.js';
|
|
3
|
+
export { c as CancelBatchView, k as CodexSignerDescriptor, C as CommitBody, a as CommitView, l as ConfirmGate, m as ConfirmOpts, n as DEFAULT_EXPLORER_BASE, o as DEFAULT_PAGE_SIZE, p as DEFAULT_POLL_CADENCE_MS, D as DeleteView, E as EditPatch, b as EditView, d as ExecuteView, F as FiresQuery, q as FiresView, G as GetBatchView, r as GetCronotonView, s as KhronotonConfig, t as KhronotonSnapshot, L as ListCronotonsQuery, v as ListCronotonsView, R as RecoverView, w as RenderMultiTx, g as RuntimeArgs, x as ServerResolverOption, y as SignersView, S as SimulateEnvelope, e as SimulateView, f as StartBatchView, T as ToggleView, U as UseKhronotonResult, z as assertAdapter, A as emptySnapshot, u as useKhronoton } from '../context-BKtdrA2B.js';
|
|
4
|
+
export { a as CodexCronotonFireRow, C as CodexCronotonRow, M as ManualBatchView } from '../types-u_nUX1Bg.js';
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* The six injection seams the server automaton is built against.
|
|
8
|
+
*
|
|
9
|
+
* Every host-specific capability the Hub executor/store reached for directly
|
|
10
|
+
* (`@stoachain/*` runtime, the codex key resolver, the ambient SQLite handle,
|
|
11
|
+
* the audit log, the fire-mode signal, the tuning constants) is inverted here
|
|
12
|
+
* into a narrow, dependency-free contract the consumer injects. This module
|
|
13
|
+
* declares ONLY interfaces, type aliases, and the module-level default
|
|
14
|
+
* constants — no orchestration logic. It imports nothing from `@stoachain/*`
|
|
15
|
+
* and nothing from `better-sqlite3`; the carrier types
|
|
16
|
+
* (`IKadenaKeypair`, `UniversalKeypair`, `IUnsignedCommand`) are genericized
|
|
17
|
+
* and declared here so the emitted `.d.ts` carries zero external module
|
|
18
|
+
* references.
|
|
19
|
+
*/
|
|
20
|
+
/**
|
|
21
|
+
* A resolved signing keypair returned by {@link KeyResolver}.
|
|
22
|
+
*
|
|
23
|
+
* `privateKey` here is the raw signing secret (hex). Note the field-name
|
|
24
|
+
* divergence from {@link UniversalKeypair}, whose equivalent field is
|
|
25
|
+
* `secretKey`; a consumer mapping a resolver result into a signer payload must
|
|
26
|
+
* copy `privateKey -> secretKey`. `seedType` is genericized to `string`
|
|
27
|
+
* (the Hub narrowed it to a `@stoachain` seed-type union). The derived-seed
|
|
28
|
+
* WASM-signing path carries `encryptedSecretKey` + `password` through.
|
|
29
|
+
*/
|
|
30
|
+
interface IKadenaKeypair {
|
|
31
|
+
publicKey: string;
|
|
32
|
+
privateKey: string;
|
|
33
|
+
seedType: string;
|
|
34
|
+
encryptedSecretKey?: string;
|
|
35
|
+
password?: string;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Resolves signer public keys to their keypairs and enumerates the pubkeys the
|
|
39
|
+
* backing key store owns. Mirrors the Hub `CodexKeyResolver`: async lookups
|
|
40
|
+
* and a `Set<string>` membership view.
|
|
41
|
+
*/
|
|
42
|
+
interface KeyResolver {
|
|
43
|
+
/** Resolve a signer public key to its keypair; rejects if not owned. */
|
|
44
|
+
getKeyPairByPublicKey(publicKey: string): Promise<IKadenaKeypair>;
|
|
45
|
+
/** Enumerate every public key the backing store can sign for. */
|
|
46
|
+
listCodexPubs(): Promise<Set<string>>;
|
|
47
|
+
/**
|
|
48
|
+
* Optional last-resort resolution for a foreign key not in the store. A
|
|
49
|
+
* headless consumer with no interactive prompt may omit this or reject
|
|
50
|
+
* fast — a signer whose pubkey is unknown then fails at build time.
|
|
51
|
+
*/
|
|
52
|
+
requestForeignKey?(publicKey: string): Promise<string>;
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* A signer keypair as consumed by {@link ChainRuntime.universalSignTransaction}.
|
|
56
|
+
*
|
|
57
|
+
* Note `secretKey` here versus `privateKey` on {@link IKadenaKeypair}: the two
|
|
58
|
+
* carriers describe the same secret under different field names, so a consumer
|
|
59
|
+
* bridging resolver output into a signer must remap the field. `seedType` is
|
|
60
|
+
* genericized to `string`.
|
|
61
|
+
*/
|
|
62
|
+
interface UniversalKeypair {
|
|
63
|
+
publicKey: string;
|
|
64
|
+
secretKey: string;
|
|
65
|
+
seedType: string;
|
|
66
|
+
encryptedSecretKey?: string;
|
|
67
|
+
password?: string;
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* A genericized unsigned Kadena command (the Hub imported this from
|
|
71
|
+
* `@stoachain/kadena-stoic-legacy/types`). Structural shape only, so a real
|
|
72
|
+
* Kadena unsigned command satisfies it without pulling the chain dependency.
|
|
73
|
+
*/
|
|
74
|
+
interface IUnsignedCommand {
|
|
75
|
+
cmd: string;
|
|
76
|
+
hash: string;
|
|
77
|
+
sigs: Array<{
|
|
78
|
+
sig?: string;
|
|
79
|
+
} | undefined>;
|
|
80
|
+
}
|
|
81
|
+
/** The dirty-read (local simulation) result from {@link ChainRuntime}. */
|
|
82
|
+
interface DirtyReadResult {
|
|
83
|
+
result: {
|
|
84
|
+
status: string;
|
|
85
|
+
error?: {
|
|
86
|
+
message?: string;
|
|
87
|
+
};
|
|
88
|
+
data?: unknown;
|
|
89
|
+
};
|
|
90
|
+
gas?: number;
|
|
91
|
+
}
|
|
92
|
+
/** The listen (confirmation) result from {@link ChainRuntime}. */
|
|
93
|
+
interface ListenResult {
|
|
94
|
+
result: {
|
|
95
|
+
status: string;
|
|
96
|
+
error?: {
|
|
97
|
+
message?: string;
|
|
98
|
+
};
|
|
99
|
+
};
|
|
100
|
+
reqKey?: string;
|
|
101
|
+
}
|
|
102
|
+
/** A network client bound to a single Pact endpoint URL. */
|
|
103
|
+
interface ChainClient {
|
|
104
|
+
dirtyRead(tx: unknown): Promise<DirtyReadResult>;
|
|
105
|
+
submit(tx: unknown): Promise<{
|
|
106
|
+
requestKey: string;
|
|
107
|
+
}>;
|
|
108
|
+
listen(desc: unknown): Promise<ListenResult>;
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* The chain runtime seam — every `@stoachain/*` runtime value the executor
|
|
112
|
+
* reaches for, inverted into one injectable object. Ported from the Hub's
|
|
113
|
+
* private `StoachainRuntime` interface, with the ambient constants renamed to
|
|
114
|
+
* seam-neutral names: `KADENA_NETWORK -> networkId`,
|
|
115
|
+
* `STOA_AUTONOMIC_OURONETGASSTATION -> gasStationAccount`,
|
|
116
|
+
* `KADENA_NAMESPACE -> namespace`. Deliberately excludes `pollRequestKeys`
|
|
117
|
+
* (the executor confirms via `listen`, never polls).
|
|
118
|
+
*/
|
|
119
|
+
interface ChainRuntime {
|
|
120
|
+
Pact: {
|
|
121
|
+
builder: {
|
|
122
|
+
execution(code: string): unknown;
|
|
123
|
+
};
|
|
124
|
+
};
|
|
125
|
+
createClient(url: string): ChainClient;
|
|
126
|
+
isSignedTransaction(tx: unknown): boolean;
|
|
127
|
+
universalSignTransaction(tx: IUnsignedCommand, keypairs: UniversalKeypair[]): Promise<unknown>;
|
|
128
|
+
calculateAutoGasLimit(gas: number): number;
|
|
129
|
+
anuToStoa(anu: number): number;
|
|
130
|
+
getPactUrl(chainId: string): string;
|
|
131
|
+
networkId: string;
|
|
132
|
+
namespace: string;
|
|
133
|
+
gasStationAccount: string;
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* A prepared statement — the subset of the better-sqlite3 `Statement` surface
|
|
137
|
+
* the store actually calls. Declared structurally (owned here, NOT re-exported
|
|
138
|
+
* from `better-sqlite3`) so the emitted `.d.ts` references no external DB
|
|
139
|
+
* module; a real better-sqlite3 `Statement` satisfies it.
|
|
140
|
+
*/
|
|
141
|
+
interface Statement {
|
|
142
|
+
run(...params: unknown[]): {
|
|
143
|
+
changes: number;
|
|
144
|
+
lastInsertRowid: number | bigint;
|
|
145
|
+
};
|
|
146
|
+
get(...params: unknown[]): unknown;
|
|
147
|
+
all(...params: unknown[]): unknown[];
|
|
148
|
+
}
|
|
149
|
+
/**
|
|
150
|
+
* The minimal synchronous SQL handle the store and `installSchema` require —
|
|
151
|
+
* `exec` for DDL, `prepare(...)` for parameterized reads/writes. A real
|
|
152
|
+
* better-sqlite3 `Database` instance structurally satisfies this, so no
|
|
153
|
+
* `better-sqlite3` import (or `@types/better-sqlite3` dependency) leaks into
|
|
154
|
+
* the public `/server` surface. `pragma`/`transaction` are intentionally
|
|
155
|
+
* omitted — no store function needs them.
|
|
156
|
+
*/
|
|
157
|
+
interface Database {
|
|
158
|
+
exec(sql: string): unknown;
|
|
159
|
+
prepare(sql: string): Statement;
|
|
160
|
+
}
|
|
161
|
+
/** The structured event passed to an {@link OnAudit} sink. */
|
|
162
|
+
interface AuditEvent {
|
|
163
|
+
action: string;
|
|
164
|
+
result: string;
|
|
165
|
+
targetKind: string;
|
|
166
|
+
targetId: string;
|
|
167
|
+
detail: unknown;
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* Audit sink invoked on each mutating action. May be sync or async. The
|
|
171
|
+
* default is a no-op: `() => {}` — a consumer wanting an audit trail injects
|
|
172
|
+
* its own writer.
|
|
173
|
+
*/
|
|
174
|
+
type OnAudit = (event: AuditEvent) => void | Promise<void>;
|
|
175
|
+
/**
|
|
176
|
+
* Resolves a cronoton id to its effective fire mode. Strictly SYNCHRONOUS (no
|
|
177
|
+
* `Promise` in the union): better-sqlite3 is a synchronous driver and the store
|
|
178
|
+
* binds the result directly into the fire-record INSERT. A consumer needing
|
|
179
|
+
* async fire-mode resolution pre-resolves before invoking the tick.
|
|
180
|
+
*
|
|
181
|
+
* The default resolves to `'live'`. A consumer may honor a per-row
|
|
182
|
+
* `fire_mode_override = 'live'` first, then fall back to a global signal.
|
|
183
|
+
*/
|
|
184
|
+
type ResolveFireMode = (cronotonId: string) => 'test' | 'live';
|
|
185
|
+
/**
|
|
186
|
+
* Tuning knobs for the automaton. Every field maps to a module-level default
|
|
187
|
+
* constant below; a consumer passes a `Partial<Config>` and each consumer site
|
|
188
|
+
* reads `config?.<field> ?? <MODULE_DEFAULT>`, so an injected value takes
|
|
189
|
+
* effect and an omitted one falls back.
|
|
190
|
+
*
|
|
191
|
+
* `gasPriceFloor` and `ttl` are intentionally absent: the Hub never clamped
|
|
192
|
+
* gasPrice/ttl (the executor uses the per-cronoton `definition.config` values
|
|
193
|
+
* directly), so exposing them as injectable would misrepresent the behavior.
|
|
194
|
+
*/
|
|
195
|
+
interface Config {
|
|
196
|
+
tickIntervalMs: number;
|
|
197
|
+
listenTimeoutMs: number;
|
|
198
|
+
autoGasCeiling: number;
|
|
199
|
+
singleTxGasGuard: number;
|
|
200
|
+
tickBatchLimit: number;
|
|
201
|
+
manualBatch: {
|
|
202
|
+
min: number;
|
|
203
|
+
max: number;
|
|
204
|
+
intervalSeconds: number;
|
|
205
|
+
};
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* The per-request handler context + the injectable auth/confirm seam + the two
|
|
210
|
+
* gate wrappers.
|
|
211
|
+
*
|
|
212
|
+
* The consumer supplies a {@link HandlerContext} on every call: the injected DB
|
|
213
|
+
* handle, chain runtime, key resolver, and the seams the store/executor already
|
|
214
|
+
* defined in `/server` (all re-exported below so a consumer imports the whole
|
|
215
|
+
* handler contract from one entry — never redeclared here). The {@link AuthSeam}
|
|
216
|
+
* genericizes the Hub's role + fresh-confirm model into two gates: a READ gate
|
|
217
|
+
* (list/get/fires/signers + the batch stop path) and a CONFIRM gate (every
|
|
218
|
+
* mutating handler). {@link withRead} / {@link withConfirm} run the appropriate
|
|
219
|
+
* gate, short-circuit on denial, otherwise invoke the handler body and translate
|
|
220
|
+
* any thrown store error through {@link mapStoreError}.
|
|
221
|
+
*/
|
|
222
|
+
|
|
223
|
+
/** The (optional) identity a passing gate attaches for the handler body to attribute writes to. */
|
|
224
|
+
interface AuthIdentity {
|
|
225
|
+
id?: string;
|
|
226
|
+
email?: string;
|
|
227
|
+
}
|
|
228
|
+
/**
|
|
229
|
+
* A gate outcome: either a pass carrying an optional identity, or a block
|
|
230
|
+
* carrying the exact {@link HandlerResponse} the wrapper returns verbatim (a 401
|
|
231
|
+
* `admin_confirm_required` for a stale/absent confirm, a 403 for a non-admin).
|
|
232
|
+
*/
|
|
233
|
+
type AuthResult = {
|
|
234
|
+
ok: true;
|
|
235
|
+
identity?: AuthIdentity;
|
|
236
|
+
} | {
|
|
237
|
+
ok: false;
|
|
238
|
+
response: HandlerResponse;
|
|
239
|
+
};
|
|
240
|
+
/**
|
|
241
|
+
* The injectable auth/confirm contract. A trusted single-tenant consumer uses
|
|
242
|
+
* {@link defaultOpenAuth}; a stricter consumer implements both gates against its
|
|
243
|
+
* own role + confirm-modal flow. Each gate may be sync or async.
|
|
244
|
+
*/
|
|
245
|
+
interface AuthSeam {
|
|
246
|
+
/** Read tier: list/get/fires/signers + the batch get/cancel stop path. */
|
|
247
|
+
requireRead(req: HandlerRequest): AuthResult | Promise<AuthResult>;
|
|
248
|
+
/** Mutate tier: demands a fresh admin-confirm; blocks with 401/403 otherwise. */
|
|
249
|
+
requireConfirm(req: HandlerRequest): AuthResult | Promise<AuthResult>;
|
|
250
|
+
}
|
|
251
|
+
/**
|
|
252
|
+
* A sentinel a strict consumer's confirm gate (or a handler body) may THROW to
|
|
253
|
+
* signal a stale/absent confirm; the gate wrappers translate it to the canonical
|
|
254
|
+
* 401 `admin_confirm_required`. The gate may equally RETURN a blocking
|
|
255
|
+
* {@link AuthResult} — this class is the throw-based alternative.
|
|
256
|
+
*/
|
|
257
|
+
declare class NeedsConfirmError extends Error {
|
|
258
|
+
readonly code = "admin_confirm_required";
|
|
259
|
+
constructor(message?: string);
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
declare function KhronotonProvider(props: KhronotonProviderProps): ReactNode;
|
|
263
|
+
|
|
264
|
+
/**
|
|
265
|
+
* The minimal HTTP-response surface the fetch adapter needs — a status plus a
|
|
266
|
+
* JSON body reader. Defined structurally (not as the DOM `Response`) so the
|
|
267
|
+
* package typechecks without `lib:["DOM"]` and a test can inject a plain stub;
|
|
268
|
+
* the platform `fetch`'s `Response` satisfies it.
|
|
269
|
+
*/
|
|
270
|
+
interface FetchResponse {
|
|
271
|
+
readonly status: number;
|
|
272
|
+
json(): Promise<unknown>;
|
|
273
|
+
}
|
|
274
|
+
/** A decoded handler outcome: the HTTP status paired with the parsed JSON body. */
|
|
275
|
+
interface StatusResult {
|
|
276
|
+
status: number;
|
|
277
|
+
body: unknown;
|
|
278
|
+
}
|
|
279
|
+
/**
|
|
280
|
+
* Translate a `{ status, body }` handler outcome into the seam's return value:
|
|
281
|
+
* resolve the body on 2xx, throw {@link NeedsConfirmError} on a 401
|
|
282
|
+
* `admin_confirm_required`, throw `Error(body.error ?? 'HTTP {status}')`
|
|
283
|
+
* otherwise. Shared by the fetch + memory adapters so their error mapping never
|
|
284
|
+
* drifts.
|
|
285
|
+
*/
|
|
286
|
+
declare function parseHandlerResult<T>({ status, body }: StatusResult): T;
|
|
287
|
+
/**
|
|
288
|
+
* Read a {@link FetchResponse}'s JSON body and run it through
|
|
289
|
+
* {@link parseHandlerResult}. A body that fails to parse (an empty/non-JSON
|
|
290
|
+
* error page) is treated as `{}` so the status still maps to the right error.
|
|
291
|
+
*/
|
|
292
|
+
declare function parseFetchResponse<T>(res: FetchResponse): Promise<T>;
|
|
293
|
+
|
|
294
|
+
/**
|
|
295
|
+
* `createFetchAdapter` — the fetch-based reference {@link KhronotonAdapter}. It
|
|
296
|
+
* is the CLIENT side of the Phase-C handler contract: each of the 16 seam methods
|
|
297
|
+
* issues the matching `fetch` (verb + path + JSON body) against `baseUrl` — the
|
|
298
|
+
* same routes a consumer wraps its `khronoton-core/handlers` with — and parses
|
|
299
|
+
* every response through the shared {@link parseFetchResponse} status map
|
|
300
|
+
* (2xx → body; 401 `admin_confirm_required` → {@link NeedsConfirmError}; other
|
|
301
|
+
* non-2xx → `Error`). React-free: it only touches `fetch`, so a server route, a
|
|
302
|
+
* worker, or a browser can all use it.
|
|
303
|
+
*
|
|
304
|
+
* ── Confirm threading ─────────────────────────────────────────────────────────
|
|
305
|
+
* The confirm gate lives in the provider/hook layer (`runGated`, T4.5); this
|
|
306
|
+
* adapter only CARRIES the fresh-confirm signal. Each mutating method takes a
|
|
307
|
+
* trailing {@link ConfirmOpts}; when `opts.confirmed === true` the request adds a
|
|
308
|
+
* `{@link CONFIRMED_HEADER}: "1"` header the host route reads back into
|
|
309
|
+
* `req.confirmed`. Read methods send no confirm. `cancelBatch` is a deliberately
|
|
310
|
+
* confirm-free one-click stop (parity §5), so it takes no opts.
|
|
311
|
+
*/
|
|
312
|
+
|
|
313
|
+
/**
|
|
314
|
+
* The header the fetch adapter sets to `"1"` on a fresh-confirm mutating request;
|
|
315
|
+
* the consumer's route maps it back to `req.confirmed === true`.
|
|
316
|
+
*/
|
|
317
|
+
declare const CONFIRMED_HEADER = "x-khronoton-confirmed";
|
|
318
|
+
/** The minimal request init the adapter builds — a structural subset of the DOM `RequestInit`. */
|
|
319
|
+
interface FetchInit {
|
|
320
|
+
method?: string;
|
|
321
|
+
headers?: Record<string, string>;
|
|
322
|
+
body?: string;
|
|
323
|
+
}
|
|
324
|
+
/** The injectable `fetch` — the platform `fetch` satisfies it; tests pass a stub. */
|
|
325
|
+
type FetchLike = (url: string, init?: FetchInit) => Promise<FetchResponse>;
|
|
326
|
+
/** Static headers to merge onto every request: an object or a per-call factory. */
|
|
327
|
+
type HeaderSource = Record<string, string> | (() => Record<string, string>);
|
|
328
|
+
interface FetchAdapterOptions {
|
|
329
|
+
/** Override the `fetch` implementation (default: the global `fetch`). */
|
|
330
|
+
fetch?: FetchLike;
|
|
331
|
+
/** Headers merged onto every request (e.g. an auth token) — static or per-call. */
|
|
332
|
+
headers?: HeaderSource;
|
|
333
|
+
}
|
|
334
|
+
/**
|
|
335
|
+
* Build a fetch-backed {@link KhronotonAdapter} against `baseUrl` (the host's
|
|
336
|
+
* cronoton API base, e.g. `/api/admin/codex-cronotons`). Stateless — safe to
|
|
337
|
+
* construct per render or share.
|
|
338
|
+
*/
|
|
339
|
+
declare function createFetchAdapter(baseUrl: string, opts?: FetchAdapterOptions): KhronotonAdapter;
|
|
340
|
+
|
|
341
|
+
/**
|
|
342
|
+
* `createMemoryAdapter` — the in-process reference {@link KhronotonAdapter}. It is
|
|
343
|
+
* the SAME client seam the fetch adapter implements, but with NO network: instead
|
|
344
|
+
* of issuing HTTP against a host's routes, each method drives the corresponding
|
|
345
|
+
* Phase-C `/handlers` function DIRECTLY over an internal {@link HandlerContext}
|
|
346
|
+
* (an in-memory `better-sqlite3` DB + `installSchema`, an injectable
|
|
347
|
+
* `ChainRuntime`/`KeyResolver`, and {@link defaultOpenAuth}). It is the
|
|
348
|
+
* "in-process handler driver" for tests, SSR-seed, and demos — not a
|
|
349
|
+
* browser-localStorage store.
|
|
350
|
+
*
|
|
351
|
+
* ── The DB is the seam ────────────────────────────────────────────────────────
|
|
352
|
+
* `better-sqlite3` is an optional/dev dependency (native, Node-only), so the
|
|
353
|
+
* adapter never imports it — the CONSUMER injects a `db` handle. In a browser
|
|
354
|
+
* demo where `better-sqlite3` is unavailable, a consumer supplies its own
|
|
355
|
+
* `Database`-shaped handle; the adapter installs the schema on it by default
|
|
356
|
+
* (idempotent `IF NOT EXISTS` DDL) so a fresh `:memory:` db works out of the box.
|
|
357
|
+
* A pre-migrated/pre-seeded demo db passes `migrate: false`. The caller OWNS the
|
|
358
|
+
* db lifecycle (the adapter never closes an injected handle).
|
|
359
|
+
*
|
|
360
|
+
* ── Confirm threading (parity with the fetch adapter) ─────────────────────────
|
|
361
|
+
* The confirm gate lives in the provider/hook layer (`runGated`, T4.5); this
|
|
362
|
+
* adapter only CARRIES the signal. Each mutating method threads
|
|
363
|
+
* `opts?.confirmed` onto `req.confirmed`, so `defaultOpenAuth.requireConfirm`
|
|
364
|
+
* passes only when a fresh confirm accompanied the call — exactly like the fetch
|
|
365
|
+
* adapter's header. Read methods (and the confirm-free `getBatch`/`cancelBatch`)
|
|
366
|
+
* set no confirm. Every handler's `{ status, body }` envelope runs through the
|
|
367
|
+
* SHARED {@link parseHandlerResult} (2xx → body; 401 `admin_confirm_required` →
|
|
368
|
+
* {@link NeedsConfirmError}; other non-2xx → `Error`), so the memory + fetch
|
|
369
|
+
* adapters map outcomes identically — no drift.
|
|
370
|
+
*/
|
|
371
|
+
|
|
372
|
+
/** The seams a consumer injects when building an in-process adapter. */
|
|
373
|
+
interface MemoryAdapterOptions {
|
|
374
|
+
/**
|
|
375
|
+
* The in-process store handle — a `better-sqlite3` `Database` in Node, or any
|
|
376
|
+
* `Database`-shaped handle a consumer supplies (the adapter never imports
|
|
377
|
+
* `better-sqlite3` itself, keeping the module browser-safe).
|
|
378
|
+
*/
|
|
379
|
+
db: Database;
|
|
380
|
+
/** Run `installSchema` on `db` before first use (default `true`; `false` for a pre-migrated db). */
|
|
381
|
+
migrate?: boolean;
|
|
382
|
+
/**
|
|
383
|
+
* The chain runtime the execution handlers drive. Default: a throwing stub —
|
|
384
|
+
* read/lifecycle/batch ops never touch it, but `simulate`/`executeNow`/
|
|
385
|
+
* `trigger` require a real (or mock) runtime, so inject one to exercise them.
|
|
386
|
+
*/
|
|
387
|
+
runtime?: ChainRuntime;
|
|
388
|
+
/** The key resolver the signer projection reads. Default: an empty (no-signer) resolver. */
|
|
389
|
+
resolver?: KeyResolver;
|
|
390
|
+
resolveFireMode?: ResolveFireMode;
|
|
391
|
+
onAudit?: OnAudit;
|
|
392
|
+
config?: Partial<Config>;
|
|
393
|
+
/** The auth/confirm seam. Default {@link defaultOpenAuth} (trusted single-tenant). */
|
|
394
|
+
auth?: AuthSeam;
|
|
395
|
+
/** A richer signer source (else the default reads the resolver's owned pubs). */
|
|
396
|
+
signers?: SignerSource;
|
|
397
|
+
}
|
|
398
|
+
/**
|
|
399
|
+
* Build an in-process {@link KhronotonAdapter}. Constructing it touches neither
|
|
400
|
+
* `window` nor the network, so it is safe to build during a server render, a
|
|
401
|
+
* test, or an SSR seed. The returned adapter shares one {@link HandlerContext}:
|
|
402
|
+
* every method assembles the matching {@link HandlerRequest} and calls the real
|
|
403
|
+
* handler, then maps `{ status, body }` through {@link parseHandlerResult}.
|
|
404
|
+
*/
|
|
405
|
+
declare function createMemoryAdapter(opts: MemoryAdapterOptions): KhronotonAdapter;
|
|
406
|
+
|
|
407
|
+
/** The confirm-gated call: the provider threads the fresh-confirm signal in. */
|
|
408
|
+
type GatedFn<T> = (opts: {
|
|
409
|
+
confirmed: boolean;
|
|
410
|
+
}) => Promise<T>;
|
|
411
|
+
interface RunGatedOptions {
|
|
412
|
+
/**
|
|
413
|
+
* The host re-confirm gate. Resolves `true` when the user re-confirms after an
|
|
414
|
+
* expiry (triggering the single retry) and `false` on cancel. When omitted, an
|
|
415
|
+
* expired confirm surfaces without a retry.
|
|
416
|
+
*/
|
|
417
|
+
onNeedConfirm?: () => Promise<boolean>;
|
|
418
|
+
}
|
|
419
|
+
declare function runGated<T>(fn: GatedFn<T>, options?: RunGatedOptions): Promise<T>;
|
|
420
|
+
|
|
421
|
+
export { CONFIRMED_HEADER, type FetchAdapterOptions, type FetchLike, type FetchResponse, type GatedFn, KhronotonAdapter, KhronotonProvider, KhronotonProviderProps, type MemoryAdapterOptions, NeedsConfirmError, type RunGatedOptions, type StatusResult, createFetchAdapter, createMemoryAdapter, parseFetchResponse, parseHandlerResult, runGated };
|