ghostlink-client 0.0.0-stage → 2.6.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.
@@ -0,0 +1,329 @@
1
+ /**
2
+ * Minimal Server-Sent Events parser for a `fetch` `Response.body` stream.
3
+ *
4
+ * Mirrors `sdks/python/ghostlink_client/_sse.py`. Ghostlink's streaming
5
+ * endpoint (`/api/inference/chat` with `stream: true`) sends unnamed SSE
6
+ * events — each a single `data: {json}` line followed by a blank line — so
7
+ * this parser only needs to handle the `data:` field, but follows the SSE
8
+ * spec generally (multiple `data:` lines per event are joined with `\n`,
9
+ * comment lines starting with `:` are ignored) rather than assuming that
10
+ * shape, so it keeps working if the server ever splits a payload across
11
+ * lines.
12
+ */
13
+ type JsonObject$1 = Record<string, unknown>;
14
+
15
+ /**
16
+ * Typed response wrappers.
17
+ *
18
+ * Mirrors `sdks/python/ghostlink_client/models.py`: thin, permissive views
19
+ * over the JSON the server returns. Every field is read with a default
20
+ * rather than assumed present, so a minor server version skew (a new field
21
+ * added, one renamed) doesn't throw inside the client. The original decoded
22
+ * JSON is always available on `.raw` for anything not modeled explicitly
23
+ * here.
24
+ */
25
+ type JsonObject = Record<string, any>;
26
+ interface ChatChoice {
27
+ index: number;
28
+ message: JsonObject;
29
+ finishReason: string | null;
30
+ }
31
+ /** `POST /v1/chat/completions` response. */
32
+ declare class ChatCompletion {
33
+ readonly id: string;
34
+ readonly object: string;
35
+ readonly created: number;
36
+ readonly model: string;
37
+ readonly choices: ChatChoice[];
38
+ /** The original decoded JSON response. */
39
+ readonly raw: JsonObject;
40
+ constructor(fields: {
41
+ id: string;
42
+ object: string;
43
+ created: number;
44
+ model: string;
45
+ choices: ChatChoice[];
46
+ raw: JsonObject;
47
+ });
48
+ /** The first choice's assistant text, or `""` if there are none. */
49
+ get content(): string;
50
+ static fromDict(data: JsonObject): ChatCompletion;
51
+ }
52
+ interface CompletionChoice {
53
+ text: string;
54
+ index: number;
55
+ finishReason: string | null;
56
+ }
57
+ /** `POST /v1/completions` response. */
58
+ declare class Completion {
59
+ readonly id: string;
60
+ readonly object: string;
61
+ readonly created: number;
62
+ readonly model: string;
63
+ readonly choices: CompletionChoice[];
64
+ readonly raw: JsonObject;
65
+ constructor(fields: {
66
+ id: string;
67
+ object: string;
68
+ created: number;
69
+ model: string;
70
+ choices: CompletionChoice[];
71
+ raw: JsonObject;
72
+ });
73
+ get text(): string;
74
+ static fromDict(data: JsonObject): Completion;
75
+ }
76
+ /** One entry from `GET /v1/models`. */
77
+ declare class Model {
78
+ readonly id: string;
79
+ readonly raw: JsonObject;
80
+ constructor(fields: {
81
+ id: string;
82
+ raw: JsonObject;
83
+ });
84
+ static fromDict(data: JsonObject): Model;
85
+ }
86
+ /** One incremental piece of a `/api/inference/chat` streamed response. */
87
+ declare class StreamChunk {
88
+ readonly token: string;
89
+ readonly requestId: string;
90
+ readonly sessionId: string;
91
+ readonly error: boolean;
92
+ readonly done: boolean;
93
+ readonly truncated: boolean;
94
+ readonly raw: JsonObject;
95
+ constructor(fields: {
96
+ token: string;
97
+ requestId: string;
98
+ sessionId: string;
99
+ error: boolean;
100
+ done: boolean;
101
+ truncated: boolean;
102
+ raw: JsonObject;
103
+ });
104
+ static fromDict(data: JsonObject): StreamChunk;
105
+ }
106
+
107
+ /**
108
+ * Client for a Ghostlink Studio API server.
109
+ *
110
+ * Wraps both the OpenAI-compatible REST surface (`/v1/chat/completions`,
111
+ * `/v1/completions`, `/v1/embeddings`, `/v1/models`) and Ghostlink's native
112
+ * `/api/*` surface (workers, sessions, settings, metrics, and real
113
+ * token-by-token streaming chat via `/api/inference/chat`).
114
+ *
115
+ * Mirrors `sdks/python/ghostlink_client/client.py` method-for-method and
116
+ * endpoint-for-endpoint. Parameter names use camelCase (idiomatic
117
+ * TypeScript) rather than the Python client's snake_case kwargs, but map
118
+ * onto the exact same JSON wire fields.
119
+ */
120
+
121
+ declare const DEFAULT_TIMEOUT_MS = 30000;
122
+ interface ChatMessage {
123
+ role: string;
124
+ content: string;
125
+ [key: string]: unknown;
126
+ }
127
+ /** Shared sampling parameters accepted by the OpenAI-compatible endpoints. */
128
+ interface SamplingParams {
129
+ temperature?: number;
130
+ topP?: number;
131
+ topK?: number;
132
+ penalty?: number;
133
+ maxTokens?: number;
134
+ }
135
+ interface CreateChatCompletionParams extends SamplingParams {
136
+ model: string;
137
+ messages: ChatMessage[];
138
+ }
139
+ interface CreateCompletionParams extends SamplingParams {
140
+ model: string;
141
+ prompt: string;
142
+ }
143
+ interface CreateEmbeddingsParams {
144
+ model: string;
145
+ input: string | string[];
146
+ }
147
+ interface StudioChatParams extends SamplingParams {
148
+ messages?: ChatMessage[];
149
+ model?: string;
150
+ }
151
+ declare class ChatCompletions {
152
+ private readonly client;
153
+ constructor(client: GhostlinkClient);
154
+ /** `POST /v1/chat/completions` — OpenAI-compatible, non-streaming. */
155
+ create(params: CreateChatCompletionParams): Promise<ChatCompletion>;
156
+ }
157
+ declare class Chat {
158
+ readonly completions: ChatCompletions;
159
+ constructor(client: GhostlinkClient);
160
+ }
161
+ declare class Completions {
162
+ private readonly client;
163
+ constructor(client: GhostlinkClient);
164
+ /** `POST /v1/completions` — OpenAI's legacy completions endpoint. */
165
+ create(params: CreateCompletionParams): Promise<Completion>;
166
+ }
167
+ declare class Embeddings {
168
+ private readonly client;
169
+ constructor(client: GhostlinkClient);
170
+ /** `POST /v1/embeddings`. */
171
+ create(params: CreateEmbeddingsParams): Promise<JsonObject$1>;
172
+ }
173
+ declare class Models {
174
+ private readonly client;
175
+ constructor(client: GhostlinkClient);
176
+ /** `GET /v1/models`. */
177
+ list(): Promise<Model[]>;
178
+ }
179
+ declare class Workers {
180
+ private readonly client;
181
+ constructor(client: GhostlinkClient);
182
+ list(): Promise<JsonObject$1[]>;
183
+ /**
184
+ * Triggers a UDP-broadcast + mDNS discovery sweep and registers any peers
185
+ * found. See `GET /api/workers/discover`.
186
+ */
187
+ discover(): Promise<JsonObject$1>;
188
+ connect(host: string, port: number): Promise<JsonObject$1>;
189
+ add(fields: JsonObject$1): Promise<JsonObject$1>;
190
+ disconnect(workerId: string): Promise<JsonObject$1>;
191
+ }
192
+ declare class Sessions {
193
+ private readonly client;
194
+ constructor(client: GhostlinkClient);
195
+ list(): Promise<JsonObject$1[]>;
196
+ }
197
+ declare class Settings {
198
+ private readonly client;
199
+ constructor(client: GhostlinkClient);
200
+ get(): Promise<JsonObject$1>;
201
+ update(fields: JsonObject$1): Promise<JsonObject$1>;
202
+ reset(): Promise<JsonObject$1>;
203
+ }
204
+ interface GhostlinkClientOptions {
205
+ apiKey?: string;
206
+ timeoutMs?: number;
207
+ /** Override `fetch` (for tests, or an alternate runtime implementation). */
208
+ fetchImpl?: typeof fetch;
209
+ }
210
+ /**
211
+ * Client for a Ghostlink Studio API server.
212
+ *
213
+ * @example
214
+ * ```ts
215
+ * const client = new GhostlinkClient("http://127.0.0.1:8003", { apiKey: "..." });
216
+ * const resp = await client.chat.completions.create({
217
+ * model: "llama3.2:3b",
218
+ * messages: [{ role: "user", content: "hello" }],
219
+ * });
220
+ * console.log(resp.content);
221
+ * ```
222
+ */
223
+ declare class GhostlinkClient {
224
+ readonly baseUrl: string;
225
+ readonly apiKey?: string;
226
+ readonly timeoutMs: number;
227
+ readonly chat: Chat;
228
+ readonly completions: Completions;
229
+ readonly embeddings: Embeddings;
230
+ readonly models: Models;
231
+ readonly workers: Workers;
232
+ readonly sessions: Sessions;
233
+ readonly settings: Settings;
234
+ private readonly fetchImpl;
235
+ constructor(baseUrl: string, options?: GhostlinkClientOptions);
236
+ private headers;
237
+ /** Fetches with a total-duration timeout on the connect/response-headers phase. */
238
+ private fetchWithTimeout;
239
+ private raiseForStatus;
240
+ /** @internal used by the nested resource classes. */
241
+ _request(method: string, path: string, json?: unknown): Promise<JsonObject$1>;
242
+ /** `GET /health` — unauthenticated liveness/version/backend info. */
243
+ health(): Promise<JsonObject$1>;
244
+ /**
245
+ * `GET /api/metrics` — JSON metrics snapshot. See `metricsPrometheus` for
246
+ * the Prometheus-exposition-format sibling.
247
+ */
248
+ metrics(): Promise<JsonObject$1>;
249
+ /**
250
+ * `GET /metrics` — the same snapshot as `metrics()`, formatted for a
251
+ * Prometheus scrape config instead of JSON.
252
+ */
253
+ metricsPrometheus(): Promise<string>;
254
+ /** Convenience alias for `client.models.list()`. */
255
+ listModels(): Promise<Model[]>;
256
+ /**
257
+ * Non-streaming call to Ghostlink Studio's native chat endpoint
258
+ * (`POST /api/inference/chat`) — richer than the OpenAI-compatible routes
259
+ * (session bookkeeping, MCP tool results, live metrics in the response),
260
+ * but Ghostlink-specific rather than portable. Use `streamChat` for real
261
+ * token-by-token streaming.
262
+ */
263
+ studioChat(message: string, params?: StudioChatParams): Promise<JsonObject$1>;
264
+ /**
265
+ * Real token-by-token streaming via `POST /api/inference/chat`
266
+ * (`stream: true`) over Server-Sent Events. Yields one `StreamChunk` per
267
+ * token as the model produces it; the final chunk has `done: true`. This
268
+ * is the only endpoint with genuine incremental streaming today — the
269
+ * OpenAI-compatible `/v1/chat/completions` accepts a `stream` field but
270
+ * does not yet act on it.
271
+ *
272
+ * Note: unlike the other request methods, the client's timeout is only
273
+ * applied to the connect/response-headers phase here, not the full
274
+ * duration of the stream — a long-running token stream would otherwise be
275
+ * truncated by a total-duration timeout meant for quick JSON calls.
276
+ *
277
+ * @example
278
+ * ```ts
279
+ * for await (const chunk of client.streamChat("tell me a story")) {
280
+ * if (!chunk.done) process.stdout.write(chunk.token);
281
+ * }
282
+ * ```
283
+ */
284
+ streamChat(message: string, params?: StudioChatParams): AsyncGenerator<StreamChunk>;
285
+ }
286
+
287
+ /**
288
+ * Exception hierarchy for the Ghostlink client.
289
+ *
290
+ * Mirrors `sdks/python/ghostlink_client/exceptions.py`:
291
+ * - `GhostlinkError` — base class for everything this client throws.
292
+ * - `GhostlinkConnectionError` — the client could not reach the server at
293
+ * all (DNS failure, connection refused, or a timeout before any response
294
+ * arrived).
295
+ * - `GhostlinkAPIError` — the server responded with a non-2xx status code.
296
+ * Carries `statusCode` and `body` (the parsed JSON error body, or raw
297
+ * text if the body wasn't JSON).
298
+ * - `GhostlinkAuthError` — a `GhostlinkAPIError` specifically for 401/403
299
+ * (missing, invalid, or expired bearer token).
300
+ */
301
+ /** Base class for all errors raised by this client. */
302
+ declare class GhostlinkError extends Error {
303
+ constructor(message: string);
304
+ }
305
+ /**
306
+ * The client could not reach the Ghostlink server at all — DNS failure,
307
+ * connection refused, or a timeout before any response arrived.
308
+ */
309
+ declare class GhostlinkConnectionError extends GhostlinkError {
310
+ constructor(message: string);
311
+ }
312
+ /** The server responded with a non-2xx status code. */
313
+ declare class GhostlinkAPIError extends GhostlinkError {
314
+ /** The HTTP status code returned by the server. */
315
+ readonly statusCode: number;
316
+ /** The parsed JSON error body, or raw response text if it wasn't JSON. */
317
+ readonly body: unknown;
318
+ constructor(statusCode: number, message: string, body?: unknown);
319
+ }
320
+ /** 401/403 — missing, invalid, or expired bearer token. */
321
+ declare class GhostlinkAuthError extends GhostlinkAPIError {
322
+ constructor(statusCode: number, message: string, body?: unknown);
323
+ }
324
+
325
+ /** TypeScript/JavaScript client SDK for the Ghostlink Studio API. */
326
+
327
+ declare const VERSION = "0.1.0";
328
+
329
+ export { type ChatChoice, ChatCompletion, type ChatMessage, Completion, type CompletionChoice, type CreateChatCompletionParams, type CreateCompletionParams, type CreateEmbeddingsParams, DEFAULT_TIMEOUT_MS, GhostlinkAPIError, GhostlinkAuthError, GhostlinkClient, type GhostlinkClientOptions, GhostlinkConnectionError, GhostlinkError, type JsonObject, Model, type SamplingParams, StreamChunk, type StudioChatParams, VERSION };