frutebox 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +69 -0
- package/LICENSE +21 -0
- package/README.md +204 -2
- package/account.d.ts +125 -0
- package/account.mjs +413 -0
- package/bin/frutebox.mjs +608 -0
- package/errors.mjs +100 -0
- package/index.d.ts +229 -0
- package/index.mjs +514 -0
- package/package.json +58 -4
- package/spec.mjs +42 -0
package/errors.mjs
ADDED
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Errors raised by the Frutebox client.
|
|
3
|
+
*
|
|
4
|
+
* The API publishes TWO error bodies and both are parsed, because a client that understood only one
|
|
5
|
+
* would report "Frutebox request failed (400)" for half the surface:
|
|
6
|
+
*
|
|
7
|
+
* NATIVE (/chat, /embeddings) { error: "...", code: "...", retryAfterSeconds: 3 }
|
|
8
|
+
* DROP-IN (everything else) { error: { message, type, code, param } }
|
|
9
|
+
*
|
|
10
|
+
* THE API KEY NEVER APPEARS IN AN ERROR. These objects are what lands in a caller's logs and crash
|
|
11
|
+
* reporter, and a rejected promise serialises its message.
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
export class FruteboxError extends Error {
|
|
15
|
+
constructor(message, { status = 0, code, errorType, retryAfterSeconds } = {}) {
|
|
16
|
+
super(message);
|
|
17
|
+
this.name = new.target.name;
|
|
18
|
+
this.status = status;
|
|
19
|
+
this.code = code;
|
|
20
|
+
this.errorType = errorType;
|
|
21
|
+
/** Published on 429 by the native shape; also read off the `retry-after` header. */
|
|
22
|
+
this.retryAfterSeconds = retryAfterSeconds;
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** 400 */ export class InvalidRequestError extends FruteboxError {}
|
|
27
|
+
/** 401 */ export class AuthenticationError extends FruteboxError {}
|
|
28
|
+
/** 402 */ export class BudgetError extends FruteboxError {}
|
|
29
|
+
/** 403 */ export class PolicyError extends FruteboxError {}
|
|
30
|
+
/** 404 */ export class NotFoundError extends FruteboxError {}
|
|
31
|
+
/** 429 */ export class RateLimitError extends FruteboxError {}
|
|
32
|
+
/** 501 — no model can serve this request yet. Never a fabricated result. */
|
|
33
|
+
export class NotImplementedByNetwork extends FruteboxError {}
|
|
34
|
+
/** 503 */ export class NoCapacityError extends FruteboxError {}
|
|
35
|
+
|
|
36
|
+
/** An async job reached a terminal non-success state (`failed` or `disabled`). */
|
|
37
|
+
export class JobFailed extends FruteboxError {
|
|
38
|
+
constructor(message, job) {
|
|
39
|
+
super(message, { code: "job_failed" });
|
|
40
|
+
this.job = job;
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* `*AndWait` gave up while the job was still `queued` or `running`.
|
|
46
|
+
* The job is NOT cancelled — it is still running on the network, and its id is on the error so the
|
|
47
|
+
* caller can keep polling rather than lose the work.
|
|
48
|
+
*/
|
|
49
|
+
export class JobTimeout extends FruteboxError {
|
|
50
|
+
constructor(message, job) {
|
|
51
|
+
super(message, { code: "job_timeout" });
|
|
52
|
+
this.job = job;
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
const BY_STATUS = {
|
|
57
|
+
400: InvalidRequestError,
|
|
58
|
+
401: AuthenticationError,
|
|
59
|
+
402: BudgetError,
|
|
60
|
+
403: PolicyError,
|
|
61
|
+
404: NotFoundError,
|
|
62
|
+
429: RateLimitError,
|
|
63
|
+
501: NotImplementedByNetwork,
|
|
64
|
+
503: NoCapacityError,
|
|
65
|
+
};
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Build the right error from either published shape.
|
|
69
|
+
*
|
|
70
|
+
* `body` is `undefined` when the response was not JSON at all — a CDN's HTML 404 page, say — in
|
|
71
|
+
* which case the status-derived message stands. Reading an unparseable body as an empty error is
|
|
72
|
+
* how "the route is not deployed" becomes "the call worked".
|
|
73
|
+
*/
|
|
74
|
+
export function errorFromBody(status, body, retryAfterHeader) {
|
|
75
|
+
let message = `Frutebox request failed (${status}).`;
|
|
76
|
+
let code;
|
|
77
|
+
let errorType;
|
|
78
|
+
let retry;
|
|
79
|
+
|
|
80
|
+
if (body && typeof body === "object") {
|
|
81
|
+
const err = body.error;
|
|
82
|
+
if (typeof err === "string") {
|
|
83
|
+
if (err) message = err;
|
|
84
|
+
if (typeof body.code === "string") code = body.code;
|
|
85
|
+
if (typeof body.retryAfterSeconds === "number") retry = Math.trunc(body.retryAfterSeconds);
|
|
86
|
+
} else if (err && typeof err === "object") {
|
|
87
|
+
if (typeof err.message === "string") message = err.message;
|
|
88
|
+
if (typeof err.code === "string") code = err.code;
|
|
89
|
+
if (typeof err.type === "string") errorType = err.type;
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
if (retry === undefined && retryAfterHeader) {
|
|
94
|
+
const parsed = Number(retryAfterHeader);
|
|
95
|
+
if (Number.isFinite(parsed)) retry = Math.trunc(parsed);
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
const Cls = BY_STATUS[status] ?? FruteboxError;
|
|
99
|
+
return new Cls(message, { status, code, errorType, retryAfterSeconds: retry });
|
|
100
|
+
}
|
package/index.d.ts
ADDED
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Type declarations for the Frutebox SDK.
|
|
3
|
+
*
|
|
4
|
+
* HAND-WRITTEN, not generated, for the same reason the package has no build step: the bytes shipped
|
|
5
|
+
* are the bytes written. `test/spec-conformance.test.mjs` checks the surface against
|
|
6
|
+
* `sdk/spec/openapi.json`, so these cannot drift from the contract unnoticed.
|
|
7
|
+
*
|
|
8
|
+
* The response types are deliberately shaped from the spec's own response schemas. Where the spec
|
|
9
|
+
* publishes an open object (`/moderations`, `/skills`), that is reflected rather than invented.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
/** A region id from the published enum. The spec renders this list from `lib/env.ts::REGIONS`. */
|
|
13
|
+
export type Region = "global" | "eu-west" | "eu-central" | "eu-north" | "uk" | "us-east";
|
|
14
|
+
|
|
15
|
+
/** The per-node measured cost the native surface returns. */
|
|
16
|
+
export interface UsageNode {
|
|
17
|
+
id?: string;
|
|
18
|
+
name?: string;
|
|
19
|
+
computeMs?: number;
|
|
20
|
+
watts?: number;
|
|
21
|
+
trust?: string;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* The REAL cost of a request, not an estimate: electricity and internet are measured per serving
|
|
26
|
+
* node. `cost` is what the account was charged.
|
|
27
|
+
*/
|
|
28
|
+
export interface Usage {
|
|
29
|
+
tokens?: number;
|
|
30
|
+
computeMs?: number;
|
|
31
|
+
nodes?: UsageNode[];
|
|
32
|
+
electricityCost?: number;
|
|
33
|
+
internetCost?: number;
|
|
34
|
+
cost?: number;
|
|
35
|
+
currency?: string;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** `POST /chat` — the native shape. */
|
|
39
|
+
export interface ChatResult {
|
|
40
|
+
reply: string;
|
|
41
|
+
model: string;
|
|
42
|
+
region: Region;
|
|
43
|
+
usage: Usage;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
export type Role = "system" | "user" | "assistant";
|
|
47
|
+
export interface ChatMessage { role: Role; content: string }
|
|
48
|
+
|
|
49
|
+
/** `POST /chat/completions` — the drop-in shape. */
|
|
50
|
+
export interface Completion {
|
|
51
|
+
id?: string;
|
|
52
|
+
object?: "chat.completion";
|
|
53
|
+
created?: number;
|
|
54
|
+
model?: string;
|
|
55
|
+
choices?: Array<{
|
|
56
|
+
index?: number;
|
|
57
|
+
message?: { role?: string; content?: string };
|
|
58
|
+
finish_reason?: string;
|
|
59
|
+
}>;
|
|
60
|
+
usage?: { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number };
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
export interface CompletionChunk {
|
|
64
|
+
id?: string;
|
|
65
|
+
object?: "chat.completion.chunk";
|
|
66
|
+
created?: number;
|
|
67
|
+
model?: string;
|
|
68
|
+
choices?: Array<{ index?: number; delta?: { role?: string; content?: string }; finish_reason?: string | null }>;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** `POST /embeddings` — native. Vectors come back directly, in request order. */
|
|
72
|
+
export interface EmbeddingsResult {
|
|
73
|
+
embeddings: number[][];
|
|
74
|
+
/** The embedder the node ACTUALLY ran — you do not pick one. */
|
|
75
|
+
model: string;
|
|
76
|
+
dimensions: number;
|
|
77
|
+
region: Region;
|
|
78
|
+
/** Null only when the network returned vectors with no usage: nothing was metered, said plainly. */
|
|
79
|
+
usage: Usage | null;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
export interface Model {
|
|
83
|
+
id: string;
|
|
84
|
+
object?: "model";
|
|
85
|
+
created?: number;
|
|
86
|
+
owned_by?: string;
|
|
87
|
+
}
|
|
88
|
+
export interface ModelList { object?: "list"; data?: Model[] }
|
|
89
|
+
|
|
90
|
+
/** The status enum every media job reports. */
|
|
91
|
+
export type JobStatus = "queued" | "running" | "done" | "failed" | "disabled";
|
|
92
|
+
|
|
93
|
+
interface JobBase {
|
|
94
|
+
id: string;
|
|
95
|
+
status: JobStatus;
|
|
96
|
+
model?: string;
|
|
97
|
+
error?: string;
|
|
98
|
+
}
|
|
99
|
+
/** The url fields are present ONLY once `status` is `done`. */
|
|
100
|
+
export interface ImageJob extends JobBase { object: "image.generation.job"; image_url?: string }
|
|
101
|
+
export interface VideoJob extends JobBase { object: "video.generation.job"; video_url?: string }
|
|
102
|
+
export interface AudioJob extends JobBase { object: "audio.generation.job"; audio_url?: string }
|
|
103
|
+
|
|
104
|
+
export declare const API_PREFIX: "/api/v1";
|
|
105
|
+
/** Every published operation, mapped to the dotted client method that calls it. */
|
|
106
|
+
export declare const OPERATIONS: Readonly<Record<string, string>>;
|
|
107
|
+
export declare const DEFAULT_BASE_URL: string;
|
|
108
|
+
export declare const DEFAULT_TIMEOUT_MS: number;
|
|
109
|
+
|
|
110
|
+
export declare class FruteboxError extends Error {
|
|
111
|
+
status: number;
|
|
112
|
+
code?: string;
|
|
113
|
+
errorType?: string;
|
|
114
|
+
/** Published on 429 by the native shape; also read off the `retry-after` header. */
|
|
115
|
+
retryAfterSeconds?: number;
|
|
116
|
+
}
|
|
117
|
+
export declare class InvalidRequestError extends FruteboxError {}
|
|
118
|
+
export declare class AuthenticationError extends FruteboxError {}
|
|
119
|
+
export declare class BudgetError extends FruteboxError {}
|
|
120
|
+
export declare class PolicyError extends FruteboxError {}
|
|
121
|
+
export declare class NotFoundError extends FruteboxError {}
|
|
122
|
+
export declare class RateLimitError extends FruteboxError {}
|
|
123
|
+
export declare class NotImplementedByNetwork extends FruteboxError {}
|
|
124
|
+
export declare class NoCapacityError extends FruteboxError {}
|
|
125
|
+
export declare class JobFailed extends FruteboxError { job: JobBase }
|
|
126
|
+
/** The job is NOT cancelled — it is still running, and its id is on the error. */
|
|
127
|
+
export declare class JobTimeout extends FruteboxError { job: JobBase }
|
|
128
|
+
|
|
129
|
+
export interface FruteboxOptions {
|
|
130
|
+
/** Falls back to `FRUTEBOX_API_KEY`, then `STEVAI_API_KEY`. */
|
|
131
|
+
apiKey?: string;
|
|
132
|
+
/** The origin, or the spec's full server URL — both are accepted. */
|
|
133
|
+
baseUrl?: string;
|
|
134
|
+
timeoutMs?: number;
|
|
135
|
+
/** Injectable for tests. Defaults to the global `fetch`. */
|
|
136
|
+
fetch?: typeof fetch;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* `POST /chat` (native) — callable, because 0.0.1 published it that way — carrying the drop-in
|
|
141
|
+
* surface as a property.
|
|
142
|
+
*/
|
|
143
|
+
export interface ChatCallable {
|
|
144
|
+
(params: { message: string; region?: Region }): Promise<ChatResult>;
|
|
145
|
+
completions: {
|
|
146
|
+
/** @deprecated The published spec marks this operation `deprecated: true`. Use `fb.chat()`. */
|
|
147
|
+
create(params: {
|
|
148
|
+
messages: ChatMessage[];
|
|
149
|
+
model?: string;
|
|
150
|
+
stream?: false;
|
|
151
|
+
region?: Region;
|
|
152
|
+
stream_options?: { include_usage?: boolean };
|
|
153
|
+
[extra: string]: unknown;
|
|
154
|
+
}): Promise<Completion>;
|
|
155
|
+
/** @deprecated Use `fb.chat()`. */
|
|
156
|
+
create(params: {
|
|
157
|
+
messages: ChatMessage[];
|
|
158
|
+
model?: string;
|
|
159
|
+
stream: true;
|
|
160
|
+
region?: Region;
|
|
161
|
+
stream_options?: { include_usage?: boolean };
|
|
162
|
+
[extra: string]: unknown;
|
|
163
|
+
}): Promise<AsyncIterable<CompletionChunk>>;
|
|
164
|
+
};
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/** `GET /models` — callable, because 0.0.1 published `fb.models()`. */
|
|
168
|
+
export interface ModelsCallable {
|
|
169
|
+
(): Promise<ModelList>;
|
|
170
|
+
list(): Promise<ModelList>;
|
|
171
|
+
retrieve(id: string): Promise<Model>;
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
export declare class Frutebox {
|
|
175
|
+
constructor(options?: FruteboxOptions);
|
|
176
|
+
readonly baseUrl: string;
|
|
177
|
+
|
|
178
|
+
chat: ChatCallable;
|
|
179
|
+
models: ModelsCallable;
|
|
180
|
+
|
|
181
|
+
embeddings: {
|
|
182
|
+
create(params: { input: string | string[]; region?: Region }): Promise<EmbeddingsResult>;
|
|
183
|
+
};
|
|
184
|
+
|
|
185
|
+
images: {
|
|
186
|
+
/** ASYNC: returns a queued job. No image is returned here, ever. `n` is clamped to 1..4. */
|
|
187
|
+
generate(params: { prompt: string; n?: number; size?: string; region?: Region }): Promise<ImageJob>;
|
|
188
|
+
retrieve(id: string): Promise<ImageJob>;
|
|
189
|
+
generateAndWait(params: {
|
|
190
|
+
prompt: string; n?: number; size?: string; timeoutMs?: number; pollIntervalMs?: number;
|
|
191
|
+
}): Promise<ImageJob>;
|
|
192
|
+
};
|
|
193
|
+
|
|
194
|
+
videos: {
|
|
195
|
+
/** `POST /videos` — the native spelling. `seconds`/`region` are not sent; the route never read them. */
|
|
196
|
+
generate(params: { prompt: string; seconds?: number; region?: Region }): Promise<VideoJob>;
|
|
197
|
+
retrieve(id: string): Promise<VideoJob>;
|
|
198
|
+
generateAndWait(params: { prompt: string; timeoutMs?: number; pollIntervalMs?: number }): Promise<VideoJob>;
|
|
199
|
+
generations: {
|
|
200
|
+
/** `POST /videos/generations` — the drop-in spelling of the same operation. */
|
|
201
|
+
create(params: { prompt: string; seconds?: number }): Promise<VideoJob>;
|
|
202
|
+
};
|
|
203
|
+
};
|
|
204
|
+
|
|
205
|
+
audio: {
|
|
206
|
+
/** Returns the raw audio: the spec publishes no JSON body for this one. */
|
|
207
|
+
speech(params: { input: string; voice?: string; format?: string }): Promise<ArrayBuffer>;
|
|
208
|
+
generations: {
|
|
209
|
+
create(params: {
|
|
210
|
+
prompt: string; kind?: "music" | "song" | "sfx"; duration_s?: number; lyrics?: string; format?: string;
|
|
211
|
+
}): Promise<AudioJob>;
|
|
212
|
+
retrieve(id: string): Promise<AudioJob>;
|
|
213
|
+
createAndWait(params: {
|
|
214
|
+
prompt: string; kind?: "music" | "song" | "sfx"; duration_s?: number; lyrics?: string;
|
|
215
|
+
format?: string; timeoutMs?: number; pollIntervalMs?: number;
|
|
216
|
+
}): Promise<AudioJob>;
|
|
217
|
+
};
|
|
218
|
+
transcriptions: {
|
|
219
|
+
create(params: {
|
|
220
|
+
file: Blob | Uint8Array | ArrayBuffer; filename?: string; model?: string; language?: string;
|
|
221
|
+
}): Promise<{ text?: string }>;
|
|
222
|
+
};
|
|
223
|
+
};
|
|
224
|
+
|
|
225
|
+
moderations: { create(params: { input: string | string[] }): Promise<Record<string, unknown>> };
|
|
226
|
+
skills: { list(): Promise<Record<string, unknown>> };
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
export default Frutebox;
|