flowforge-client 0.1.2
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/README.md +343 -0
- package/dist/index.d.mts +908 -0
- package/dist/index.d.ts +908 -0
- package/dist/index.js +811 -0
- package/dist/index.mjs +774 -0
- package/package.json +35 -0
package/dist/index.d.mts
ADDED
|
@@ -0,0 +1,908 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* FlowForge TypeScript Client - Type Definitions
|
|
3
|
+
*/
|
|
4
|
+
type Result<T> = {
|
|
5
|
+
data: T;
|
|
6
|
+
error: null;
|
|
7
|
+
} | {
|
|
8
|
+
data: null;
|
|
9
|
+
error: FlowForgeError;
|
|
10
|
+
};
|
|
11
|
+
declare class FlowForgeError extends Error {
|
|
12
|
+
status: number;
|
|
13
|
+
code?: string | undefined;
|
|
14
|
+
detail?: unknown | undefined;
|
|
15
|
+
constructor(message: string, status: number, code?: string | undefined, detail?: unknown | undefined);
|
|
16
|
+
}
|
|
17
|
+
type RunStatus = "pending" | "running" | "completed" | "failed" | "paused" | "cancelled";
|
|
18
|
+
type StepType = "run" | "sleep" | "ai" | "wait_for_event" | "invoke" | "send_event" | "agent";
|
|
19
|
+
type StepStatus = "pending" | "running" | "completed" | "failed" | "sleeping" | "waiting";
|
|
20
|
+
type TriggerType = "event" | "cron" | "webhook";
|
|
21
|
+
type ApprovalStatus = "pending" | "approved" | "rejected" | "expired";
|
|
22
|
+
interface Run {
|
|
23
|
+
id: string;
|
|
24
|
+
function_id: string;
|
|
25
|
+
event_id: string | null;
|
|
26
|
+
status: RunStatus;
|
|
27
|
+
trigger_type: string;
|
|
28
|
+
trigger_data: Record<string, unknown>;
|
|
29
|
+
output: Record<string, unknown> | null;
|
|
30
|
+
error: Record<string, unknown> | null;
|
|
31
|
+
attempt: number;
|
|
32
|
+
max_attempts: number;
|
|
33
|
+
started_at: string | null;
|
|
34
|
+
ended_at: string | null;
|
|
35
|
+
created_at: string;
|
|
36
|
+
}
|
|
37
|
+
interface Step {
|
|
38
|
+
id: string;
|
|
39
|
+
step_id: string;
|
|
40
|
+
step_type: StepType;
|
|
41
|
+
status: StepStatus;
|
|
42
|
+
input: Record<string, unknown> | null;
|
|
43
|
+
output: Record<string, unknown> | null;
|
|
44
|
+
error: Record<string, unknown> | null;
|
|
45
|
+
attempt: number;
|
|
46
|
+
max_attempts: number;
|
|
47
|
+
started_at: string | null;
|
|
48
|
+
ended_at: string | null;
|
|
49
|
+
created_at: string;
|
|
50
|
+
}
|
|
51
|
+
interface RunWithSteps extends Run {
|
|
52
|
+
steps: Step[];
|
|
53
|
+
}
|
|
54
|
+
interface FlowForgeFunction {
|
|
55
|
+
id: string;
|
|
56
|
+
function_id: string;
|
|
57
|
+
name: string;
|
|
58
|
+
trigger_type: TriggerType;
|
|
59
|
+
trigger_value: string;
|
|
60
|
+
trigger_expression: string | null;
|
|
61
|
+
endpoint_url: string | null;
|
|
62
|
+
is_inline: boolean;
|
|
63
|
+
system_prompt: string | null;
|
|
64
|
+
tools_config: string[] | null;
|
|
65
|
+
agent_config: Record<string, unknown> | null;
|
|
66
|
+
config: Record<string, unknown>;
|
|
67
|
+
is_active: boolean;
|
|
68
|
+
created_at: string;
|
|
69
|
+
updated_at: string;
|
|
70
|
+
}
|
|
71
|
+
interface Tool {
|
|
72
|
+
id: string;
|
|
73
|
+
name: string;
|
|
74
|
+
description: string;
|
|
75
|
+
parameters: Record<string, unknown>;
|
|
76
|
+
code: string | null;
|
|
77
|
+
is_builtin: boolean;
|
|
78
|
+
requires_approval: boolean;
|
|
79
|
+
approval_timeout: string | null;
|
|
80
|
+
is_active: boolean;
|
|
81
|
+
created_at: string;
|
|
82
|
+
updated_at: string;
|
|
83
|
+
}
|
|
84
|
+
interface Event {
|
|
85
|
+
id: string;
|
|
86
|
+
event_id: string;
|
|
87
|
+
name: string;
|
|
88
|
+
data: Record<string, unknown>;
|
|
89
|
+
timestamp: string;
|
|
90
|
+
received_at: string;
|
|
91
|
+
user_id: string | null;
|
|
92
|
+
processed: boolean;
|
|
93
|
+
}
|
|
94
|
+
interface SendEventResponse extends Event {
|
|
95
|
+
runs: Array<{
|
|
96
|
+
id: string;
|
|
97
|
+
function_id: string;
|
|
98
|
+
}>;
|
|
99
|
+
}
|
|
100
|
+
interface Approval {
|
|
101
|
+
id: string;
|
|
102
|
+
tool_call_id: string;
|
|
103
|
+
tool_name: string;
|
|
104
|
+
arguments: Record<string, unknown>;
|
|
105
|
+
run_id: string;
|
|
106
|
+
step_id: string;
|
|
107
|
+
status: ApprovalStatus;
|
|
108
|
+
created_at: string;
|
|
109
|
+
timeout_at: string;
|
|
110
|
+
}
|
|
111
|
+
interface Stats {
|
|
112
|
+
runs: {
|
|
113
|
+
total: number;
|
|
114
|
+
completed: number;
|
|
115
|
+
failed: number;
|
|
116
|
+
running: number;
|
|
117
|
+
};
|
|
118
|
+
functions: {
|
|
119
|
+
total: number;
|
|
120
|
+
active: number;
|
|
121
|
+
};
|
|
122
|
+
events: {
|
|
123
|
+
today: number;
|
|
124
|
+
total: number;
|
|
125
|
+
};
|
|
126
|
+
queue: {
|
|
127
|
+
pending: number;
|
|
128
|
+
running: number;
|
|
129
|
+
scheduled: number;
|
|
130
|
+
};
|
|
131
|
+
}
|
|
132
|
+
interface HealthStatus {
|
|
133
|
+
status: "healthy" | "unhealthy";
|
|
134
|
+
version?: string;
|
|
135
|
+
uptime?: number;
|
|
136
|
+
}
|
|
137
|
+
interface RunFilters {
|
|
138
|
+
status: RunStatus;
|
|
139
|
+
function_id: string;
|
|
140
|
+
}
|
|
141
|
+
interface FunctionFilters {
|
|
142
|
+
trigger_type: TriggerType;
|
|
143
|
+
is_active: boolean;
|
|
144
|
+
}
|
|
145
|
+
interface EventFilters {
|
|
146
|
+
name: string;
|
|
147
|
+
processed: boolean;
|
|
148
|
+
}
|
|
149
|
+
interface ToolFilters {
|
|
150
|
+
is_active: boolean;
|
|
151
|
+
requires_approval: boolean;
|
|
152
|
+
is_builtin: boolean;
|
|
153
|
+
}
|
|
154
|
+
interface ApprovalFilters {
|
|
155
|
+
status: ApprovalStatus;
|
|
156
|
+
}
|
|
157
|
+
interface CreateFunctionInput {
|
|
158
|
+
id: string;
|
|
159
|
+
name: string;
|
|
160
|
+
trigger_type: TriggerType;
|
|
161
|
+
trigger_value: string;
|
|
162
|
+
trigger_expression?: string;
|
|
163
|
+
endpoint_url?: string;
|
|
164
|
+
is_inline?: boolean;
|
|
165
|
+
system_prompt?: string;
|
|
166
|
+
tools_config?: string[];
|
|
167
|
+
agent_config?: Record<string, unknown>;
|
|
168
|
+
config?: Record<string, unknown>;
|
|
169
|
+
is_active?: boolean;
|
|
170
|
+
}
|
|
171
|
+
interface UpdateFunctionInput {
|
|
172
|
+
name?: string;
|
|
173
|
+
trigger_value?: string;
|
|
174
|
+
trigger_expression?: string;
|
|
175
|
+
endpoint_url?: string;
|
|
176
|
+
system_prompt?: string;
|
|
177
|
+
tools_config?: string[];
|
|
178
|
+
agent_config?: Record<string, unknown>;
|
|
179
|
+
config?: Record<string, unknown>;
|
|
180
|
+
is_active?: boolean;
|
|
181
|
+
}
|
|
182
|
+
interface CreateToolInput {
|
|
183
|
+
name: string;
|
|
184
|
+
description: string;
|
|
185
|
+
parameters: Record<string, unknown>;
|
|
186
|
+
code?: string;
|
|
187
|
+
requires_approval?: boolean;
|
|
188
|
+
approval_timeout?: string;
|
|
189
|
+
is_active?: boolean;
|
|
190
|
+
}
|
|
191
|
+
interface UpdateToolInput {
|
|
192
|
+
description?: string;
|
|
193
|
+
parameters?: Record<string, unknown>;
|
|
194
|
+
code?: string;
|
|
195
|
+
requires_approval?: boolean;
|
|
196
|
+
approval_timeout?: string;
|
|
197
|
+
is_active?: boolean;
|
|
198
|
+
}
|
|
199
|
+
interface SendEventInput {
|
|
200
|
+
id?: string;
|
|
201
|
+
user_id?: string;
|
|
202
|
+
timestamp?: string;
|
|
203
|
+
}
|
|
204
|
+
type UserRole = "admin" | "member" | "viewer";
|
|
205
|
+
interface User {
|
|
206
|
+
id: string;
|
|
207
|
+
email: string;
|
|
208
|
+
name: string;
|
|
209
|
+
role: UserRole;
|
|
210
|
+
is_active: boolean;
|
|
211
|
+
last_login_at: string | null;
|
|
212
|
+
created_at: string;
|
|
213
|
+
}
|
|
214
|
+
interface CreateUserInput {
|
|
215
|
+
email: string;
|
|
216
|
+
password: string;
|
|
217
|
+
name: string;
|
|
218
|
+
role: UserRole;
|
|
219
|
+
}
|
|
220
|
+
interface UpdateUserInput {
|
|
221
|
+
email?: string;
|
|
222
|
+
name?: string;
|
|
223
|
+
role?: UserRole;
|
|
224
|
+
is_active?: boolean;
|
|
225
|
+
}
|
|
226
|
+
interface UsersResponse {
|
|
227
|
+
users: User[];
|
|
228
|
+
total: number;
|
|
229
|
+
}
|
|
230
|
+
type ApiKeyType = "live" | "test" | "ro";
|
|
231
|
+
interface ApiKey {
|
|
232
|
+
id: string;
|
|
233
|
+
name: string;
|
|
234
|
+
key_prefix: string;
|
|
235
|
+
key_type: ApiKeyType;
|
|
236
|
+
scopes: string[];
|
|
237
|
+
expires_at: string | null;
|
|
238
|
+
last_used_at: string | null;
|
|
239
|
+
is_active: boolean;
|
|
240
|
+
created_at: string;
|
|
241
|
+
}
|
|
242
|
+
interface ApiKeyCreated extends ApiKey {
|
|
243
|
+
key: string;
|
|
244
|
+
}
|
|
245
|
+
interface CreateApiKeyInput {
|
|
246
|
+
name: string;
|
|
247
|
+
key_type?: ApiKeyType;
|
|
248
|
+
scopes?: string[];
|
|
249
|
+
expires_in_days?: number;
|
|
250
|
+
}
|
|
251
|
+
interface ApiKeysResponse {
|
|
252
|
+
keys: ApiKey[];
|
|
253
|
+
total: number;
|
|
254
|
+
}
|
|
255
|
+
interface ApiKeyFilters {
|
|
256
|
+
include_revoked: boolean;
|
|
257
|
+
}
|
|
258
|
+
interface ClientOptions {
|
|
259
|
+
/**
|
|
260
|
+
* API key for authentication.
|
|
261
|
+
* Uses the X-FlowForge-API-Key header.
|
|
262
|
+
* Format: ff_{type}_{random} (e.g., ff_live_a1b2c3d4...)
|
|
263
|
+
*
|
|
264
|
+
* Key types:
|
|
265
|
+
* - ff_live_xxx - Production keys with full access
|
|
266
|
+
* - ff_test_xxx - Test/development keys
|
|
267
|
+
* - ff_ro_xxx - Read-only keys
|
|
268
|
+
*/
|
|
269
|
+
apiKey?: string;
|
|
270
|
+
/** Custom fetch implementation (for testing or custom environments) */
|
|
271
|
+
fetch?: typeof fetch;
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
/**
|
|
275
|
+
* FlowForge TypeScript Client - Query Builder
|
|
276
|
+
*
|
|
277
|
+
* Generic, type-safe query builder with chainable methods.
|
|
278
|
+
*/
|
|
279
|
+
|
|
280
|
+
type OrderDirection = "asc" | "desc";
|
|
281
|
+
interface QueryParams {
|
|
282
|
+
filters: Record<string, unknown>;
|
|
283
|
+
orderBy?: string;
|
|
284
|
+
orderDir?: OrderDirection;
|
|
285
|
+
limitValue?: number;
|
|
286
|
+
offsetValue?: number;
|
|
287
|
+
}
|
|
288
|
+
type RequestFn$2 = <T>(method: string, path: string, body?: unknown) => Promise<Result<T>>;
|
|
289
|
+
/**
|
|
290
|
+
* Generic query builder for type-safe filtering and pagination.
|
|
291
|
+
*
|
|
292
|
+
* @example
|
|
293
|
+
* ```ts
|
|
294
|
+
* const { data } = await builder
|
|
295
|
+
* .eq('status', 'completed')
|
|
296
|
+
* .order('created_at', 'desc')
|
|
297
|
+
* .limit(10)
|
|
298
|
+
* .execute();
|
|
299
|
+
* ```
|
|
300
|
+
*/
|
|
301
|
+
declare class QueryBuilder<T, Filters> {
|
|
302
|
+
protected request: RequestFn$2;
|
|
303
|
+
protected basePath: string;
|
|
304
|
+
protected responseKey: string;
|
|
305
|
+
protected params: QueryParams;
|
|
306
|
+
constructor(request: RequestFn$2, basePath: string, responseKey: string);
|
|
307
|
+
/**
|
|
308
|
+
* Filter by exact match.
|
|
309
|
+
*/
|
|
310
|
+
eq<K extends keyof Filters>(field: K, value: Filters[K]): this;
|
|
311
|
+
/**
|
|
312
|
+
* Order results by a field.
|
|
313
|
+
*/
|
|
314
|
+
order<K extends keyof T>(field: K, direction?: OrderDirection): this;
|
|
315
|
+
/**
|
|
316
|
+
* Limit the number of results.
|
|
317
|
+
*/
|
|
318
|
+
limit(n: number): this;
|
|
319
|
+
/**
|
|
320
|
+
* Skip the first n results (for pagination).
|
|
321
|
+
*/
|
|
322
|
+
offset(n: number): this;
|
|
323
|
+
/**
|
|
324
|
+
* Build query string from params.
|
|
325
|
+
*/
|
|
326
|
+
protected buildQueryString(): string;
|
|
327
|
+
/**
|
|
328
|
+
* Execute the query and return multiple results.
|
|
329
|
+
*/
|
|
330
|
+
execute(): Promise<Result<T[]>>;
|
|
331
|
+
/**
|
|
332
|
+
* Execute the query and return a single result.
|
|
333
|
+
* Returns an error if no results found.
|
|
334
|
+
*/
|
|
335
|
+
single(): Promise<Result<T>>;
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
/**
|
|
339
|
+
* FlowForge TypeScript Client - Events Resource
|
|
340
|
+
*/
|
|
341
|
+
|
|
342
|
+
declare class EventsResource {
|
|
343
|
+
private request;
|
|
344
|
+
constructor(request: RequestFn$2);
|
|
345
|
+
/**
|
|
346
|
+
* Send an event to trigger matching workflows.
|
|
347
|
+
*
|
|
348
|
+
* @example
|
|
349
|
+
* ```ts
|
|
350
|
+
* const { data, error } = await ff.events.send('order/created', {
|
|
351
|
+
* order_id: '123',
|
|
352
|
+
* customer: 'Alice'
|
|
353
|
+
* });
|
|
354
|
+
* if (error) console.error(error.message);
|
|
355
|
+
* else console.log('Triggered runs:', data.runs);
|
|
356
|
+
* ```
|
|
357
|
+
*/
|
|
358
|
+
send(name: string, data: Record<string, unknown>, options?: SendEventInput): Promise<Result<SendEventResponse>>;
|
|
359
|
+
/**
|
|
360
|
+
* Get a specific event by ID.
|
|
361
|
+
*
|
|
362
|
+
* @example
|
|
363
|
+
* ```ts
|
|
364
|
+
* const { data: event } = await ff.events.get('event-id');
|
|
365
|
+
* ```
|
|
366
|
+
*/
|
|
367
|
+
get(eventId: string): Promise<Result<Event>>;
|
|
368
|
+
/**
|
|
369
|
+
* Start building a query to select events.
|
|
370
|
+
*
|
|
371
|
+
* @example
|
|
372
|
+
* ```ts
|
|
373
|
+
* const { data: events } = await ff.events
|
|
374
|
+
* .select()
|
|
375
|
+
* .eq('name', 'order/*')
|
|
376
|
+
* .limit(10)
|
|
377
|
+
* .execute();
|
|
378
|
+
* ```
|
|
379
|
+
*/
|
|
380
|
+
select(): QueryBuilder<Event, EventFilters>;
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
/**
|
|
384
|
+
* FlowForge TypeScript Client - Runs Resource
|
|
385
|
+
*/
|
|
386
|
+
|
|
387
|
+
declare class RunsResource {
|
|
388
|
+
private request;
|
|
389
|
+
constructor(request: RequestFn$2);
|
|
390
|
+
/**
|
|
391
|
+
* Get a run by ID, including its steps.
|
|
392
|
+
*
|
|
393
|
+
* @example
|
|
394
|
+
* ```ts
|
|
395
|
+
* const { data: run } = await ff.runs.get('run-id');
|
|
396
|
+
* console.log(run.status, run.steps);
|
|
397
|
+
* ```
|
|
398
|
+
*/
|
|
399
|
+
get(runId: string): Promise<Result<RunWithSteps>>;
|
|
400
|
+
/**
|
|
401
|
+
* Start building a query to select runs.
|
|
402
|
+
*
|
|
403
|
+
* @example
|
|
404
|
+
* ```ts
|
|
405
|
+
* const { data: runs } = await ff.runs
|
|
406
|
+
* .select()
|
|
407
|
+
* .eq('status', 'completed')
|
|
408
|
+
* .order('created_at', 'desc')
|
|
409
|
+
* .limit(10)
|
|
410
|
+
* .execute();
|
|
411
|
+
* ```
|
|
412
|
+
*/
|
|
413
|
+
select(): QueryBuilder<Run, RunFilters>;
|
|
414
|
+
/**
|
|
415
|
+
* Cancel a running workflow.
|
|
416
|
+
*
|
|
417
|
+
* @example
|
|
418
|
+
* ```ts
|
|
419
|
+
* const { error } = await ff.runs.cancel('run-id');
|
|
420
|
+
* if (error) console.error('Failed to cancel:', error.message);
|
|
421
|
+
* ```
|
|
422
|
+
*/
|
|
423
|
+
cancel(runId: string): Promise<Result<{
|
|
424
|
+
success: boolean;
|
|
425
|
+
message: string;
|
|
426
|
+
}>>;
|
|
427
|
+
/**
|
|
428
|
+
* Replay a completed or failed run.
|
|
429
|
+
*
|
|
430
|
+
* @example
|
|
431
|
+
* ```ts
|
|
432
|
+
* const { data: newRun } = await ff.runs.replay('run-id');
|
|
433
|
+
* console.log('New run ID:', newRun.id);
|
|
434
|
+
* ```
|
|
435
|
+
*/
|
|
436
|
+
replay(runId: string): Promise<Result<RunWithSteps>>;
|
|
437
|
+
/**
|
|
438
|
+
* Wait for a run to complete (polling).
|
|
439
|
+
*
|
|
440
|
+
* @example
|
|
441
|
+
* ```ts
|
|
442
|
+
* const { data: completedRun, error } = await ff.runs.waitFor('run-id', {
|
|
443
|
+
* timeout: 60000
|
|
444
|
+
* });
|
|
445
|
+
* if (error) console.error('Timeout or error:', error.message);
|
|
446
|
+
* else console.log('Run completed with status:', completedRun.status);
|
|
447
|
+
* ```
|
|
448
|
+
*/
|
|
449
|
+
waitFor(runId: string, options?: {
|
|
450
|
+
timeout?: number;
|
|
451
|
+
interval?: number;
|
|
452
|
+
}): Promise<Result<RunWithSteps>>;
|
|
453
|
+
}
|
|
454
|
+
|
|
455
|
+
/**
|
|
456
|
+
* FlowForge TypeScript Client - Functions Resource
|
|
457
|
+
*/
|
|
458
|
+
|
|
459
|
+
declare class FunctionsResource {
|
|
460
|
+
private request;
|
|
461
|
+
constructor(request: RequestFn$2);
|
|
462
|
+
/**
|
|
463
|
+
* Get a function by ID.
|
|
464
|
+
*
|
|
465
|
+
* @example
|
|
466
|
+
* ```ts
|
|
467
|
+
* const { data: fn } = await ff.functions.get('my-function');
|
|
468
|
+
* console.log(fn.name, fn.is_active);
|
|
469
|
+
* ```
|
|
470
|
+
*/
|
|
471
|
+
get(functionId: string): Promise<Result<FlowForgeFunction>>;
|
|
472
|
+
/**
|
|
473
|
+
* Start building a query to select functions.
|
|
474
|
+
*
|
|
475
|
+
* @example
|
|
476
|
+
* ```ts
|
|
477
|
+
* const { data: fns } = await ff.functions
|
|
478
|
+
* .select()
|
|
479
|
+
* .eq('is_active', true)
|
|
480
|
+
* .eq('trigger_type', 'event')
|
|
481
|
+
* .execute();
|
|
482
|
+
* ```
|
|
483
|
+
*/
|
|
484
|
+
select(): QueryBuilder<FlowForgeFunction, FunctionFilters>;
|
|
485
|
+
/**
|
|
486
|
+
* Create a new function.
|
|
487
|
+
*
|
|
488
|
+
* @example
|
|
489
|
+
* ```ts
|
|
490
|
+
* const { data: fn, error } = await ff.functions.create({
|
|
491
|
+
* id: 'order-processor',
|
|
492
|
+
* name: 'Order Processor',
|
|
493
|
+
* trigger_type: 'event',
|
|
494
|
+
* trigger_value: 'order/created',
|
|
495
|
+
* endpoint_url: 'http://localhost:3000/api/workflows/order',
|
|
496
|
+
* });
|
|
497
|
+
* ```
|
|
498
|
+
*/
|
|
499
|
+
create(input: CreateFunctionInput): Promise<Result<FlowForgeFunction>>;
|
|
500
|
+
/**
|
|
501
|
+
* Update an existing function.
|
|
502
|
+
*
|
|
503
|
+
* @example
|
|
504
|
+
* ```ts
|
|
505
|
+
* const { error } = await ff.functions.update('my-function', {
|
|
506
|
+
* is_active: false
|
|
507
|
+
* });
|
|
508
|
+
* ```
|
|
509
|
+
*/
|
|
510
|
+
update(functionId: string, input: UpdateFunctionInput): Promise<Result<FlowForgeFunction>>;
|
|
511
|
+
/**
|
|
512
|
+
* Delete a function.
|
|
513
|
+
*
|
|
514
|
+
* @example
|
|
515
|
+
* ```ts
|
|
516
|
+
* const { error } = await ff.functions.delete('my-function');
|
|
517
|
+
* if (error) console.error('Failed to delete:', error.message);
|
|
518
|
+
* ```
|
|
519
|
+
*/
|
|
520
|
+
delete(functionId: string): Promise<Result<{
|
|
521
|
+
success: boolean;
|
|
522
|
+
message: string;
|
|
523
|
+
}>>;
|
|
524
|
+
}
|
|
525
|
+
|
|
526
|
+
/**
|
|
527
|
+
* FlowForge TypeScript Client - Tools Resource
|
|
528
|
+
*/
|
|
529
|
+
|
|
530
|
+
declare class ToolsResource {
|
|
531
|
+
private request;
|
|
532
|
+
constructor(request: RequestFn$2);
|
|
533
|
+
/**
|
|
534
|
+
* Get a tool by name.
|
|
535
|
+
*
|
|
536
|
+
* @example
|
|
537
|
+
* ```ts
|
|
538
|
+
* const { data: tool } = await ff.tools.get('send-email');
|
|
539
|
+
* console.log(tool.description, tool.requires_approval);
|
|
540
|
+
* ```
|
|
541
|
+
*/
|
|
542
|
+
get(toolName: string): Promise<Result<Tool>>;
|
|
543
|
+
/**
|
|
544
|
+
* Start building a query to select tools.
|
|
545
|
+
*
|
|
546
|
+
* @example
|
|
547
|
+
* ```ts
|
|
548
|
+
* const { data: tools } = await ff.tools
|
|
549
|
+
* .select()
|
|
550
|
+
* .eq('requires_approval', true)
|
|
551
|
+
* .eq('is_active', true)
|
|
552
|
+
* .execute();
|
|
553
|
+
* ```
|
|
554
|
+
*/
|
|
555
|
+
select(): QueryBuilder<Tool, ToolFilters>;
|
|
556
|
+
/**
|
|
557
|
+
* Create a new tool.
|
|
558
|
+
*
|
|
559
|
+
* @example
|
|
560
|
+
* ```ts
|
|
561
|
+
* const { data: tool, error } = await ff.tools.create({
|
|
562
|
+
* name: 'send-email',
|
|
563
|
+
* description: 'Send an email to a recipient',
|
|
564
|
+
* parameters: {
|
|
565
|
+
* type: 'object',
|
|
566
|
+
* properties: {
|
|
567
|
+
* to: { type: 'string', description: 'Recipient email' },
|
|
568
|
+
* subject: { type: 'string', description: 'Email subject' },
|
|
569
|
+
* body: { type: 'string', description: 'Email body' },
|
|
570
|
+
* },
|
|
571
|
+
* required: ['to', 'subject', 'body'],
|
|
572
|
+
* },
|
|
573
|
+
* requires_approval: true,
|
|
574
|
+
* });
|
|
575
|
+
* ```
|
|
576
|
+
*/
|
|
577
|
+
create(input: CreateToolInput): Promise<Result<Tool>>;
|
|
578
|
+
/**
|
|
579
|
+
* Update an existing tool.
|
|
580
|
+
*
|
|
581
|
+
* @example
|
|
582
|
+
* ```ts
|
|
583
|
+
* const { error } = await ff.tools.update('send-email', {
|
|
584
|
+
* requires_approval: false
|
|
585
|
+
* });
|
|
586
|
+
* ```
|
|
587
|
+
*/
|
|
588
|
+
update(toolName: string, input: UpdateToolInput): Promise<Result<Tool>>;
|
|
589
|
+
/**
|
|
590
|
+
* Delete a tool.
|
|
591
|
+
*
|
|
592
|
+
* @example
|
|
593
|
+
* ```ts
|
|
594
|
+
* const { error } = await ff.tools.delete('my-tool');
|
|
595
|
+
* if (error) console.error('Failed to delete:', error.message);
|
|
596
|
+
* ```
|
|
597
|
+
*/
|
|
598
|
+
delete(toolName: string): Promise<Result<{
|
|
599
|
+
success: boolean;
|
|
600
|
+
message: string;
|
|
601
|
+
}>>;
|
|
602
|
+
}
|
|
603
|
+
|
|
604
|
+
/**
|
|
605
|
+
* FlowForge TypeScript Client - Approvals Resource
|
|
606
|
+
*
|
|
607
|
+
* Human-in-the-loop approval management for tool calls.
|
|
608
|
+
*/
|
|
609
|
+
|
|
610
|
+
declare class ApprovalsResource {
|
|
611
|
+
private request;
|
|
612
|
+
constructor(request: RequestFn$2);
|
|
613
|
+
/**
|
|
614
|
+
* Get an approval by ID.
|
|
615
|
+
*
|
|
616
|
+
* @example
|
|
617
|
+
* ```ts
|
|
618
|
+
* const { data: approval } = await ff.approvals.get('approval-id');
|
|
619
|
+
* console.log(approval.tool_name, approval.status);
|
|
620
|
+
* ```
|
|
621
|
+
*/
|
|
622
|
+
get(approvalId: string): Promise<Result<Approval>>;
|
|
623
|
+
/**
|
|
624
|
+
* Start building a query to select approvals.
|
|
625
|
+
*
|
|
626
|
+
* @example
|
|
627
|
+
* ```ts
|
|
628
|
+
* const { data: pending } = await ff.approvals
|
|
629
|
+
* .select()
|
|
630
|
+
* .eq('status', 'pending')
|
|
631
|
+
* .execute();
|
|
632
|
+
* ```
|
|
633
|
+
*/
|
|
634
|
+
select(): QueryBuilder<Approval, ApprovalFilters>;
|
|
635
|
+
/**
|
|
636
|
+
* Approve a pending tool call.
|
|
637
|
+
*
|
|
638
|
+
* @example
|
|
639
|
+
* ```ts
|
|
640
|
+
* const { error } = await ff.approvals.approve('approval-id');
|
|
641
|
+
* if (error) console.error('Failed to approve:', error.message);
|
|
642
|
+
* ```
|
|
643
|
+
*
|
|
644
|
+
* @example With modified arguments
|
|
645
|
+
* ```ts
|
|
646
|
+
* const { error } = await ff.approvals.approve('approval-id', {
|
|
647
|
+
* modifiedArguments: { amount: 50 } // Override the original amount
|
|
648
|
+
* });
|
|
649
|
+
* ```
|
|
650
|
+
*/
|
|
651
|
+
approve(approvalId: string, options?: {
|
|
652
|
+
modifiedArguments?: Record<string, unknown>;
|
|
653
|
+
}): Promise<Result<{
|
|
654
|
+
success: boolean;
|
|
655
|
+
message: string;
|
|
656
|
+
}>>;
|
|
657
|
+
/**
|
|
658
|
+
* Reject a pending tool call.
|
|
659
|
+
*
|
|
660
|
+
* @example
|
|
661
|
+
* ```ts
|
|
662
|
+
* const { error } = await ff.approvals.reject('approval-id', 'Too risky');
|
|
663
|
+
* if (error) console.error('Failed to reject:', error.message);
|
|
664
|
+
* ```
|
|
665
|
+
*/
|
|
666
|
+
reject(approvalId: string, reason: string): Promise<Result<{
|
|
667
|
+
success: boolean;
|
|
668
|
+
message: string;
|
|
669
|
+
}>>;
|
|
670
|
+
}
|
|
671
|
+
|
|
672
|
+
/**
|
|
673
|
+
* FlowForge TypeScript Client - Health Resource
|
|
674
|
+
*/
|
|
675
|
+
|
|
676
|
+
declare class HealthResource {
|
|
677
|
+
private request;
|
|
678
|
+
constructor(request: RequestFn$2);
|
|
679
|
+
/**
|
|
680
|
+
* Check if the server is healthy.
|
|
681
|
+
*
|
|
682
|
+
* @example
|
|
683
|
+
* ```ts
|
|
684
|
+
* const { data: healthy, error } = await ff.health.check();
|
|
685
|
+
* if (healthy) console.log('Server is healthy');
|
|
686
|
+
* else console.error('Server is unhealthy:', error?.message);
|
|
687
|
+
* ```
|
|
688
|
+
*/
|
|
689
|
+
check(): Promise<Result<boolean>>;
|
|
690
|
+
/**
|
|
691
|
+
* Get server statistics.
|
|
692
|
+
*
|
|
693
|
+
* @example
|
|
694
|
+
* ```ts
|
|
695
|
+
* const { data: stats } = await ff.health.stats();
|
|
696
|
+
* console.log('Total runs:', stats.runs.total);
|
|
697
|
+
* console.log('Active functions:', stats.functions.active);
|
|
698
|
+
* ```
|
|
699
|
+
*/
|
|
700
|
+
stats(): Promise<Result<Stats>>;
|
|
701
|
+
}
|
|
702
|
+
|
|
703
|
+
/**
|
|
704
|
+
* FlowForge TypeScript Client - Users Resource
|
|
705
|
+
*
|
|
706
|
+
* Note: The SDK uses API key authentication only (X-FlowForge-API-Key header).
|
|
707
|
+
* User/password login is only available through the dashboard.
|
|
708
|
+
*/
|
|
709
|
+
|
|
710
|
+
type RequestFn$1 = <T>(method: string, path: string, body?: unknown) => Promise<Result<T>>;
|
|
711
|
+
/**
|
|
712
|
+
* Users resource for user management (admin API key required).
|
|
713
|
+
*
|
|
714
|
+
* Note: This resource requires an admin-level API key.
|
|
715
|
+
* User/password login is only available through the dashboard.
|
|
716
|
+
*/
|
|
717
|
+
declare class UsersResource {
|
|
718
|
+
private request;
|
|
719
|
+
constructor(request: RequestFn$1);
|
|
720
|
+
/**
|
|
721
|
+
* List all users (admin only).
|
|
722
|
+
*
|
|
723
|
+
* @param options - Filter options
|
|
724
|
+
* @returns List of users
|
|
725
|
+
*
|
|
726
|
+
* @example
|
|
727
|
+
* ```ts
|
|
728
|
+
* const { data } = await ff.users.list({ includeInactive: true });
|
|
729
|
+
* console.log('Total users:', data?.total);
|
|
730
|
+
* ```
|
|
731
|
+
*/
|
|
732
|
+
list(options?: {
|
|
733
|
+
includeInactive?: boolean;
|
|
734
|
+
}): Promise<Result<UsersResponse>>;
|
|
735
|
+
/**
|
|
736
|
+
* Get a user by ID (admin only).
|
|
737
|
+
*
|
|
738
|
+
* @param userId - User ID
|
|
739
|
+
* @returns User details
|
|
740
|
+
*/
|
|
741
|
+
get(userId: string): Promise<Result<User>>;
|
|
742
|
+
/**
|
|
743
|
+
* Create a new user (admin only).
|
|
744
|
+
*
|
|
745
|
+
* @param input - User details
|
|
746
|
+
* @returns Created user
|
|
747
|
+
*
|
|
748
|
+
* @example
|
|
749
|
+
* ```ts
|
|
750
|
+
* const { data, error } = await ff.users.create({
|
|
751
|
+
* email: 'user@example.com',
|
|
752
|
+
* password: 'securepassword',
|
|
753
|
+
* name: 'John Doe',
|
|
754
|
+
* role: 'member'
|
|
755
|
+
* });
|
|
756
|
+
* ```
|
|
757
|
+
*/
|
|
758
|
+
create(input: CreateUserInput): Promise<Result<User>>;
|
|
759
|
+
/**
|
|
760
|
+
* Update a user (admin only).
|
|
761
|
+
*
|
|
762
|
+
* @param userId - User ID
|
|
763
|
+
* @param input - Fields to update
|
|
764
|
+
* @returns Updated user
|
|
765
|
+
*/
|
|
766
|
+
update(userId: string, input: UpdateUserInput): Promise<Result<User>>;
|
|
767
|
+
/**
|
|
768
|
+
* Delete a user (admin only).
|
|
769
|
+
*
|
|
770
|
+
* @param userId - User ID
|
|
771
|
+
* @returns Success message
|
|
772
|
+
*/
|
|
773
|
+
delete(userId: string): Promise<Result<{
|
|
774
|
+
message: string;
|
|
775
|
+
}>>;
|
|
776
|
+
}
|
|
777
|
+
|
|
778
|
+
/**
|
|
779
|
+
* FlowForge TypeScript Client - API Keys Resource
|
|
780
|
+
*/
|
|
781
|
+
|
|
782
|
+
type RequestFn = <T>(method: string, path: string, body?: unknown) => Promise<Result<T>>;
|
|
783
|
+
/**
|
|
784
|
+
* API Keys resource for managing API key authentication.
|
|
785
|
+
*/
|
|
786
|
+
declare class ApiKeysResource {
|
|
787
|
+
private request;
|
|
788
|
+
constructor(request: RequestFn);
|
|
789
|
+
/**
|
|
790
|
+
* List all API keys for the tenant.
|
|
791
|
+
*
|
|
792
|
+
* @param options - Filter options
|
|
793
|
+
* @returns List of API keys (without the actual key values)
|
|
794
|
+
*
|
|
795
|
+
* @example
|
|
796
|
+
* ```ts
|
|
797
|
+
* const { data } = await ff.apiKeys.list();
|
|
798
|
+
* data?.keys.forEach(key => {
|
|
799
|
+
* console.log(`${key.name}: ${key.key_prefix}... (${key.key_type})`);
|
|
800
|
+
* });
|
|
801
|
+
* ```
|
|
802
|
+
*/
|
|
803
|
+
list(options?: {
|
|
804
|
+
includeRevoked?: boolean;
|
|
805
|
+
}): Promise<Result<ApiKeysResponse>>;
|
|
806
|
+
/**
|
|
807
|
+
* Get an API key by ID.
|
|
808
|
+
*
|
|
809
|
+
* @param keyId - API key ID
|
|
810
|
+
* @returns API key details (without the actual key value)
|
|
811
|
+
*/
|
|
812
|
+
get(keyId: string): Promise<Result<ApiKey>>;
|
|
813
|
+
/**
|
|
814
|
+
* Create a new API key.
|
|
815
|
+
*
|
|
816
|
+
* @param input - API key configuration
|
|
817
|
+
* @returns Created API key WITH the actual key value (only returned once!)
|
|
818
|
+
*
|
|
819
|
+
* @example
|
|
820
|
+
* ```ts
|
|
821
|
+
* const { data, error } = await ff.apiKeys.create({
|
|
822
|
+
* name: 'Production API Key',
|
|
823
|
+
* key_type: 'live',
|
|
824
|
+
* scopes: ['events:send', 'runs:read']
|
|
825
|
+
* });
|
|
826
|
+
*
|
|
827
|
+
* if (data) {
|
|
828
|
+
* // IMPORTANT: Store this key - it won't be shown again!
|
|
829
|
+
* console.log('New API key:', data.key); // ff_live_a1b2c3...
|
|
830
|
+
* }
|
|
831
|
+
* ```
|
|
832
|
+
*/
|
|
833
|
+
create(input: CreateApiKeyInput): Promise<Result<ApiKeyCreated>>;
|
|
834
|
+
/**
|
|
835
|
+
* Revoke an API key.
|
|
836
|
+
*
|
|
837
|
+
* @param keyId - API key ID
|
|
838
|
+
* @param reason - Optional reason for revocation
|
|
839
|
+
* @returns Success message
|
|
840
|
+
*
|
|
841
|
+
* @example
|
|
842
|
+
* ```ts
|
|
843
|
+
* const { error } = await ff.apiKeys.revoke('key-id', 'Compromised');
|
|
844
|
+
* if (!error) {
|
|
845
|
+
* console.log('Key revoked successfully');
|
|
846
|
+
* }
|
|
847
|
+
* ```
|
|
848
|
+
*/
|
|
849
|
+
revoke(keyId: string, reason?: string): Promise<Result<{
|
|
850
|
+
message: string;
|
|
851
|
+
}>>;
|
|
852
|
+
}
|
|
853
|
+
|
|
854
|
+
/**
|
|
855
|
+
* FlowForge TypeScript Client - Main Client Factory
|
|
856
|
+
*/
|
|
857
|
+
|
|
858
|
+
/**
|
|
859
|
+
* FlowForge client instance with typed resource accessors.
|
|
860
|
+
*/
|
|
861
|
+
interface FlowForgeClient {
|
|
862
|
+
/** Events resource - send and query events */
|
|
863
|
+
events: EventsResource;
|
|
864
|
+
/** Runs resource - query and manage workflow runs */
|
|
865
|
+
runs: RunsResource;
|
|
866
|
+
/** Functions resource - manage workflow functions */
|
|
867
|
+
functions: FunctionsResource;
|
|
868
|
+
/** Tools resource - manage AI tools */
|
|
869
|
+
tools: ToolsResource;
|
|
870
|
+
/** Approvals resource - human-in-the-loop approvals */
|
|
871
|
+
approvals: ApprovalsResource;
|
|
872
|
+
/** Health resource - server health and stats */
|
|
873
|
+
health: HealthResource;
|
|
874
|
+
/** Users resource - authentication and user management */
|
|
875
|
+
users: UsersResource;
|
|
876
|
+
/** API Keys resource - manage API key authentication */
|
|
877
|
+
apiKeys: ApiKeysResource;
|
|
878
|
+
}
|
|
879
|
+
/**
|
|
880
|
+
* Create a FlowForge client instance.
|
|
881
|
+
*
|
|
882
|
+
* @param baseUrl - The base URL of the FlowForge server
|
|
883
|
+
* @param options - Optional client configuration
|
|
884
|
+
* @returns A FlowForge client instance
|
|
885
|
+
*
|
|
886
|
+
* @example Basic usage
|
|
887
|
+
* ```ts
|
|
888
|
+
* import { createClient } from 'flowforge-client';
|
|
889
|
+
*
|
|
890
|
+
* const ff = createClient('http://localhost:8000');
|
|
891
|
+
*
|
|
892
|
+
* // Send an event
|
|
893
|
+
* const { data, error } = await ff.events.send('order/created', {
|
|
894
|
+
* order_id: '123',
|
|
895
|
+
* customer: 'Alice'
|
|
896
|
+
* });
|
|
897
|
+
* ```
|
|
898
|
+
*
|
|
899
|
+
* @example With API key
|
|
900
|
+
* ```ts
|
|
901
|
+
* const ff = createClient('http://localhost:8000', {
|
|
902
|
+
* apiKey: process.env.FLOWFORGE_API_KEY // ff_live_xxx
|
|
903
|
+
* });
|
|
904
|
+
* ```
|
|
905
|
+
*/
|
|
906
|
+
declare function createClient(baseUrl: string, options?: ClientOptions): FlowForgeClient;
|
|
907
|
+
|
|
908
|
+
export { type ApiKey, type ApiKeyCreated, type ApiKeyFilters, type ApiKeyType, ApiKeysResource, type ApiKeysResponse, type Approval, type ApprovalFilters, type ApprovalStatus, ApprovalsResource, type ClientOptions, type CreateApiKeyInput, type CreateFunctionInput, type CreateToolInput, type CreateUserInput, type Event, type EventFilters, EventsResource, type FlowForgeClient, FlowForgeError, type FlowForgeFunction, type FunctionFilters, FunctionsResource, HealthResource, type HealthStatus, type OrderDirection, QueryBuilder, type QueryParams, type Result, type Run, type RunFilters, type RunStatus, type RunWithSteps, RunsResource, type SendEventInput, type SendEventResponse, type Stats, type Step, type StepStatus, type StepType, type Tool, type ToolFilters, ToolsResource, type TriggerType, type UpdateFunctionInput, type UpdateToolInput, type UpdateUserInput, type User, type UserRole, UsersResource, type UsersResponse, createClient };
|