@picsart/ai-sdk 5.39.0 → 6.0.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/README.md +87 -19
- package/_vendor/workflows-client/index.d.ts +246 -6
- package/chunk-4VNS5WPM.js +37 -0
- package/esm-debug-3SQICTIF.js +8341 -0
- package/index.d.ts +278 -194
- package/index.js +2536 -1939
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -77,6 +77,58 @@ const ai = createClient({
|
|
|
77
77
|
|
|
78
78
|
`createClient` throws if neither `apiKey` nor `fetch` is provided.
|
|
79
79
|
|
|
80
|
+
## Custom Transport
|
|
81
|
+
|
|
82
|
+
`fetch` swaps out how a request is authenticated; `transport` swaps out the
|
|
83
|
+
requests themselves. Pass one and the SDK stops talking to the workflows API
|
|
84
|
+
altogether — every generation, poll, catalog load and credit estimate goes
|
|
85
|
+
through your implementation instead:
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
88
|
+
const ai = createClient({ transport: myTransport })
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
`apiUrl` and the auth source are yours to bake into the transport, so neither is
|
|
92
|
+
required alongside it. Two surfaces still speak the workflows protocol directly
|
|
93
|
+
and keep needing `apiUrl` plus `fetch`/`apiKey` if you use them: `ai.drive` and
|
|
94
|
+
`ai.apis`.
|
|
95
|
+
|
|
96
|
+
| Method | Required | Serves |
|
|
97
|
+
|--------|----------|--------|
|
|
98
|
+
| `execute(request)` | yes | `syncExecute` models, catalog tasks, and every generation when `submit`/`poll` are absent |
|
|
99
|
+
| `submit(request)` | no | `generate()`, `submit()` — returns the generation id |
|
|
100
|
+
| `poll(handle, options)` | no | `generate()`, `result()`, `subscribe()` — resolves when the job is terminal, calls `options.onProgress` on the way |
|
|
101
|
+
| `status(handle, signal?)` | no | the edit-route probe behind `result(model, id)` on models that have one |
|
|
102
|
+
| `options(workflow, payload)` | no | `getCredits()` — returns credits, or null |
|
|
103
|
+
|
|
104
|
+
Leave `submit`/`poll` out and the client runs **every** generation through
|
|
105
|
+
`execute()`; the async lifecycle (`submit()` / `result()` / `subscribe()`) then
|
|
106
|
+
rejects with a 400 `unsupported_transport` rather than pretending. Leave
|
|
107
|
+
`options` out and `getCredits()` answers null.
|
|
108
|
+
|
|
109
|
+
```typescript
|
|
110
|
+
import type { SdkTransport } from '@picsart/ai-sdk'
|
|
111
|
+
|
|
112
|
+
const myTransport: SdkTransport = {
|
|
113
|
+
async execute({ workflow, payload, signal }) {
|
|
114
|
+
const res = await callMyGateway(workflow, payload, signal)
|
|
115
|
+
return { result: res.output, usage: res.usage }
|
|
116
|
+
},
|
|
117
|
+
async submit({ workflow, payload }) {
|
|
118
|
+
return (await startMyJob(workflow, payload)).id
|
|
119
|
+
},
|
|
120
|
+
async poll(handle, options) {
|
|
121
|
+
const res = await waitForMyJob(handle.id, options)
|
|
122
|
+
return { result: res.output, usage: res.usage }
|
|
123
|
+
},
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Throw `ApiError` for failures — anything else reaches the caller as a 502
|
|
128
|
+
`generation_failed`. A failed job may also resolve with the platform's
|
|
129
|
+
`{ message, reason, statusCode }` payload as its `result`; the SDK turns that
|
|
130
|
+
into the matching `ApiError` itself.
|
|
131
|
+
|
|
80
132
|
## Drive Integration
|
|
81
133
|
|
|
82
134
|
Auto-save generations to Picsart Drive:
|
|
@@ -173,21 +225,30 @@ validates for real.
|
|
|
173
225
|
|
|
174
226
|
## Advanced Lifecycle
|
|
175
227
|
|
|
176
|
-
For progress tracking
|
|
228
|
+
For progress tracking and job recovery:
|
|
177
229
|
|
|
178
230
|
```typescript
|
|
179
|
-
// Submit without waiting
|
|
180
|
-
const
|
|
181
|
-
|
|
182
|
-
// Subscribe to
|
|
183
|
-
|
|
184
|
-
|
|
231
|
+
// Submit without waiting — returns the generation id (a string)
|
|
232
|
+
const generationId = await ai.submit(Models.KlingV3, { prompt: 'a sunset' })
|
|
233
|
+
|
|
234
|
+
// Subscribe to updates — the terminal generation.completed event carries the
|
|
235
|
+
// parsed result, so no follow-up result() call is needed
|
|
236
|
+
for await (const e of ai.subscribe(Models.KlingV3, generationId)) {
|
|
237
|
+
if (e.type === 'generation.progress') console.log(e.progress?.percent)
|
|
238
|
+
if (e.type === 'generation.completed') console.log(e.result.url)
|
|
239
|
+
if (e.type === 'generation.failed') console.error(e.error.message)
|
|
185
240
|
}
|
|
186
241
|
|
|
187
|
-
// Or
|
|
188
|
-
const
|
|
242
|
+
// Or just wait for the parsed result (throws on failure/cancel)
|
|
243
|
+
const result = await ai.result(Models.KlingV3, generationId, { intervalMs: 2000 })
|
|
244
|
+
|
|
245
|
+
// One-shot snapshot of a stored id (e.g. after a page reload)
|
|
246
|
+
const { value: snapshot } = await ai.subscribe(Models.KlingV3, generationId).next()
|
|
189
247
|
```
|
|
190
248
|
|
|
249
|
+
Generation ids are plain strings — store them and recover jobs later with
|
|
250
|
+
`result(model, id)` or `subscribe(model, id)`.
|
|
251
|
+
|
|
191
252
|
## Error Handling
|
|
192
253
|
|
|
193
254
|
Every failure thrown by `generate()`, `generateText()`, `submit()`, and `result()`
|
|
@@ -240,19 +301,26 @@ Aborts raised by `fetch` itself are deliberately **not** wrapped, so
|
|
|
240
301
|
`message` is human-readable and may change between versions — branch on `status`
|
|
241
302
|
and `code`, not on the message text.
|
|
242
303
|
|
|
304
|
+
`ApiError` is the only error type the SDK throws: `ai.apis` and `ai.catalogs`
|
|
305
|
+
report failures the same way, and a custom transport's own error is mapped too
|
|
306
|
+
(a 502 `generation_failed` when it isn't already an `ApiError`).
|
|
307
|
+
|
|
243
308
|
## Public API
|
|
244
309
|
|
|
245
|
-
|
|
310
|
+
Key exports (see `src/index.ts` for the full list):
|
|
246
311
|
|
|
247
312
|
| Export | Type | Description |
|
|
248
313
|
|--------|------|-------------|
|
|
249
314
|
| `createClient` | function | Create an AI client from an API key (or a custom authenticated fetch) |
|
|
250
|
-
| `Models` | object |
|
|
251
|
-
| `
|
|
252
|
-
| `
|
|
315
|
+
| `Models` | object | Typed model-id constants (`Models.Flux2Pro` → `'flux-2-pro'`) |
|
|
316
|
+
| `Model`, `catalog` | function / object | Model metadata, params, validation, discovery |
|
|
317
|
+
| `GenerateResult` | type | `{ url, items: [{ url, metadata? }], generationId, usage?, drive? }` |
|
|
318
|
+
| `GenerationEvent` | type | One `ai.subscribe()` update — `generation.progress` / `.completed` / `.failed` |
|
|
319
|
+
| `GenerationEventType` | const | Named event-type constants (`GenerationEventType.Completed` === `'generation.completed'`) |
|
|
320
|
+
| `ClientConfig` | type | `{ apiKey?, fetch?, apiUrl, drive?, transport? }` — one of `apiKey` / `fetch` required unless `transport` is set |
|
|
253
321
|
| `AuthenticatedFetch` | type | `(url, init?) => Promise<Response>` — for the custom-`fetch` path |
|
|
254
|
-
| `SdkTransport` | type |
|
|
255
|
-
| `
|
|
322
|
+
| `SdkTransport` | type | The transport contract — see [Custom Transport](#custom-transport) |
|
|
323
|
+
| `GenerationOptions` | type | Poll controls for `result()`/`subscribe()` — `{ intervalMs?, maxAttempts?, signal? }` |
|
|
256
324
|
| `ApiError` | class | Unified error: `{ status, code, reason, message }` — see [Error Handling](#error-handling) |
|
|
257
325
|
|
|
258
326
|
## Package Structure
|
|
@@ -263,16 +331,16 @@ packages/ai-sdk/
|
|
|
263
331
|
tsconfig.json
|
|
264
332
|
tsup.config.ts
|
|
265
333
|
src/
|
|
266
|
-
index.ts # Public API entry
|
|
334
|
+
index.ts # Public API entry
|
|
267
335
|
client/
|
|
268
336
|
types.ts # ClientConfig, GenerateResult, DriveConfig
|
|
269
|
-
transport.ts #
|
|
337
|
+
transport.ts # Default SdkTransport, over @picsart/workflows-client
|
|
270
338
|
prepare.ts # Validate input, build payload, parse result
|
|
271
339
|
drive.ts # Drive folder management + file saving
|
|
272
340
|
index.ts # createClient() factory
|
|
273
341
|
core/
|
|
274
342
|
types.ts # ModelDefinition, ParamConfig, GenerationContext
|
|
275
|
-
workflow.ts #
|
|
343
|
+
workflow.ts # Task envelope types + the SdkTransport contract
|
|
276
344
|
contracts.ts # Runtime input validation
|
|
277
345
|
schema.ts # ParamConfig → JSON Schema
|
|
278
346
|
response.ts # Vendor-agnostic result extraction
|
|
@@ -282,7 +350,7 @@ packages/ai-sdk/
|
|
|
282
350
|
voices.ts # Voice catalogs (ElevenLabs, OpenAI, Gemini)
|
|
283
351
|
helpers.ts # Vendor utilities
|
|
284
352
|
generated/
|
|
285
|
-
model-constants.ts # AUTO-GENERATED: Models object +
|
|
353
|
+
model-constants.ts # AUTO-GENERATED: Models object + id constants
|
|
286
354
|
model-input-types.ts # AUTO-GENERATED: per-model TypeScript input types
|
|
287
355
|
vendors/
|
|
288
356
|
define.ts # defineModels() framework + params.* helpers
|
|
@@ -40,6 +40,14 @@ type PartialWorkflowResult<R> = {
|
|
|
40
40
|
status: WorkflowStatus;
|
|
41
41
|
result: R;
|
|
42
42
|
};
|
|
43
|
+
interface WorkflowOptions {
|
|
44
|
+
monetization?: {
|
|
45
|
+
toolId: string;
|
|
46
|
+
};
|
|
47
|
+
usageAmount?: number;
|
|
48
|
+
credits?: number;
|
|
49
|
+
originalCredits?: number;
|
|
50
|
+
}
|
|
43
51
|
type HistoryResponse<R> = PicsartResponse & {
|
|
44
52
|
response: {
|
|
45
53
|
id: string;
|
|
@@ -57,10 +65,12 @@ type WorkflowProgress = {
|
|
|
57
65
|
};
|
|
58
66
|
type OnPartialResultFn = <R>(result: WorkflowApiResponse<R> | PartialWorkflowResult<R>) => Promise<void> | void;
|
|
59
67
|
type OnProgressFn = (progress: WorkflowProgress) => Promise<void> | void;
|
|
68
|
+
type OnEventFn = (event: WorkflowEvent) => Promise<void> | void;
|
|
60
69
|
declare enum ExecutionMode {
|
|
61
70
|
ASYNC = "ASYNC",
|
|
62
71
|
SYNC = "SYNC",
|
|
63
|
-
STREAM = "STREAM"
|
|
72
|
+
STREAM = "STREAM",
|
|
73
|
+
SOCKET = "SOCKET"
|
|
64
74
|
}
|
|
65
75
|
declare class ExecutionOptions {
|
|
66
76
|
mode?: ExecutionMode;
|
|
@@ -71,7 +81,7 @@ declare class ExecutionOptions {
|
|
|
71
81
|
onPartialResult?: OnPartialResultFn;
|
|
72
82
|
onProgress?: OnProgressFn;
|
|
73
83
|
onAccepted?: (id: string) => Promise<void> | void;
|
|
74
|
-
onEvent?:
|
|
84
|
+
onEvent?: OnEventFn;
|
|
75
85
|
notificationConfig?: INotificationContext;
|
|
76
86
|
headers?: HeadersInit;
|
|
77
87
|
}
|
|
@@ -79,13 +89,24 @@ declare class ApiSettings {
|
|
|
79
89
|
executionMode?: ExecutionMode;
|
|
80
90
|
configId?: string;
|
|
81
91
|
}
|
|
92
|
+
declare enum EventTypes {
|
|
93
|
+
COMPLETED = "task.completed",
|
|
94
|
+
FAILED = "task.failed",
|
|
95
|
+
PARTIAL_RESULT = "task.partial-result",
|
|
96
|
+
METRICS = "task.metrics"
|
|
97
|
+
}
|
|
82
98
|
interface WorkflowEvent {
|
|
83
99
|
type: string;
|
|
84
100
|
id?: string;
|
|
85
101
|
}
|
|
86
102
|
interface WorkflowResponse<R> {
|
|
87
103
|
result: R;
|
|
104
|
+
status: WorkflowStatus;
|
|
88
105
|
usage?: TaskCreditUsage;
|
|
106
|
+
id?: string;
|
|
107
|
+
updated?: string;
|
|
108
|
+
progress?: WorkflowProgress;
|
|
109
|
+
events?: WorkflowEvent[];
|
|
89
110
|
}
|
|
90
111
|
interface INotificationContext {
|
|
91
112
|
projectId?: string;
|
|
@@ -96,8 +117,49 @@ interface INotificationContextAction {
|
|
|
96
117
|
deeplink: string;
|
|
97
118
|
mobileDeeplink: string;
|
|
98
119
|
}
|
|
120
|
+
interface ChannelOpAck {
|
|
121
|
+
accepted: string[];
|
|
122
|
+
rejected: {
|
|
123
|
+
channel: string;
|
|
124
|
+
reason: string;
|
|
125
|
+
}[];
|
|
126
|
+
}
|
|
127
|
+
interface SocketLike {
|
|
128
|
+
on(event: string, handler: (payload: any) => void): unknown;
|
|
129
|
+
off(event: string, handler: (payload: any) => void): unknown;
|
|
130
|
+
emit(event: string, payload?: unknown, ack?: (response: ChannelOpAck) => void): unknown;
|
|
131
|
+
connect(): unknown;
|
|
132
|
+
disconnect(): unknown;
|
|
133
|
+
readonly connected: boolean;
|
|
134
|
+
readonly recovered: boolean;
|
|
135
|
+
readonly active: boolean;
|
|
136
|
+
}
|
|
137
|
+
interface SocketConnectionOptions {
|
|
138
|
+
url?: string;
|
|
139
|
+
getToken: () => string | Promise<string>;
|
|
140
|
+
path?: string;
|
|
141
|
+
transports?: string[];
|
|
142
|
+
}
|
|
143
|
+
interface StreamSocketMessage {
|
|
144
|
+
taskId: string;
|
|
145
|
+
workflow?: string;
|
|
146
|
+
type: string;
|
|
147
|
+
payload: any;
|
|
148
|
+
}
|
|
149
|
+
interface SubscribeOptions {
|
|
150
|
+
name: string;
|
|
151
|
+
taskId?: string;
|
|
152
|
+
signal?: AbortSignal;
|
|
153
|
+
}
|
|
154
|
+
declare const STREAM_EVENT_NAME = "task.stream";
|
|
155
|
+
declare const normalizeWorkflowName: (workflow: string) => string;
|
|
156
|
+
declare const taskChannel: (workflow: string, taskId: string) => string;
|
|
157
|
+
declare const workflowChannel: (workflow: string) => string;
|
|
99
158
|
|
|
100
159
|
type getRemoteSettingsFn = (name: string, tag?: string) => Promise<ApiSettings>;
|
|
160
|
+
type MappedWorkflow = keyof WorkflowTypes;
|
|
161
|
+
type RunParams<N> = N extends MappedWorkflow ? WorkflowTypes[N]['params'] : unknown;
|
|
162
|
+
type RunResult<N, R> = N extends MappedWorkflow ? WorkflowTypes[N]['result'] : R;
|
|
101
163
|
interface ClientOptions {
|
|
102
164
|
baseUrl?: string;
|
|
103
165
|
fetch?: typeof fetch;
|
|
@@ -105,27 +167,205 @@ interface ClientOptions {
|
|
|
105
167
|
identityToken?: string;
|
|
106
168
|
getRemoteSettings?: getRemoteSettingsFn;
|
|
107
169
|
headers?: HeadersInit;
|
|
170
|
+
socket?: SocketLike;
|
|
171
|
+
socketConnection?: SocketConnectionOptions;
|
|
108
172
|
}
|
|
109
173
|
declare class WorkflowsClient {
|
|
110
174
|
private readonly workflowsApiBaseUrl;
|
|
111
175
|
private readonly defaultHeaders;
|
|
112
|
-
private readonly
|
|
176
|
+
private readonly clientOptions;
|
|
177
|
+
private readonly sockets;
|
|
113
178
|
private readonly terminalStatuses;
|
|
114
179
|
constructor(options: ClientOptions);
|
|
115
|
-
|
|
116
|
-
|
|
180
|
+
/**
|
|
181
|
+
* Runs a workflow end-to-end and resolves with its result.
|
|
182
|
+
*
|
|
183
|
+
* A workflow that has an entry in `WorkflowTypes` (from `@picsart/workflows-types`) is
|
|
184
|
+
* type-checked against it: `params` must match the workflow's input and the result comes back
|
|
185
|
+
* typed, with no type argument to pass. Every other workflow is left unconstrained — declare
|
|
186
|
+
* the result yourself with `run<MyResult>(name, params)`.
|
|
187
|
+
*
|
|
188
|
+
* The execution mode is taken from remote settings when available, otherwise from
|
|
189
|
+
* `executionOptions.mode`, defaulting to async (submit + polling). Supported modes:
|
|
190
|
+
* sync (single HTTP call), stream (SSE, requires `onEvent`), socket (result pushed
|
|
191
|
+
* over the socket), and async (submit + polling).
|
|
192
|
+
*
|
|
193
|
+
* @typeParam R - Shape of the result, for a workflow that has no `WorkflowTypes` entry.
|
|
194
|
+
* Passing it explicitly also opts a mapped workflow out of its types.
|
|
195
|
+
* @param name - Workflow name.
|
|
196
|
+
* @param params - Workflow input, typed per the workflow definition when there is one.
|
|
197
|
+
* @param executionOptions - Mode, callbacks (`onAccepted`, `onProgress`, `onPartialResult`,
|
|
198
|
+
* `onEvent`), polling tuning, headers, and abort signal.
|
|
199
|
+
* @returns The workflow result and usage info.
|
|
200
|
+
* @throws {WorkflowsError} On a failed request (`httpStatusCode` carries the HTTP status),
|
|
201
|
+
* invalid arguments, or an unexpected failure.
|
|
202
|
+
*/
|
|
203
|
+
run<R = unknown, N extends string = string>(name: N, params: RunParams<N>, executionOptions?: ExecutionOptions): Promise<WorkflowResponse<RunResult<N, R>>>;
|
|
204
|
+
/**
|
|
205
|
+
* Submits a task WITHOUT waiting for its result — the standalone counterpart of {@link run}.
|
|
206
|
+
* Consume the result later with {@link runPolling} or {@link subscribe} (`{ name, taskId }`).
|
|
207
|
+
*
|
|
208
|
+
* Only the submission-related execution options apply here (`headers`, `notificationConfig`,
|
|
209
|
+
* `remoteSettingName`); result-consumption options (mode, callbacks, polling) belong to the consumer.
|
|
210
|
+
*
|
|
211
|
+
* @param name - Workflow name.
|
|
212
|
+
* @param params - Workflow input parameters.
|
|
213
|
+
* @param executionOptions - Submission-related options only.
|
|
214
|
+
* @returns The taskId of the submitted task.
|
|
215
|
+
* @throws {WorkflowsError} On a failed request (`httpStatusCode` carries the HTTP status)
|
|
216
|
+
* or an unexpected failure.
|
|
217
|
+
*/
|
|
218
|
+
submit(name: string, params: unknown, executionOptions?: ExecutionOptions): Promise<string>;
|
|
219
|
+
/**
|
|
220
|
+
* Fetches the options a workflow offers for the given input — what the adapter resolves for THIS
|
|
221
|
+
* caller (subscription tier, country, the `x-config-id` CMS card), which is why it is read at call
|
|
222
|
+
* time rather than described by the workflow's types.
|
|
223
|
+
*
|
|
224
|
+
* @param name - Workflow name, including the version when the workflow has one (`pipelineName/v1`).
|
|
225
|
+
* @param params - Workflow input to resolve the options for; defaults to `{}` for the common case
|
|
226
|
+
* of asking before anything is chosen.
|
|
227
|
+
* @param requestOptions - `remoteSettingName` to resolve the `x-config-id` under a name other
|
|
228
|
+
* than the workflow's own.
|
|
229
|
+
* @returns The options payload — the envelope's `response`, unwrapped.
|
|
230
|
+
* @throws {WorkflowsError} On a failed request; `httpStatusCode` carries the HTTP status.
|
|
231
|
+
*/
|
|
232
|
+
options(name: string, params?: unknown, requestOptions?: {
|
|
233
|
+
remoteSettingName?: string;
|
|
234
|
+
}): Promise<WorkflowOptions>;
|
|
117
235
|
private postTask;
|
|
236
|
+
/**
|
|
237
|
+
* Polls an already-submitted task until it reaches a terminal status (COMPLETED/FAILED)
|
|
238
|
+
* and resolves with its result. Progress and partial-result callbacks from
|
|
239
|
+
* `executionOptions` are invoked on each update.
|
|
240
|
+
*
|
|
241
|
+
* A poll that never reaches the server (dropped wifi, DNS failure, a reset connection) does not
|
|
242
|
+
* end the run — the task keeps going server-side, so polling backs off and retries, giving up
|
|
243
|
+
* only once the drops outlast the retry budget. Anything the server did answer, and any abort,
|
|
244
|
+
* still fails immediately.
|
|
245
|
+
*
|
|
246
|
+
* @typeParam R - Shape of the workflow result.
|
|
247
|
+
* @param taskName - Workflow name.
|
|
248
|
+
* @param taskId - Task id returned by {@link submit} (or `onAccepted`).
|
|
249
|
+
* @param executionOptions - `pollingInterval` (default 300ms), `retriesCount` (default 1000),
|
|
250
|
+
* callbacks and abort signal.
|
|
251
|
+
* @returns The workflow result and usage info.
|
|
252
|
+
* @throws {WorkflowsError} With `httpStatusCode` 408 when the retry budget is exhausted
|
|
253
|
+
* before the task completes, or the connection error when the connection never came back.
|
|
254
|
+
*/
|
|
118
255
|
runPolling<R>(taskName: string, taskId: string, executionOptions?: ExecutionOptions): Promise<WorkflowResponse<R>>;
|
|
256
|
+
private connectionError;
|
|
257
|
+
private isTerminal;
|
|
258
|
+
/**
|
|
259
|
+
* Whether a failed poll never got an answer from the server — the connection dropped, DNS failed,
|
|
260
|
+
* the request was reset. Classified by what the failure is NOT, so it holds in a browser
|
|
261
|
+
* (`TypeError: Failed to fetch`) and in Node (`TypeError: fetch failed`) alike: anything the
|
|
262
|
+
* server answered carries an `httpStatusCode`, and an abort is the caller's own doing.
|
|
263
|
+
*/
|
|
264
|
+
private isConnectionError;
|
|
265
|
+
private pollingDelay;
|
|
266
|
+
/**
|
|
267
|
+
* Fetches the CURRENT state of an already-submitted task with a single request — no polling, no
|
|
268
|
+
* waiting. Returns the task as it stands, so read `status` (and `progress`) to know what you got:
|
|
269
|
+
* `result` may still be empty or partial while the task is not COMPLETED. Use {@link runPolling}
|
|
270
|
+
* or {@link subscribe} to wait for a terminal status instead.
|
|
271
|
+
*
|
|
272
|
+
* @typeParam R - Shape of the workflow result.
|
|
273
|
+
* @param taskName - Workflow name.
|
|
274
|
+
* @param taskId - Task id returned by {@link submit} (or `onAccepted`).
|
|
275
|
+
* @returns The task record as it stands at the moment of the call.
|
|
276
|
+
* @throws {WorkflowsError} On a failed request (`httpStatusCode` carries the HTTP status)
|
|
277
|
+
* or an unexpected failure.
|
|
278
|
+
*/
|
|
279
|
+
result<R>(taskName: string, taskId: string): Promise<WorkflowResponse<R>>;
|
|
280
|
+
/**
|
|
281
|
+
* Watches already-submitted work LIVE over the socket (no re-submit), as an async iterable
|
|
282
|
+
* of the raw `StreamSocketMessage` the gateway pushes — iterate with `for await` and switch
|
|
283
|
+
* on `msg.type`. With a `taskId` it watches that task (ending after its COMPLETED/FAILED);
|
|
284
|
+
* without it, it watches EVERY task of the workflow until stopped. A lost session throws out
|
|
285
|
+
* of the loop; `break` (or an AbortSignal in options) stops watching.
|
|
286
|
+
*
|
|
287
|
+
* @param options - Subscription target: `name` (required), optional `taskId` and abort signal.
|
|
288
|
+
* @returns Async iterable of socket messages for the subscribed workflow/task.
|
|
289
|
+
* @throws {WorkflowsError} If `options.name` is missing.
|
|
290
|
+
*/
|
|
291
|
+
subscribe(options: SubscribeOptions): AsyncIterableIterator<StreamSocketMessage>;
|
|
292
|
+
/**
|
|
293
|
+
* Closes the socket the client created from `socketConnection`. No-op for an injected
|
|
294
|
+
* `socket` (the caller owns that one). Safe to call more than once.
|
|
295
|
+
*/
|
|
296
|
+
disconnect(): Promise<void>;
|
|
297
|
+
/**
|
|
298
|
+
* Marks a task's notification as seen so it is no longer surfaced to the user.
|
|
299
|
+
* Called automatically after socket-mode runs; call it manually when consuming
|
|
300
|
+
* results yourself (e.g. after {@link submit} + {@link subscribe}).
|
|
301
|
+
*
|
|
302
|
+
* @param taskId - Task id whose notification should be dismissed.
|
|
303
|
+
* @param options - Optional extra request headers.
|
|
304
|
+
* @throws {WorkflowsError} On a failed request; `httpStatusCode` carries the HTTP status.
|
|
305
|
+
*/
|
|
306
|
+
disableNotification(taskId: string, options?: {
|
|
307
|
+
headers?: HeadersInit;
|
|
308
|
+
}): Promise<void>;
|
|
119
309
|
private executeTaskSync;
|
|
120
310
|
private getResult;
|
|
121
311
|
private executeTaskStream;
|
|
312
|
+
/**
|
|
313
|
+
* Fetches the execution history of a workflow, paginated.
|
|
314
|
+
*
|
|
315
|
+
* @typeParam R - Shape of each execution's result in the history entries.
|
|
316
|
+
* @param taskName - Workflow name to fetch history for.
|
|
317
|
+
* @param offset - Pagination offset (default 0).
|
|
318
|
+
* @param limit - Page size (default 10).
|
|
319
|
+
* @param isGrouped - When true, fetches the grouped history endpoint.
|
|
320
|
+
* @returns The history page for the workflow.
|
|
321
|
+
* @throws {WorkflowsError} On a failed request (`httpStatusCode` carries the HTTP status)
|
|
322
|
+
* or an unexpected failure.
|
|
323
|
+
*/
|
|
122
324
|
executionsHistory<R>(taskName: string, offset?: number, limit?: number, isGrouped?: boolean): Promise<HistoryResponse<R>>;
|
|
123
325
|
private toSuccessResponse;
|
|
124
326
|
private throwIfError;
|
|
125
327
|
private getApiSettings;
|
|
126
328
|
private wrapError;
|
|
329
|
+
private requestHeaders;
|
|
127
330
|
private buildRequestHeaders;
|
|
128
331
|
private _fetch;
|
|
129
332
|
}
|
|
130
333
|
|
|
131
|
-
|
|
334
|
+
/**
|
|
335
|
+
* The single error every failure in this client is reported as: a failed HTTP call, a failed
|
|
336
|
+
* workflow, a lost socket, a bad argument or an unexpected local throw.
|
|
337
|
+
*
|
|
338
|
+
* Three fields, always: `message` (the raw text the API returned), `reason` (machine-readable
|
|
339
|
+
* code) and `httpStatusCode` (absent for failures that never had one). A payload that doesn't
|
|
340
|
+
* follow the backend's error format is NOT carried along — each missing field falls back to the
|
|
341
|
+
* caller's value instead, so callers only ever depend on the three fields above.
|
|
342
|
+
*/
|
|
343
|
+
interface WorkflowsErrorInit {
|
|
344
|
+
reason: string;
|
|
345
|
+
message: string;
|
|
346
|
+
httpStatusCode?: number;
|
|
347
|
+
}
|
|
348
|
+
declare class WorkflowsError extends Error {
|
|
349
|
+
/** Machine-readable failure code, e.g. `invalid_request`, `client_timeout`, `unknown_error`. */
|
|
350
|
+
readonly reason: string;
|
|
351
|
+
/** HTTP status when the failure came with one; undefined for purely local failures. */
|
|
352
|
+
readonly httpStatusCode?: number;
|
|
353
|
+
constructor(init: WorkflowsErrorInit);
|
|
354
|
+
/**
|
|
355
|
+
* Builds an error from an already-parsed error payload — a `FailedResult` off a stream/socket
|
|
356
|
+
* event, or any body with `reason` / `message` / `statusCode`. Each field falls back to
|
|
357
|
+
* `fallback` individually, so a payload that carries only a message still keeps the caller's
|
|
358
|
+
* reason and status.
|
|
359
|
+
*/
|
|
360
|
+
static fromBody(body: unknown, fallback: WorkflowsErrorInit): WorkflowsError;
|
|
361
|
+
/**
|
|
362
|
+
* Builds an error from a non-ok `Response`. The status always comes from the response itself;
|
|
363
|
+
* `reason` and `message` come from the JSON body when it has them, otherwise from `fallback`
|
|
364
|
+
* (a body that isn't JSON at all is reported as such rather than throwing a parse error).
|
|
365
|
+
*/
|
|
366
|
+
static fromResponse(response: Response, fallback?: Partial<WorkflowsErrorInit>): Promise<WorkflowsError>;
|
|
367
|
+
/** Wraps an unexpected local throw (anything that isn't already a WorkflowsError). */
|
|
368
|
+
static fromUnknown(error: unknown): WorkflowsError;
|
|
369
|
+
}
|
|
370
|
+
|
|
371
|
+
export { type ChannelOpAck, EventTypes, ExecutionMode, ExecutionOptions, STREAM_EVENT_NAME, type SocketConnectionOptions, type SocketLike, type StreamSocketMessage, type SubscribeOptions, type WorkflowEvent, type WorkflowOptions, type WorkflowProgress, type WorkflowResponse, WorkflowStatus, WorkflowsClient, WorkflowsError, type WorkflowsErrorInit, normalizeWorkflowName, taskChannel, workflowChannel };
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
var __create = Object.create;
|
|
2
|
+
var __defProp = Object.defineProperty;
|
|
3
|
+
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
4
|
+
var __getOwnPropNames = Object.getOwnPropertyNames;
|
|
5
|
+
var __getProtoOf = Object.getPrototypeOf;
|
|
6
|
+
var __hasOwnProp = Object.prototype.hasOwnProperty;
|
|
7
|
+
var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
|
|
8
|
+
get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
|
|
9
|
+
}) : x)(function(x) {
|
|
10
|
+
if (typeof require !== "undefined") return require.apply(this, arguments);
|
|
11
|
+
throw Error('Dynamic require of "' + x + '" is not supported');
|
|
12
|
+
});
|
|
13
|
+
var __commonJS = (cb, mod) => function __require2() {
|
|
14
|
+
return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
|
|
15
|
+
};
|
|
16
|
+
var __export = (target, all) => {
|
|
17
|
+
for (var name in all)
|
|
18
|
+
__defProp(target, name, { get: all[name], enumerable: true });
|
|
19
|
+
};
|
|
20
|
+
var __copyProps = (to, from, except, desc) => {
|
|
21
|
+
if (from && typeof from === "object" || typeof from === "function") {
|
|
22
|
+
for (let key of __getOwnPropNames(from))
|
|
23
|
+
if (!__hasOwnProp.call(to, key) && key !== except)
|
|
24
|
+
__defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
|
|
25
|
+
}
|
|
26
|
+
return to;
|
|
27
|
+
};
|
|
28
|
+
var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
|
|
29
|
+
// If the importer is in node compatibility mode or this is not an ESM
|
|
30
|
+
// file that has been converted to a CommonJS file using a Babel-
|
|
31
|
+
// compatible transform (i.e. "__esModule" has not been set), then set
|
|
32
|
+
// "default" to the CommonJS "module.exports" for node compatibility.
|
|
33
|
+
isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
|
|
34
|
+
mod
|
|
35
|
+
));
|
|
36
|
+
|
|
37
|
+
export { __commonJS, __export, __require, __toESM };
|