akribes 0.21.17

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.
Files changed (100) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/LICENSE +21 -0
  3. package/README.md +160 -0
  4. package/dist/client.d.ts +240 -0
  5. package/dist/client.d.ts.map +1 -0
  6. package/dist/client.js +272 -0
  7. package/dist/client.js.map +1 -0
  8. package/dist/errors.d.ts +196 -0
  9. package/dist/errors.d.ts.map +1 -0
  10. package/dist/errors.js +274 -0
  11. package/dist/errors.js.map +1 -0
  12. package/dist/execution/index.d.ts +3 -0
  13. package/dist/execution/index.d.ts.map +1 -0
  14. package/dist/execution/index.js +3 -0
  15. package/dist/execution/index.js.map +1 -0
  16. package/dist/execution/replay.d.ts +37 -0
  17. package/dist/execution/replay.d.ts.map +1 -0
  18. package/dist/execution/replay.js +59 -0
  19. package/dist/execution/replay.js.map +1 -0
  20. package/dist/execution/steps.d.ts +327 -0
  21. package/dist/execution/steps.d.ts.map +1 -0
  22. package/dist/execution/steps.js +1068 -0
  23. package/dist/execution/steps.js.map +1 -0
  24. package/dist/http.d.ts +53 -0
  25. package/dist/http.d.ts.map +1 -0
  26. package/dist/http.js +141 -0
  27. package/dist/http.js.map +1 -0
  28. package/dist/index.d.ts +36 -0
  29. package/dist/index.d.ts.map +1 -0
  30. package/dist/index.js +38 -0
  31. package/dist/index.js.map +1 -0
  32. package/dist/runStream.d.ts +176 -0
  33. package/dist/runStream.d.ts.map +1 -0
  34. package/dist/runStream.js +408 -0
  35. package/dist/runStream.js.map +1 -0
  36. package/dist/sse.d.ts +46 -0
  37. package/dist/sse.d.ts.map +1 -0
  38. package/dist/sse.js +218 -0
  39. package/dist/sse.js.map +1 -0
  40. package/dist/sub/bench.d.ts +182 -0
  41. package/dist/sub/bench.d.ts.map +1 -0
  42. package/dist/sub/bench.js +420 -0
  43. package/dist/sub/bench.js.map +1 -0
  44. package/dist/sub/channels.d.ts +22 -0
  45. package/dist/sub/channels.d.ts.map +1 -0
  46. package/dist/sub/channels.js +32 -0
  47. package/dist/sub/channels.js.map +1 -0
  48. package/dist/sub/clients.d.ts +79 -0
  49. package/dist/sub/clients.d.ts.map +1 -0
  50. package/dist/sub/clients.js +190 -0
  51. package/dist/sub/clients.js.map +1 -0
  52. package/dist/sub/documents.d.ts +113 -0
  53. package/dist/sub/documents.d.ts.map +1 -0
  54. package/dist/sub/documents.js +329 -0
  55. package/dist/sub/documents.js.map +1 -0
  56. package/dist/sub/evals.d.ts +71 -0
  57. package/dist/sub/evals.d.ts.map +1 -0
  58. package/dist/sub/evals.js +86 -0
  59. package/dist/sub/evals.js.map +1 -0
  60. package/dist/sub/events.d.ts +65 -0
  61. package/dist/sub/events.d.ts.map +1 -0
  62. package/dist/sub/events.js +154 -0
  63. package/dist/sub/events.js.map +1 -0
  64. package/dist/sub/executions.d.ts +255 -0
  65. package/dist/sub/executions.d.ts.map +1 -0
  66. package/dist/sub/executions.js +322 -0
  67. package/dist/sub/executions.js.map +1 -0
  68. package/dist/sub/mcp.d.ts +51 -0
  69. package/dist/sub/mcp.d.ts.map +1 -0
  70. package/dist/sub/mcp.js +42 -0
  71. package/dist/sub/mcp.js.map +1 -0
  72. package/dist/sub/projects.d.ts +73 -0
  73. package/dist/sub/projects.d.ts.map +1 -0
  74. package/dist/sub/projects.js +101 -0
  75. package/dist/sub/projects.js.map +1 -0
  76. package/dist/sub/scripts.d.ts +58 -0
  77. package/dist/sub/scripts.d.ts.map +1 -0
  78. package/dist/sub/scripts.js +82 -0
  79. package/dist/sub/scripts.js.map +1 -0
  80. package/dist/sub/tokens.d.ts +126 -0
  81. package/dist/sub/tokens.d.ts.map +1 -0
  82. package/dist/sub/tokens.js +105 -0
  83. package/dist/sub/tokens.js.map +1 -0
  84. package/dist/sub/versions.d.ts +29 -0
  85. package/dist/sub/versions.d.ts.map +1 -0
  86. package/dist/sub/versions.js +52 -0
  87. package/dist/sub/versions.js.map +1 -0
  88. package/dist/tokenSafety.d.ts +15 -0
  89. package/dist/tokenSafety.d.ts.map +1 -0
  90. package/dist/tokenSafety.js +24 -0
  91. package/dist/tokenSafety.js.map +1 -0
  92. package/dist/types.d.ts +1147 -0
  93. package/dist/types.d.ts.map +1 -0
  94. package/dist/types.js +132 -0
  95. package/dist/types.js.map +1 -0
  96. package/dist/workflowEvents.d.ts +297 -0
  97. package/dist/workflowEvents.d.ts.map +1 -0
  98. package/dist/workflowEvents.js +612 -0
  99. package/dist/workflowEvents.js.map +1 -0
  100. package/package.json +57 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,30 @@
1
+ # Changelog
2
+
3
+ All notable changes to `akribes` (TypeScript SDK) will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the package follows [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [0.21.16] — 2026-05-30
8
+
9
+ First public release of the TypeScript SDK.
10
+
11
+ ### Added
12
+ - Pure-ESM `AkribesClient`, browser-safe (only the global `fetch` and
13
+ `EventSource`).
14
+ - Resource sub-clients: `projects`, `scripts`, `versions`, `executions`,
15
+ `events`, `documents`, `tokens`, `evals`, `mcp`, `drafts`, `clients`.
16
+ - Typed streaming via `createRunStream` with discriminated-union events
17
+ and a `subscribe-before-POST` flow that avoids missed events on the
18
+ start edge.
19
+ - Document ingest with hash-deduped server-side storage.
20
+ - Long-lived event subscription with heartbeat and `onHeartbeatStatus`
21
+ callback for browser re-auth.
22
+ - Typed errors (`AkribesError`, `AkribesAuthError`, `AkribesNotFoundError`,
23
+ `AkribesRateLimitError`, `AkribesTransientError`, `AkribesScriptError`,
24
+ `AkribesTimeoutError`).
25
+ - Full `.d.ts` types ship; the package is `"type": "module"` only.
26
+
27
+ ### Server compatibility
28
+
29
+ Targets akribes-server v0.21.16. Accepts both the new `akribes_tk_…`
30
+ scoped-token prefix and the legacy `aura_tk_…` prefix.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Podesta
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,160 @@
1
+ # akribes
2
+
3
+ TypeScript / Bun client SDK for the [Akribes](https://akribes.ai) workflow server.
4
+
5
+ Akribes is a domain-specific language and execution platform for AI workflows — multi-agent, multi-step processes with type-checked inputs, structured outputs, and a real-time event stream. This package is the typed client; you author `.akr` workflows and the server runs them.
6
+
7
+ Browser-safe: zero Node-only deps, only the global `fetch` and `EventSource`.
8
+
9
+ ## Install
10
+
11
+ ```bash
12
+ npm install akribes
13
+ # or
14
+ bun add akribes
15
+ ```
16
+
17
+ ## Quickstart
18
+
19
+ ```ts
20
+ import { AkribesClient } from "akribes";
21
+
22
+ const client = new AkribesClient({
23
+ baseUrl: "https://akribes.example.com",
24
+ projectId: 2,
25
+ token: process.env.AKRIBES_SERVICE_TOKEN!,
26
+ });
27
+
28
+ // List projects
29
+ const projects = await client.projects.list();
30
+ for (const p of projects) console.log(`${p.id}: ${p.name}`);
31
+
32
+ // Run a workflow and await the result
33
+ const { execution_id } = await client.executions.run("my_script");
34
+ const result = await client.executions.awaitExecution(execution_id);
35
+ console.log(result);
36
+ ```
37
+
38
+ ## Authentication
39
+
40
+ `AkribesClient` accepts either a **service token** (long-lived, from
41
+ `AKRIBES_SERVICE_TOKEN_<NAME>=<scope>:<secret>`) or a **scoped token**
42
+ (`akribes_tk_...` — legacy `aura_tk_...` still accepted — minted via
43
+ `client.tokens.mint(...)`).
44
+
45
+ - **Backend / CLI**: pass the service-token secret directly.
46
+ - **Browser**: never ship a service token. Mint a short-lived scoped
47
+ token server-side and hand it to the browser:
48
+
49
+ ```ts
50
+ // Server side, with a service token.
51
+ const minted = await backendClient.tokens.mint({
52
+ user_email: "alice@acme.com",
53
+ scopes: { projects: 2, role: "editor" },
54
+ expires_in: 8 * 3600,
55
+ label: "web-session",
56
+ });
57
+ // `minted.token` is the `akribes_tk_…` string to ship to the browser.
58
+
59
+ // Browser side.
60
+ const client = new AkribesClient({
61
+ baseUrl: "https://akribes.example.com",
62
+ projectId: 2,
63
+ token: mintedTokenFromBackend,
64
+ onHeartbeatStatus: (status) => {
65
+ // Prompt for re-auth when the token is revoked / expires.
66
+ if (status === "auth_failed") promptRelogin();
67
+ },
68
+ });
69
+ ```
70
+
71
+ See the [auth docs](https://akribes.ai/docs/authentication) for the full two-tier token model.
72
+
73
+ ### Prefer `Authorization: Bearer` over `?token=…` (#789)
74
+
75
+ The SDK ships the bearer token in the `Authorization` header on every
76
+ HTTP call and on its WebSocket upgrade — the recommended path for any
77
+ non-browser caller. The `?token=…` query-string fallback exists only
78
+ because browser `EventSource` / `WebSocket` constructors cannot set
79
+ arbitrary headers; treat it as a browser-only escape hatch.
80
+
81
+ Reasons to avoid query-string tokens for CLIs, backends, and scripts:
82
+
83
+ - Reverse proxies (nginx, Ingress, CDN) log the full URL, including
84
+ the token, in access logs by default.
85
+ - Browsers leak `?token=` in the `Referer` header on cross-origin
86
+ sub-resource requests originating from the same page.
87
+ - CI runners (Forgejo / GitHub Actions) echo `curl` command-lines into
88
+ job logs.
89
+ - HTTP error responses and OTel spans sometimes capture `url.full`.
90
+
91
+ The server stamps `X-Token-Source: query-param` on responses to any
92
+ request that used the query fallback, so operators can chart adoption
93
+ away from the query form without having to log the token.
94
+
95
+ ## Streaming execution
96
+
97
+ `runStream` yields typed events as the workflow executes:
98
+
99
+ ```ts
100
+ import { createRunStream } from "akribes";
101
+
102
+ const run = await createRunStream({
103
+ scriptName: "summarize",
104
+ inputs: { brief: "Distill the attached doc into 3 bullets." },
105
+ starter: client.executions,
106
+ events: client.events,
107
+ });
108
+
109
+ run.on.output((chunk) => process.stdout.write(chunk.chunk));
110
+ run.on.error((e) => console.error("Workflow failed:", e.message));
111
+
112
+ const result = await run.output();
113
+ console.log("Final result:", result);
114
+ ```
115
+
116
+ ## Document ingest
117
+
118
+ Upload a document and run a workflow against it without re-uploading on
119
+ each retry — `documents.ingest` is hash-deduped server-side:
120
+
121
+ ```ts
122
+ import { readFile } from "node:fs/promises";
123
+
124
+ const data = await readFile("./contract.pdf");
125
+ const { documentId } = await client.documents.ingest("contract.pdf", data);
126
+
127
+ const { execution_id } = await client.executions.run("extract_clauses", {
128
+ inputs: { doc: documentId },
129
+ });
130
+ ```
131
+
132
+ ## Browser usage
133
+
134
+ Scoped tokens only — never expose a service token client-side. Rotate
135
+ via `setToken()` after re-auth, and call `clients.resumeHeartbeat()` if
136
+ you wired `onHeartbeatStatus` and paused on `auth_failed`:
137
+
138
+ ```ts
139
+ client.setToken(newToken);
140
+ client.clients.resumeHeartbeat();
141
+ ```
142
+
143
+ ## Examples
144
+
145
+ See [`examples/`](./examples) for runnable scripts:
146
+
147
+ - `quick_start.ts` — minimal projects/run/await flow.
148
+ - `run_stream.ts` — streaming with the subscribe-before-POST race avoidance.
149
+ - `document_upload.ts` — `client.documents.ingest` + run.
150
+ - `with_scoped_token.ts` — mint + browser-style usage.
151
+ - `with_otel.ts` — OpenTelemetry W3C trace propagation.
152
+
153
+ ## Documentation
154
+
155
+ - Source mirror: <https://github.com/PodestaAI/akribes-sdks>
156
+ - Language guide: <https://akribes.ai/docs>
157
+
158
+ ## License
159
+
160
+ MIT. See [`LICENSE`](./LICENSE).
@@ -0,0 +1,240 @@
1
+ import { HttpClient, type TracePropagator } from './http';
2
+ import { ProjectsClient } from './sub/projects';
3
+ import { ScriptsClient } from './sub/scripts';
4
+ import { VersionsClient } from './sub/versions';
5
+ import { ChannelsClient } from './sub/channels';
6
+ import { ExecutionsClient } from './sub/executions';
7
+ import { DocumentsClient } from './sub/documents';
8
+ import { ClientsClient, type HeartbeatStatus } from './sub/clients';
9
+ import { TokensClient } from './sub/tokens';
10
+ import { EventsClient } from './sub/events';
11
+ import { EvalsClient } from './sub/evals';
12
+ import { BenchClient } from './sub/bench';
13
+ import { McpClient } from './sub/mcp';
14
+ import type { ConvertResult, EngineEvent } from './types';
15
+ export type AkribesClientOptions = {
16
+ baseUrl: string;
17
+ /**
18
+ * Bearer token sent on every request. There are two valid kinds:
19
+ *
20
+ * 1. **Service token** — the secret part of `AKRIBES_SERVICE_TOKEN_<NAME>=<scope>:<secret>`
21
+ * from the server's env. Long-lived, never expires, full Admin within
22
+ * its project scope. Use this from a trusted backend (e.g. puto's
23
+ * server-side code).
24
+ * 2. **Scoped token** — `akribes_tk_...` (legacy `aura_tk_...` still
25
+ * accepted) minted at runtime via
26
+ * `akribes.tokens.mint()`. Short-lived, revokable, has a `user_email`
27
+ * attached. Use this in browsers, CLIs, or any context where you don't
28
+ * want to expose a long-lived secret.
29
+ *
30
+ * Update this at runtime via `setToken()` after refreshing.
31
+ */
32
+ token?: string;
33
+ projectId?: number;
34
+ name?: string;
35
+ id?: string;
36
+ /**
37
+ * Email sent as `X-Akribes-User` header for metrics attribution. Only
38
+ * honored for service tokens — when a backend with a service token makes
39
+ * calls on behalf of an end user, set this so usage shows up against that
40
+ * user. (Servers also accept the legacy `X-Aura-User` form for backwards
41
+ * compat with pre-rebrand clients, but new code should not rely on that.)
42
+ *
43
+ * **This header does not grant any permissions.** Authorization is purely
44
+ * based on the bearer token's scope.
45
+ */
46
+ onBehalfOf?: string;
47
+ /**
48
+ * Optional W3C trace-context propagator. When set, the SDK invokes it on
49
+ * every outbound request so the carrier is populated with `traceparent`
50
+ * (and optionally `tracestate`) headers. The SDK has zero OpenTelemetry
51
+ * runtime dependencies; callers pass in an `@opentelemetry/api`-based
52
+ * injector from their own setup:
53
+ *
54
+ * ```ts
55
+ * import { propagation, context } from '@opentelemetry/api';
56
+ * new AkribesClient({
57
+ * ...,
58
+ * propagator: (carrier) => propagation.inject(context.active(), carrier),
59
+ * });
60
+ * ```
61
+ *
62
+ * Leaving this unset is fine — the server doesn't require a traceparent.
63
+ */
64
+ propagator?: TracePropagator;
65
+ /**
66
+ * Default poll budget for `documents.ingest()` when the per-call
67
+ * `pollTimeoutMs` is omitted. Resolution order at construction:
68
+ *
69
+ * 1. This option, if set.
70
+ * 2. `process.env.AKRIBES_SDK_INGEST_TIMEOUT_SECS` × 1000 (Node/Bun only;
71
+ * ignored in browsers and when zero/unparseable).
72
+ * 3. `DEFAULT_INGEST_POLL_TIMEOUT_MS` (1 200 000 ms = 20 min).
73
+ *
74
+ * Per-call `IngestOptions.pollTimeoutMs` always wins over this default.
75
+ */
76
+ ingestPollTimeoutMs?: number;
77
+ /**
78
+ * Invoked when the background heartbeat transitions between states (`ok`,
79
+ * `unreachable`, `auth_failed`). Fired once per transition — not once per
80
+ * 30s tick — so a UI can prompt for re-auth on `auth_failed` without an
81
+ * endless flood of warnings. After receiving `auth_failed`, the heartbeat
82
+ * stops ticking; call {@link setToken} with a fresh token and then
83
+ * {@link AkribesClient.clients}`.resumeHeartbeat()` to revive it.
84
+ *
85
+ * Resolves #1220 (TS heartbeat silently logged 401/403 forever) and
86
+ * #1182 (heartbeat backoff parity across SDKs).
87
+ */
88
+ onHeartbeatStatus?: (status: HeartbeatStatus) => void;
89
+ };
90
+ /**
91
+ * Akribes client.
92
+ *
93
+ * **Auth quickstart**:
94
+ *
95
+ * ```ts
96
+ * // Backend → talk to akribes-server with your service token
97
+ * const akribes = new AkribesClient({
98
+ * baseUrl: 'https://akribes.example.com',
99
+ * token: process.env.AKRIBES_SERVICE_TOKEN!, // <scope>:<secret>'s secret part
100
+ * onBehalfOf: 'customer@acme.com', // optional, for metrics
101
+ * projectId: 2,
102
+ * });
103
+ *
104
+ * // Browser → use a scoped token your backend minted via akribes.tokens.mint()
105
+ * const akribes = new AkribesClient({
106
+ * baseUrl: 'https://akribes.example.com',
107
+ * token: 'akribes_tk_xxxx', // expires, revokable
108
+ * projectId: 2,
109
+ * });
110
+ * ```
111
+ *
112
+ * See {@link TokensClient} for minting/listing/revoking scoped tokens.
113
+ */
114
+ export declare class AkribesClient {
115
+ private options;
116
+ private http;
117
+ private token;
118
+ private _projectId;
119
+ private _projects;
120
+ private _scripts?;
121
+ private _versions?;
122
+ private _channels?;
123
+ private _executions?;
124
+ private _documents?;
125
+ private _clients?;
126
+ private _tokens;
127
+ private _events;
128
+ private _evals?;
129
+ private _bench?;
130
+ private _mcp?;
131
+ private _state;
132
+ private _adHocDisposers;
133
+ constructor(options: AkribesClientOptions);
134
+ private initProjectScoped;
135
+ private requireProjectScoped;
136
+ get projects(): ProjectsClient;
137
+ get scripts(): ScriptsClient;
138
+ get versions(): VersionsClient;
139
+ get channels(): ChannelsClient;
140
+ get executions(): ExecutionsClient;
141
+ get documents(): DocumentsClient;
142
+ get clients(): ClientsClient;
143
+ get tokens(): TokensClient;
144
+ /** Hub event subscriptions. Always available — non-project-scoped clients
145
+ * receive the global stream (filtered to what the token can see). */
146
+ get events(): EventsClient;
147
+ get evals(): EvalsClient;
148
+ get bench(): BenchClient;
149
+ get mcp(): McpClient;
150
+ get state(): StateClient;
151
+ /**
152
+ * @deprecated Prefer `client.documents.ingest(filename, bytes, opts)`, which
153
+ * hash-first-dedups against the server's blob cache and supports progress
154
+ * callbacks. The legacy `/convert` endpoint remains functional for now.
155
+ *
156
+ * Convert a document file to Markdown via Docling.
157
+ *
158
+ * When the client is constructed with a `projectId`, the persisted document
159
+ * is owned by that project and the returned `document_id` can be passed back
160
+ * as a document input on subsequent runs to skip re-upload + reconversion.
161
+ * Without a `projectId`, the document (if S3-persisted) has no project owner
162
+ * and can only be accessed by service tokens. */
163
+ convert(file: Blob | File, opts?: {
164
+ signal?: AbortSignal;
165
+ }): Promise<ConvertResult>;
166
+ /** Fetch the caller's per-user sandbox project id (creates one on the
167
+ * server if missing). Use this to subscribe to ad-hoc events *before*
168
+ * calling `runAdHoc()` so the first engine events aren't missed. */
169
+ getSandboxProjectId(opts?: {
170
+ signal?: AbortSignal;
171
+ }): Promise<number>;
172
+ /** Execute raw .akr source ad-hoc. Server runs it in the caller's
173
+ * per-user sandbox project and returns the execution_id + project_id.
174
+ *
175
+ * `channel` and `triggeredBy` (#1120) match the Python SDK's `run_adhoc`
176
+ * parameters: `channel` selects the published-version channel to resolve
177
+ * `use foo` references against (default: server's default channel);
178
+ * `triggeredBy` is an opaque identifier recorded with the execution. */
179
+ runAdHoc(source: string, opts?: {
180
+ inputs?: Record<string, unknown>;
181
+ breakpointLines?: number[];
182
+ channel?: string;
183
+ triggeredBy?: string;
184
+ signal?: AbortSignal;
185
+ }): Promise<{
186
+ execution_id: string;
187
+ project_id: number;
188
+ }>;
189
+ /** Stream events from ad-hoc executions in the given sandbox project.
190
+ *
191
+ * Pass the `project_id` returned from `runAdHoc()` (or
192
+ * `getSandboxProjectId()`). Returns an unsubscribe function.
193
+ *
194
+ * **Avoiding the subscribe-after-POST race.** A fast workflow
195
+ * (single-digit-millisecond mock providers) can emit `NodeStart`,
196
+ * `TaskStart`, … before a naive `runAdHoc().then(onAdHocExecution)` has
197
+ * the SSE subscriber attached on the server side, dropping those opening
198
+ * events on the broadcast channel. To eliminate the race, pass an
199
+ * `opts.onReady` callback — it fires once the SSE `GET /events` response
200
+ * is open (status 2xx) — and only POST `/execute` after it resolves:
201
+ *
202
+ * ```ts
203
+ * const projectId = await client.getSandboxProjectId();
204
+ * const ready = Promise.withResolvers<void>();
205
+ * const unsubscribe = client.onAdHocExecution(
206
+ * projectId,
207
+ * (ev) => { ... },
208
+ * { onReady: () => ready.resolve() },
209
+ * );
210
+ * await ready.promise; // SSE attached, safe to POST
211
+ * await client.runAdHoc(source);
212
+ * ```
213
+ *
214
+ * `onReady` is invoked at most once per call (transparent reconnects do
215
+ * not re-fire it). If the connection never establishes — bad token, wrong
216
+ * URL, server down — `onReady` is never called; pair the `await` with a
217
+ * timeout so a misconfigured callsite fails fast instead of hanging.
218
+ */
219
+ onAdHocExecution(projectId: number, callback: (event: EngineEvent) => void, opts?: {
220
+ onReady?: () => void;
221
+ }): () => void;
222
+ /** Update the auth token at runtime (e.g. after refresh). */
223
+ setToken(token: string | undefined): void;
224
+ /** Update the X-Akribes-User header for metrics attribution. */
225
+ setOnBehalfOf(email: string | undefined): void;
226
+ /** Clean up heartbeat and SSE connections. */
227
+ destroy(): void;
228
+ }
229
+ declare class StateClient {
230
+ private http;
231
+ constructor(http: HttpClient);
232
+ get(opts?: {
233
+ signal?: AbortSignal;
234
+ }): Promise<{
235
+ env: Record<string, string>;
236
+ }>;
237
+ }
238
+ export { StateClient };
239
+ export type { HeartbeatStatus } from './sub/clients';
240
+ //# sourceMappingURL=client.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}