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.
- package/CHANGELOG.md +30 -0
- package/LICENSE +21 -0
- package/README.md +160 -0
- package/dist/client.d.ts +240 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +272 -0
- package/dist/client.js.map +1 -0
- package/dist/errors.d.ts +196 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +274 -0
- package/dist/errors.js.map +1 -0
- package/dist/execution/index.d.ts +3 -0
- package/dist/execution/index.d.ts.map +1 -0
- package/dist/execution/index.js +3 -0
- package/dist/execution/index.js.map +1 -0
- package/dist/execution/replay.d.ts +37 -0
- package/dist/execution/replay.d.ts.map +1 -0
- package/dist/execution/replay.js +59 -0
- package/dist/execution/replay.js.map +1 -0
- package/dist/execution/steps.d.ts +327 -0
- package/dist/execution/steps.d.ts.map +1 -0
- package/dist/execution/steps.js +1068 -0
- package/dist/execution/steps.js.map +1 -0
- package/dist/http.d.ts +53 -0
- package/dist/http.d.ts.map +1 -0
- package/dist/http.js +141 -0
- package/dist/http.js.map +1 -0
- package/dist/index.d.ts +36 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +38 -0
- package/dist/index.js.map +1 -0
- package/dist/runStream.d.ts +176 -0
- package/dist/runStream.d.ts.map +1 -0
- package/dist/runStream.js +408 -0
- package/dist/runStream.js.map +1 -0
- package/dist/sse.d.ts +46 -0
- package/dist/sse.d.ts.map +1 -0
- package/dist/sse.js +218 -0
- package/dist/sse.js.map +1 -0
- package/dist/sub/bench.d.ts +182 -0
- package/dist/sub/bench.d.ts.map +1 -0
- package/dist/sub/bench.js +420 -0
- package/dist/sub/bench.js.map +1 -0
- package/dist/sub/channels.d.ts +22 -0
- package/dist/sub/channels.d.ts.map +1 -0
- package/dist/sub/channels.js +32 -0
- package/dist/sub/channels.js.map +1 -0
- package/dist/sub/clients.d.ts +79 -0
- package/dist/sub/clients.d.ts.map +1 -0
- package/dist/sub/clients.js +190 -0
- package/dist/sub/clients.js.map +1 -0
- package/dist/sub/documents.d.ts +113 -0
- package/dist/sub/documents.d.ts.map +1 -0
- package/dist/sub/documents.js +329 -0
- package/dist/sub/documents.js.map +1 -0
- package/dist/sub/evals.d.ts +71 -0
- package/dist/sub/evals.d.ts.map +1 -0
- package/dist/sub/evals.js +86 -0
- package/dist/sub/evals.js.map +1 -0
- package/dist/sub/events.d.ts +65 -0
- package/dist/sub/events.d.ts.map +1 -0
- package/dist/sub/events.js +154 -0
- package/dist/sub/events.js.map +1 -0
- package/dist/sub/executions.d.ts +255 -0
- package/dist/sub/executions.d.ts.map +1 -0
- package/dist/sub/executions.js +322 -0
- package/dist/sub/executions.js.map +1 -0
- package/dist/sub/mcp.d.ts +51 -0
- package/dist/sub/mcp.d.ts.map +1 -0
- package/dist/sub/mcp.js +42 -0
- package/dist/sub/mcp.js.map +1 -0
- package/dist/sub/projects.d.ts +73 -0
- package/dist/sub/projects.d.ts.map +1 -0
- package/dist/sub/projects.js +101 -0
- package/dist/sub/projects.js.map +1 -0
- package/dist/sub/scripts.d.ts +58 -0
- package/dist/sub/scripts.d.ts.map +1 -0
- package/dist/sub/scripts.js +82 -0
- package/dist/sub/scripts.js.map +1 -0
- package/dist/sub/tokens.d.ts +126 -0
- package/dist/sub/tokens.d.ts.map +1 -0
- package/dist/sub/tokens.js +105 -0
- package/dist/sub/tokens.js.map +1 -0
- package/dist/sub/versions.d.ts +29 -0
- package/dist/sub/versions.d.ts.map +1 -0
- package/dist/sub/versions.js +52 -0
- package/dist/sub/versions.js.map +1 -0
- package/dist/tokenSafety.d.ts +15 -0
- package/dist/tokenSafety.d.ts.map +1 -0
- package/dist/tokenSafety.js +24 -0
- package/dist/tokenSafety.js.map +1 -0
- package/dist/types.d.ts +1147 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +132 -0
- package/dist/types.js.map +1 -0
- package/dist/workflowEvents.d.ts +297 -0
- package/dist/workflowEvents.d.ts.map +1 -0
- package/dist/workflowEvents.js +612 -0
- package/dist/workflowEvents.js.map +1 -0
- 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).
|
package/dist/client.d.ts
ADDED
|
@@ -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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"}
|