@dosu/seshi-client 0.0.0-stage → 0.10.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Dosu
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 CHANGED
@@ -1,3 +1,9 @@
1
- # Temporary Holding Version
1
+ <img src="https://raw.githubusercontent.com/dosu-ai/sessiondb/v0.10.0/brand/glyph/seshi-glyph-badge.svg" alt="" width="64" height="64">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # @dosu/seshi-client
4
+
5
+ *Every session has a thread.*
6
+
7
+ The typed HTTP client for a seshi server. Runs on Node 20+ and Bun.
8
+
9
+ Docs: https://github.com/dosu-ai/sessiondb#readme
package/dist/index.js ADDED
@@ -0,0 +1,374 @@
1
+ // packages/ts/client/src/index.ts
2
+ import {
3
+ Forbidden as Forbidden2,
4
+ IngestRejected,
5
+ OffsetMismatch as OffsetMismatch2,
6
+ SessionConflict as SessionConflict2,
7
+ SessionRejected as SessionRejected2,
8
+ StoreError as StoreError2
9
+ } from "@dosu/seshi-model";
10
+
11
+ // packages/ts/client/src/http.ts
12
+ import { gzipSync } from "node:zlib";
13
+ import {
14
+ Forbidden,
15
+ OffsetMismatch,
16
+ SessionConflict,
17
+ SessionRejected,
18
+ StoreError,
19
+ VERSION
20
+ } from "@dosu/seshi-model";
21
+ var RETRACT_HEADER = "x-seshi-retract";
22
+
23
+ class ServerError extends Error {
24
+ status;
25
+ code;
26
+ constructor(status, code, message) {
27
+ super(message);
28
+ this.status = status;
29
+ this.code = code;
30
+ this.name = "ServerError";
31
+ }
32
+ }
33
+ async function send(transport, method, path, options = {}) {
34
+ const server = transport.server.replace(/\/+$/, "");
35
+ const fetchImpl = transport.fetch ?? ((input, init) => globalThis.fetch(input, init));
36
+ const timeoutMs = transport.timeoutMs ?? 120000;
37
+ const url = new URL(`${server}${path}`);
38
+ for (const [key, value] of Object.entries(options.query ?? {})) {
39
+ if (value !== undefined)
40
+ url.searchParams.set(key, String(value));
41
+ }
42
+ const headers = {
43
+ "user-agent": transport.userAgent ?? `@dosu/seshi-client/${VERSION}`,
44
+ ...options.headers
45
+ };
46
+ let body;
47
+ if (options.body !== undefined) {
48
+ headers["content-type"] = "application/json";
49
+ const json = new TextEncoder().encode(JSON.stringify(options.body));
50
+ if (json.length >= (options.gzipFrom ?? Number.POSITIVE_INFINITY)) {
51
+ headers["content-encoding"] = "gzip";
52
+ body = new Uint8Array(gzipSync(json));
53
+ } else {
54
+ body = json;
55
+ }
56
+ }
57
+ let response;
58
+ try {
59
+ response = await fetchImpl(url.toString(), {
60
+ method,
61
+ headers,
62
+ body,
63
+ ...timeoutMs > 0 ? { signal: AbortSignal.timeout(timeoutMs) } : {}
64
+ });
65
+ } catch (err) {
66
+ const reason = err instanceof Error ? err.message : String(err);
67
+ throw new StoreError(`cannot reach ${server}: ${reason}`, err);
68
+ }
69
+ const text = await response.text();
70
+ let parsed = null;
71
+ if (text) {
72
+ try {
73
+ parsed = JSON.parse(text);
74
+ } catch {
75
+ if (response.ok) {
76
+ throw new ServerError(response.status, "bad_response", `not JSON: ${text.slice(0, 200)}`);
77
+ }
78
+ }
79
+ }
80
+ return { status: response.status, body: parsed, headers: response.headers };
81
+ }
82
+ function errorCode(body) {
83
+ return body?.error?.code;
84
+ }
85
+ function refuse(status, body, offset = 0) {
86
+ const error = body?.error ?? {};
87
+ const code = error.code ?? "unknown";
88
+ const message = error.message ?? `HTTP ${status}`;
89
+ if (status === 409 && code === "offset_mismatch") {
90
+ throw new OffsetMismatch(offset, error.expected ?? 0);
91
+ }
92
+ if (status === 409 && code === "conflict")
93
+ throw new SessionConflict(message);
94
+ if (status === 403 && code === "forbidden")
95
+ throw new Forbidden(message);
96
+ if (status === 422)
97
+ throw new SessionRejected(code, message);
98
+ if (status === 502)
99
+ throw new StoreError(message);
100
+ throw new ServerError(status, code, message);
101
+ }
102
+ async function authConfig(transport) {
103
+ const { status, body } = await send(transport, "GET", "/v1/auth/config");
104
+ if (status !== 200)
105
+ refuse(status, body);
106
+ return body;
107
+ }
108
+ async function exchangeIdToken(transport, request) {
109
+ const { status, body } = await send(transport, "POST", "/v1/auth/exchange", { body: request });
110
+ if (status !== 200)
111
+ refuse(status, body);
112
+ return body;
113
+ }
114
+
115
+ class HttpSessionDB {
116
+ server;
117
+ token;
118
+ user;
119
+ transport;
120
+ gzipFrom;
121
+ constructor(options) {
122
+ this.server = options.server.replace(/\/+$/, "");
123
+ this.token = options.token;
124
+ this.user = options.user;
125
+ this.gzipFrom = options.gzipFrom ?? 8 * 1024;
126
+ this.transport = {
127
+ server: this.server,
128
+ ...options.fetch ? { fetch: options.fetch } : {},
129
+ ...options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {},
130
+ ...options.userAgent !== undefined ? { userAgent: options.userAgent } : {}
131
+ };
132
+ }
133
+ request(method, path, options = {}) {
134
+ return send(this.transport, method, path, {
135
+ ...options,
136
+ gzipFrom: this.gzipFrom,
137
+ headers: {
138
+ ...options.headers,
139
+ authorization: `Bearer ${this.token}`,
140
+ ...this.user !== undefined ? { "x-seshi-user": this.user } : {}
141
+ }
142
+ });
143
+ }
144
+ async ingest(upload, options = {}) {
145
+ const { status, body } = await this.request("POST", "/v1/sessions", {
146
+ body: upload,
147
+ ...options.retractSecret !== undefined ? { headers: { [RETRACT_HEADER]: options.retractSecret } } : {}
148
+ });
149
+ if (status !== 200 && status !== 201)
150
+ refuse(status, body, upload.offset ?? 0);
151
+ return body;
152
+ }
153
+ sessionPath(agent, sessionId) {
154
+ return `/v1/sessions/${encodeURIComponent(agent)}/${encodeURIComponent(sessionId)}`;
155
+ }
156
+ async getSession(agent, sessionId, options = {}) {
157
+ const { status, body } = await this.request("GET", this.sessionPath(agent, sessionId), {
158
+ query: { owner: options.owner }
159
+ });
160
+ if (status === 404)
161
+ return null;
162
+ if (status !== 200)
163
+ refuse(status, body);
164
+ return body;
165
+ }
166
+ async getTrace(agent, sessionId, hash, format, options = {}) {
167
+ const { status, body } = await this.request("GET", `${this.sessionPath(agent, sessionId)}/trace`, { query: { hash, format, owner: options.owner } });
168
+ if (status === 404 || status === 410)
169
+ return null;
170
+ if (status !== 200)
171
+ refuse(status, body);
172
+ return body;
173
+ }
174
+ async listSessions(options = {}) {
175
+ const { status, body } = await this.request("GET", "/v1/sessions", {
176
+ query: { after: options.after, limit: options.limit, owner: options.owner }
177
+ });
178
+ if (status !== 200)
179
+ refuse(status, body);
180
+ return body;
181
+ }
182
+ async staleSessions(options = {}) {
183
+ const { status, body } = await this.request("GET", "/v1/sessions/stale", {
184
+ query: { after: options.after, limit: options.limit }
185
+ });
186
+ if (status !== 200)
187
+ refuse(status, body);
188
+ return body;
189
+ }
190
+ async tombstone(agent, sessionId, options = {}) {
191
+ const { status, body } = await this.request("DELETE", this.sessionPath(agent, sessionId), {
192
+ query: { owner: options.owner },
193
+ ...options.retractSecret !== undefined ? { headers: { [RETRACT_HEADER]: options.retractSecret } } : {}
194
+ });
195
+ if (status === 404)
196
+ return null;
197
+ if (status !== 200)
198
+ refuse(status, body);
199
+ return body;
200
+ }
201
+ async setVisibility(agent, sessionId, visibility, options = {}) {
202
+ const { status, body } = await this.request("PATCH", this.sessionPath(agent, sessionId), {
203
+ body: { visibility },
204
+ query: { owner: options.owner }
205
+ });
206
+ if (status === 404)
207
+ return null;
208
+ if (status !== 200)
209
+ refuse(status, body);
210
+ return body;
211
+ }
212
+ async reviews(agent, sessionId, options = {}) {
213
+ const { status, body } = await this.request("GET", `${this.sessionPath(agent, sessionId)}/reviews`, { query: { owner: options.owner } });
214
+ if (status === 404)
215
+ return null;
216
+ if (status !== 200)
217
+ refuse(status, body);
218
+ return body.reviews;
219
+ }
220
+ async changes(options = {}) {
221
+ const { status, body } = await this.request("GET", "/v1/changes", {
222
+ query: { after: options.after, since: options.since, limit: options.limit }
223
+ });
224
+ if (status !== 200)
225
+ refuse(status, body);
226
+ return body;
227
+ }
228
+ async allChanges(options = {}) {
229
+ const { status, body } = await this.request("GET", "/v1/changes/all", {
230
+ query: { after: options.after, since: options.since, limit: options.limit }
231
+ });
232
+ if (status !== 200)
233
+ refuse(status, body);
234
+ return body;
235
+ }
236
+ async search(request) {
237
+ const { status, body } = await this.request("GET", "/v1/search", {
238
+ query: {
239
+ q: request.q,
240
+ owner: request.owner,
241
+ agent: request.agent,
242
+ repo: request.repo,
243
+ branch: request.branch,
244
+ source: request.source,
245
+ since: request.since,
246
+ until: request.until,
247
+ sort: request.sort,
248
+ limit: request.limit,
249
+ matches: request.matches,
250
+ cursor: request.cursor
251
+ }
252
+ });
253
+ if (status !== 200)
254
+ refuse(status, body);
255
+ return body;
256
+ }
257
+ async me() {
258
+ const { status, body } = await this.request("GET", "/v1/me");
259
+ if (status !== 200)
260
+ refuse(status, body);
261
+ return body;
262
+ }
263
+ async redactionRules() {
264
+ const { status, body } = await this.request("GET", "/v1/redaction/rules");
265
+ if (status !== 200)
266
+ refuse(status, body);
267
+ return body;
268
+ }
269
+ async redactionRulesSince(etag) {
270
+ const { status, body, headers } = await this.request("GET", "/v1/redaction/rules", {
271
+ ...etag ? { headers: { "if-none-match": etag } } : {}
272
+ });
273
+ if (status === 304 && etag)
274
+ return null;
275
+ if (status !== 200)
276
+ refuse(status, body);
277
+ return { document: body, etag: headers.get("etag") ?? undefined };
278
+ }
279
+ async owners(options = {}) {
280
+ const { status, body } = await this.request("GET", "/v1/owners", {
281
+ query: { after: options.after, limit: options.limit }
282
+ });
283
+ if (status !== 200)
284
+ refuse(status, body);
285
+ return body;
286
+ }
287
+ async createToken(request) {
288
+ const { status, body } = await this.request("POST", "/v1/tokens", { body: request });
289
+ if (status !== 201)
290
+ refuse(status, body);
291
+ return body;
292
+ }
293
+ async listTokens(filter = {}) {
294
+ const { status, body } = await this.request("GET", "/v1/tokens", {
295
+ query: { owner: filter.owner, kind: filter.kind, all: filter.all ? "true" : undefined }
296
+ });
297
+ if (status !== 200)
298
+ refuse(status, body);
299
+ return body.tokens;
300
+ }
301
+ async revokeToken(id) {
302
+ const { status, body } = await this.request("DELETE", `/v1/tokens/${encodeURIComponent(id)}`);
303
+ if (status === 404)
304
+ return null;
305
+ if (status !== 200)
306
+ refuse(status, body);
307
+ return body.token;
308
+ }
309
+ async revokeOwnerTokens(owner, kind) {
310
+ const { status, body } = await this.request("POST", "/v1/tokens/revoke", {
311
+ body: { owner, ...kind ? { kind } : {} }
312
+ });
313
+ if (status !== 200)
314
+ refuse(status, body);
315
+ return body.revoked;
316
+ }
317
+ async jobs() {
318
+ const { status, body } = await this.request("GET", "/v1/admin/jobs");
319
+ if (status !== 200)
320
+ refuse(status, body);
321
+ return body;
322
+ }
323
+ async configStatus() {
324
+ const { status, body } = await this.request("GET", "/v1/admin/reload");
325
+ if (status !== 200)
326
+ refuse(status, body);
327
+ return body;
328
+ }
329
+ async reload() {
330
+ const { status, body } = await this.request("POST", "/v1/admin/reload");
331
+ const answer = body;
332
+ if ((status === 200 || status === 422) && answer?.reload && answer.config) {
333
+ return { reload: answer.reload, config: answer.config };
334
+ }
335
+ refuse(status, body);
336
+ }
337
+ async sources(options = {}) {
338
+ const { status, body } = await this.request("GET", "/v1/admin/sources", {
339
+ query: { days: options.days }
340
+ });
341
+ if (status !== 200)
342
+ refuse(status, body);
343
+ return body.sources;
344
+ }
345
+ async source(id, options = {}) {
346
+ const { status, body } = await this.request("GET", `/v1/admin/sources/${encodeURIComponent(id)}`, { query: { days: options.days } });
347
+ if (status === 404 && errorCode(body) === "unknown_source")
348
+ return null;
349
+ if (status !== 200)
350
+ refuse(status, body);
351
+ return body;
352
+ }
353
+ async records(kind, id, options = {}) {
354
+ const { status, body } = await this.request("GET", `/v1/admin/sources/${encodeURIComponent(id)}/${kind}`, { query: { since: options.since, after: options.after, limit: options.limit } });
355
+ if (status === 404 && errorCode(body) === "unknown_source")
356
+ return null;
357
+ if (status !== 200)
358
+ refuse(status, body);
359
+ return body;
360
+ }
361
+ }
362
+ export {
363
+ Forbidden2 as Forbidden,
364
+ HttpSessionDB,
365
+ IngestRejected,
366
+ OffsetMismatch2 as OffsetMismatch,
367
+ RETRACT_HEADER,
368
+ ServerError,
369
+ SessionConflict2 as SessionConflict,
370
+ SessionRejected2 as SessionRejected,
371
+ StoreError2 as StoreError,
372
+ authConfig,
373
+ exchangeIdToken
374
+ };
package/package.json CHANGED
@@ -1,6 +1,35 @@
1
1
  {
2
2
  "name": "@dosu/seshi-client",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.10.0",
4
+ "license": "MIT",
5
+ "homepage": "https://github.com/dosu-ai/sessiondb#readme",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/dosu-ai/sessiondb.git"
9
+ },
10
+ "bugs": {
11
+ "url": "https://github.com/dosu-ai/sessiondb/issues"
12
+ },
13
+ "description": "The typed HTTP client for a seshi server. Runs on Node 20+ and Bun.",
14
+ "type": "module",
15
+ "main": "./dist/index.js",
16
+ "types": "./types/index.d.ts",
17
+ "exports": {
18
+ ".": {
19
+ "types": "./types/index.d.ts",
20
+ "default": "./dist/index.js"
21
+ },
22
+ "./package.json": "./package.json"
23
+ },
24
+ "files": [
25
+ "dist/",
26
+ "types/"
27
+ ],
28
+ "sideEffects": false,
29
+ "engines": {
30
+ "node": ">=20"
31
+ },
32
+ "dependencies": {
33
+ "@dosu/seshi-model": "0.10.0"
34
+ }
35
+ }
@@ -0,0 +1,159 @@
1
+ import { type AllChangesPage, type ChangesPage, type Fetch, type Identity, type IngestOptions, type ListSessionsOptions, type ReadChangesOptions, type RenderFormat, type SearchRequest, type SearchResults, type SessionDB, type SessionMetadata, type SessionsPage, type StaleSessionsPage, type StoredTrace, type StoreSessionResult, type Upload, type Visibility } from "@dosu/seshi-model";
2
+ import type { AuthConfig, ConfigStatus, ExchangeRequest, ExchangeResult, JobsStatus, OwnersPage, RecordKind, RecordsPage, ReloadReport, ReviewDecision, SourceStatus, TokenInfo, TokenKind, TokenRequest } from "./types.js";
3
+ /** How a client reaches the server, with or without a credential. */
4
+ export interface TransportOptions {
5
+ /** The server's base URL (`https://seshi.example.com`). */
6
+ server: string;
7
+ /** For tests and custom transports: defaults to the global `fetch`. */
8
+ fetch?: Fetch;
9
+ /** Per request; a large transcript can take the server a while to normalize and verify.
10
+ * Default 120 s, the server's own idle timeout. 0 disables. */
11
+ timeoutMs?: number;
12
+ /** Sent as `User-Agent`, so a server's logs say which program called
13
+ * (`dosu-cli/0.68.5`). Default `@dosu/seshi-client/<version>`; the seshi CLI sends
14
+ * `seshi/<version>`. */
15
+ userAgent?: string;
16
+ }
17
+ export interface HttpClientOptions extends TransportOptions {
18
+ token: string;
19
+ /** With the org key (X5.12): the username to write as, sent as `X-Seshi-User`. The CLI
20
+ * resolves it from SESHI_USER, the CLI config's `user`, git's user.email, then the OS user
21
+ * name (X5.7). Other credentials name their owner themselves. */
22
+ user?: string;
23
+ /** Bodies past this many bytes are sent `Content-Encoding: gzip`. Default 8 KiB. */
24
+ gzipFrom?: number;
25
+ }
26
+ /** The header a retraction carries its secret in (F9.7). */
27
+ export declare const RETRACT_HEADER = "x-seshi-retract";
28
+ /** Whose session a read or change is about: the caller's own when `owner` is omitted. A member
29
+ * reads another owner's sessions as far as visibility allows (X5.10). */
30
+ export interface OwnerOption {
31
+ owner?: string;
32
+ }
33
+ /** A response the server gave that is not one of the pipeline's own refusals: unauthorized, a
34
+ * bad request, an internal error, a route that is not there. */
35
+ export declare class ServerError extends Error {
36
+ readonly status: number;
37
+ readonly code: string;
38
+ constructor(status: number, code: string, message: string);
39
+ }
40
+ /** `GET /v1/auth/config`: whether the server takes the org key and which IdP it signs in
41
+ * through (X5.7). Needs no credential. */
42
+ export declare function authConfig(transport: TransportOptions): Promise<AuthConfig>;
43
+ /** `POST /v1/auth/exchange`: an IdP ID token for a session token, and a device token when the
44
+ * request names a machine (X5.2). Needs no credential; a token the server does not accept is
45
+ * `ServerError` 401, a server without an IdP 404 `no_idp`. */
46
+ export declare function exchangeIdToken(transport: TransportOptions, request: ExchangeRequest): Promise<ExchangeResult>;
47
+ /** The server's API over `fetch`. Every refusal the server maps to a status comes back as the
48
+ * error the pipeline would have thrown. */
49
+ export declare class HttpSessionDB implements SessionDB {
50
+ readonly server: string;
51
+ private readonly token;
52
+ private readonly user;
53
+ private readonly transport;
54
+ private readonly gzipFrom;
55
+ constructor(options: HttpClientOptions);
56
+ private request;
57
+ /** `POST /v1/sessions`. With `retractSecret` (for a `replace` with the org key) the secret
58
+ * goes in `X-Seshi-Retract`, never the body. */
59
+ ingest(upload: Upload, options?: IngestOptions): Promise<StoreSessionResult>;
60
+ private sessionPath;
61
+ /** The session's metadata; null for one not stored, or one the caller may not read. */
62
+ getSession(agent: string, sessionId: string, options?: OwnerOption): Promise<SessionMetadata | null>;
63
+ /** The head trace, or `hash`, as `format`; null for a session not stored, unreadable or
64
+ * redacted. */
65
+ getTrace(agent: string, sessionId: string, hash?: string, format?: RenderFormat, options?: OwnerOption): Promise<StoredTrace | null>;
66
+ listSessions(options?: ListSessionsOptions): Promise<SessionsPage>;
67
+ /** `GET /v1/sessions/stale`: the caller's own sessions an older normalizer built (X4.9), a
68
+ * page at a time. Needs `sessions:write`, which the uploader's credential has. */
69
+ staleSessions(options?: {
70
+ after?: string;
71
+ limit?: number;
72
+ }): Promise<StaleSessionsPage>;
73
+ /** Delete the session: a tombstone in its owner's change feed (X5.3); null for one not
74
+ * stored. Needs `sessions:delete`, and with an IdP a session token under 10 minutes old.
75
+ * With `retractSecret` it is a retraction instead (F9.7): the machine that uploaded the
76
+ * session proves it with the secret whose hash it sent, using its normal upload credential
77
+ * (`sessions:write`), and the tombstone says `retracted`. A refused retraction is
78
+ * `ServerError` 403 `bad_retract_secret` or `retract_disabled`. */
79
+ tombstone(agent: string, sessionId: string, options?: OwnerOption & {
80
+ retractSecret?: string;
81
+ }): Promise<{
82
+ removed: number;
83
+ } | null>;
84
+ /** Change who may read a session (X5.10); the metadata as it now is, null for one not
85
+ * stored. A redacted session is `ServerError` 410. The owner or an admin may. */
86
+ setVisibility(agent: string, sessionId: string, visibility: Visibility, options?: OwnerOption): Promise<SessionMetadata | null>;
87
+ /** What model review decided for each stored write of the session, oldest first (F3.8,
88
+ * `GET …/reviews`): the whole audit record for admins, only `n`, `at`, `content_hash` and
89
+ * `decision` for anyone else who may read it. Null for a session not stored. */
90
+ reviews(agent: string, sessionId: string, options?: OwnerOption): Promise<ReviewDecision[] | null>;
91
+ changes(options?: ReadChangesOptions): Promise<ChangesPage>;
92
+ /** Every owner's change feed as one (`GET /v1/changes/all`), by stamp, then owner, then
93
+ * key; each entry names its owner. Only for a credential that reads every session (a
94
+ * service token or an admin): any other is `Forbidden`. `after` is the last page's opaque
95
+ * `cursor`. While the server's search index is first being built it is a `ServerError` with
96
+ * status 503 (`index_building`), and 404 (`search_disabled`) when search is turned off. */
97
+ allChanges(options?: ReadChangesOptions): Promise<AllChangesPage>;
98
+ /** Keyword search over the sessions this credential may read (F10, `GET /v1/search`). A
99
+ * request the server cannot run is a `ServerError` with status 400 (`bad_query`); while the
100
+ * server's index is first being built, status 503 (`index_building`), and 404
101
+ * (`search_disabled`) when the server has search turned off. */
102
+ search(request: SearchRequest): Promise<SearchResults>;
103
+ me(): Promise<Identity>;
104
+ /** The org's redaction rule packs (`GET /v1/redaction/rules`, F2.4), for redacting before
105
+ * upload: a `seshi/redaction-rules/1` document, unchecked. `@seshi/redact`'s
106
+ * `ruleSetFromDocument` validates it and builds the rule set. */
107
+ redactionRules(): Promise<unknown>;
108
+ /** `redactionRules` with HTTP caching, for a client that keeps the document between runs:
109
+ * `etag`, from an earlier answer, goes as If-None-Match. `null` means the rule set has not
110
+ * changed since; otherwise the document comes back with its own ETag. */
111
+ redactionRulesSince(etag?: string): Promise<{
112
+ document: unknown;
113
+ etag: string | undefined;
114
+ } | null>;
115
+ /** The owners with sessions stored. */
116
+ owners(options?: {
117
+ after?: string;
118
+ limit?: number;
119
+ }): Promise<OwnersPage>;
120
+ /** Issue a token; its secret is in the answer only. */
121
+ createToken(request: TokenRequest): Promise<{
122
+ token: string;
123
+ record: TokenInfo;
124
+ }>;
125
+ /** Live tokens, or every one with `all`. */
126
+ listTokens(filter?: {
127
+ owner?: string;
128
+ kind?: TokenKind;
129
+ all?: boolean;
130
+ }): Promise<TokenInfo[]>;
131
+ /** Revoke one token; null for an unknown id. */
132
+ revokeToken(id: string): Promise<TokenInfo | null>;
133
+ /** Revoke every token of an owner (offboarding, X5.11), or every one of a kind. */
134
+ revokeOwnerTokens(owner: string, kind?: TokenKind): Promise<TokenInfo[]>;
135
+ /** The worker, its jobs and every source. */
136
+ jobs(): Promise<JobsStatus>;
137
+ /** The running config's generation, hash and rule set, and how the last reload went. */
138
+ configStatus(): Promise<ConfigStatus>;
139
+ /** Have the server read its config files again and apply them (all or nothing). A rejected
140
+ * reload is returned, not thrown: its `errors` say why, and the running config stays. */
141
+ reload(): Promise<{
142
+ reload: ReloadReport;
143
+ config: ConfigStatus;
144
+ }>;
145
+ /** Every configured source and `upload`: checkpoints, record counts, health over `days`. */
146
+ sources(options?: {
147
+ days?: number;
148
+ }): Promise<SourceStatus[]>;
149
+ /** One source's status; null for an unknown source. */
150
+ source(id: string, options?: {
151
+ days?: number;
152
+ }): Promise<SourceStatus | null>;
153
+ /** A source's failure or drop records, oldest first (X6.4); null for an unknown source. */
154
+ records(kind: RecordKind, id: string, options?: {
155
+ since?: string;
156
+ after?: string;
157
+ limit?: number;
158
+ }): Promise<RecordsPage | null>;
159
+ }
@@ -0,0 +1,4 @@
1
+ export type { AllChangesPage, ChangesPage, Fetch, Identity, ListSessionsOptions, ReadChangesOptions, SearchMatch, SearchRequest, SearchResult, SearchResults, SessionDB, SessionsPage, StorageView, StoredTrace, StoreSessionResult, Upload, } from "@dosu/seshi-model";
2
+ export { Forbidden, IngestRejected, OffsetMismatch, SessionConflict, SessionRejected, StoreError, } from "@dosu/seshi-model";
3
+ export { authConfig, exchangeIdToken, type HttpClientOptions, HttpSessionDB, type OwnerOption, RETRACT_HEADER, ServerError, type TransportOptions, } from "./http.js";
4
+ export type { AuthConfig, ConfigStatus, ExchangeRequest, ExchangeResult, JobsStatus, OwnersPage, RecordKind, RecordsPage, ReloadReport, ReviewDecision, Scope, SourceRecord, SourceStatus, TokenInfo, TokenKind, TokenRequest, } from "./types.js";
@@ -0,0 +1,222 @@
1
+ import type { OwnerBasis, Visibility } from "@dosu/seshi-model";
2
+ export type Scope = "sessions:write" | "sessions:read" | "sessions:delete" | "search" | "sources:admin" | "tokens:admin";
3
+ export type TokenKind = "org" | "admin" | "device" | "service";
4
+ /** `GET /v1/auth/config`: which ways in the server takes (X5.7). */
5
+ export interface AuthConfig {
6
+ version: string;
7
+ /** The org key is accepted (X5.12). */
8
+ org_key: boolean;
9
+ /** The IdP to sign in through, or null without one. */
10
+ oidc: {
11
+ issuer: string;
12
+ client_id: string;
13
+ audience: string;
14
+ scopes: string[];
15
+ } | null;
16
+ session_token_seconds: number;
17
+ /** How recent a session token must be to delete (X5.3). */
18
+ delete_fresh_seconds: number;
19
+ }
20
+ /** `POST /v1/auth/exchange`'s body. */
21
+ export interface ExchangeRequest {
22
+ id_token: string;
23
+ nonce?: string;
24
+ /** The first sign-in from this machine, or a renewal of its device token (X5.2). */
25
+ machine?: {
26
+ id: string;
27
+ name?: string;
28
+ };
29
+ /** The device token's default visibility (X5.10). */
30
+ visibility?: Visibility;
31
+ }
32
+ export interface ExchangeResult {
33
+ session_token: string;
34
+ expires_at: string;
35
+ owner: string;
36
+ role: "member" | "admin";
37
+ scopes: Scope[];
38
+ device_token?: {
39
+ token: string;
40
+ id: string;
41
+ expires_at: string;
42
+ };
43
+ }
44
+ /** `POST /v1/tokens`' body (X5.9). */
45
+ export interface TokenRequest {
46
+ kind: TokenKind;
47
+ /** A person's owner id, for `admin` and `device`. */
48
+ owner?: string;
49
+ /** For `service`: its name, or the configured source it writes for. */
50
+ service?: string;
51
+ scopes?: Scope[];
52
+ visibility?: Visibility;
53
+ /** RFC 3339. */
54
+ expires_at?: string;
55
+ label?: string;
56
+ }
57
+ /** A token record without its hash. */
58
+ export interface TokenInfo {
59
+ schema: "seshi/token/1";
60
+ id: string;
61
+ kind: TokenKind;
62
+ /** The owner id, or `*` for the org key. */
63
+ owner: string;
64
+ scopes: Scope[];
65
+ visibility?: Visibility;
66
+ owner_basis?: OwnerBasis;
67
+ created_at: string;
68
+ expires_at: string | null;
69
+ revoked: boolean;
70
+ revoked_at?: string;
71
+ label?: string;
72
+ created_by?: {
73
+ kind: string;
74
+ principal: string;
75
+ credential_id?: string;
76
+ };
77
+ machine?: {
78
+ id: string;
79
+ name?: string;
80
+ };
81
+ claims?: Record<string, unknown>;
82
+ }
83
+ export interface OwnersPage {
84
+ owners: string[];
85
+ cursor?: string;
86
+ truncated: boolean;
87
+ }
88
+ /** A source's state (`GET /v1/admin/sources`). */
89
+ export interface SourceStatus {
90
+ id: string;
91
+ type: string;
92
+ enabled: boolean;
93
+ polled: boolean;
94
+ connector?: string;
95
+ interval_ms?: number;
96
+ note?: string;
97
+ checkpoint: {
98
+ updated_at: string;
99
+ cursor: Record<string, unknown>;
100
+ } | null;
101
+ dropped: number;
102
+ failed: number;
103
+ /** Outcome counts over the days asked for (X4.8). */
104
+ health: Record<string, number>;
105
+ }
106
+ export type RecordKind = "failed" | "dropped";
107
+ /** A drop or failure record (X6.4): that an envelope arrived and why it was not stored, never
108
+ * its content. */
109
+ export interface SourceRecord {
110
+ schema: "seshi/failed/1" | "seshi/dropped/1";
111
+ at: string;
112
+ source: string;
113
+ source_kind?: string;
114
+ owner?: string;
115
+ session_key?: string;
116
+ idempotency_key: string;
117
+ provenance?: Record<string, unknown>;
118
+ /** Failures: the pipeline's error code and message. */
119
+ code?: string;
120
+ message?: string;
121
+ /** Drops: why, under which policy. */
122
+ reason?: string;
123
+ policy?: string;
124
+ policy_hash?: string;
125
+ decision_model?: string;
126
+ }
127
+ export interface RecordsPage {
128
+ source: string;
129
+ kind: RecordKind;
130
+ records: {
131
+ key: string;
132
+ record: SourceRecord;
133
+ }[];
134
+ /** Pass as `after` for the next page. */
135
+ cursor?: string;
136
+ truncated: boolean;
137
+ }
138
+ /** `GET /v1/admin/jobs` (X7.5). Loosely typed here; `spec/openapi.yaml`'s `JobsStatus` is the
139
+ * whole shape. */
140
+ export interface JobsStatus {
141
+ at: string;
142
+ deployment: string;
143
+ instance: {
144
+ id: string;
145
+ process: string;
146
+ roles: string[];
147
+ version: string;
148
+ };
149
+ worker: {
150
+ state: "running" | "stopped" | "never" | "several";
151
+ [key: string]: unknown;
152
+ };
153
+ jobs: Array<{
154
+ name: string;
155
+ kind: string;
156
+ [key: string]: unknown;
157
+ }>;
158
+ sources: SourceStatus[];
159
+ warnings: string[];
160
+ }
161
+ /** One config reload (`POST /v1/admin/reload`); `spec/openapi.yaml`'s `ReloadReport`. */
162
+ export interface ReloadReport {
163
+ trigger: "signal" | "api" | "watch" | "manual";
164
+ started_at: string;
165
+ finished_at: string;
166
+ outcome: "applied" | "unchanged" | "rejected";
167
+ generation: number;
168
+ config_hash: string;
169
+ rule_set: string;
170
+ review_set: string | null;
171
+ errors?: string[];
172
+ changed: string[];
173
+ sources?: {
174
+ added: string[];
175
+ removed: string[];
176
+ changed: string[];
177
+ unchanged: string[];
178
+ };
179
+ restart_required: string[];
180
+ }
181
+ /** `GET /v1/admin/reload`: the running config's generation and hash, and the last reload. */
182
+ export interface ConfigStatus {
183
+ generation: number;
184
+ config_hash: string;
185
+ rule_set: string;
186
+ /** A hash of the running review policies (their prompt text included); null for a reviewer
187
+ * seshi did not build. */
188
+ review_set: string | null;
189
+ loaded_at: string;
190
+ reloadable: boolean;
191
+ restart_required: string[];
192
+ last_reload: ReloadReport | null;
193
+ live_sections: string[];
194
+ restart_only_sections: string[];
195
+ }
196
+ /** One stored write's model review (`GET /v1/sessions/{agent}/{id}/reviews`, F3.8). Callers
197
+ * who are not admins get `schema`, `n`, `at`, `content_hash` and `decision` only. */
198
+ export interface ReviewDecision {
199
+ schema: "seshi/review/1";
200
+ n: number;
201
+ at: string;
202
+ content_hash: string;
203
+ /** `allow`, `redact` (findings applied), or `skipped` (review failed and was skipped). */
204
+ decision: "allow" | "redact" | "skipped";
205
+ policy?: string;
206
+ policy_hash?: string;
207
+ decision_model?: string;
208
+ redactor_model?: string;
209
+ findings?: {
210
+ record: number;
211
+ field: string;
212
+ category: string;
213
+ action: "redact" | "withhold";
214
+ }[];
215
+ unmatched?: number;
216
+ parts?: number;
217
+ failure?: {
218
+ step: "decision" | "redactor";
219
+ code: string;
220
+ attempts: number;
221
+ };
222
+ }