@lovable.dev/workflows-sdk 0.0.0-dev.2 → 0.0.0-dev.21

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/dist/index.d.ts CHANGED
@@ -1,49 +1,162 @@
1
- import { AnyWorkflowDefinition, AnyWorkflowDefinition as AnyWorkflowDefinition$1, Ctx, StepContext, StepOptions, WorkflowDefinition, WorkflowInput, WorkflowInput as WorkflowInput$1, WorkflowOutput, WorkflowState, createMiddleware, createWorkflow } from "@tanstack/workflow-core";
2
- //#region src/schedule.d.ts
1
+ import { AnyWorkflowDefinition, AnyWorkflowDefinition as AnyWorkflowDefinition$1, Ctx, RunStore, StepContext, StepOptions, WorkflowDefinition, WorkflowEvent, WorkflowInput, WorkflowInput as WorkflowInput$1, WorkflowMetadata, WorkflowOutput, WorkflowState, createMiddleware, createWorkflow } from "@tanstack/workflow-core";
2
+ import "typescript";
3
+ //#region src/core/cadence.d.ts
4
+ type Weekday = "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";
5
+ type Cadence = {
6
+ readonly kind: "hourly";
7
+ } | {
8
+ readonly kind: "daily";
9
+ readonly at: readonly number[] | null;
10
+ readonly days: readonly Weekday[] | null;
11
+ };
12
+ declare function hourly(options?: never): Cadence;
13
+ declare function daily(options?: {
14
+ at?: number | readonly number[];
15
+ days?: readonly string[];
16
+ }): Cadence;
17
+ declare function weekly(options: {
18
+ on: string;
19
+ at?: number | readonly number[];
20
+ }): Cadence;
21
+ //#endregion
22
+ //#region src/core/schedule.d.ts
23
+ type OverlapPolicy = "skip" | "allow" | "buffer-one";
3
24
  interface ScheduleDefinition<TWorkflow extends AnyWorkflowDefinition$1 = AnyWorkflowDefinition$1> {
4
25
  readonly id: string;
5
26
  readonly workflow: TWorkflow;
6
- readonly cron: string;
7
- readonly timeZone?: string;
27
+ readonly cadence: Cadence;
28
+ readonly timeZone: string;
29
+ readonly overlapPolicy?: OverlapPolicy;
30
+ readonly enabled?: boolean;
8
31
  readonly input: WorkflowInput$1<NoInfer<TWorkflow>>;
9
32
  }
10
- declare function defineSchedule<TWorkflow extends AnyWorkflowDefinition$1>(schedule: ScheduleDefinition<TWorkflow>): ScheduleDefinition<TWorkflow>;
33
+ interface ResolvedSchedule<TWorkflow extends AnyWorkflowDefinition$1 = AnyWorkflowDefinition$1> extends ScheduleDefinition<TWorkflow> {
34
+ readonly type: "schedule";
35
+ readonly overlapPolicy: OverlapPolicy;
36
+ readonly enabled: boolean;
37
+ }
38
+ declare function defineSchedule<TWorkflow extends AnyWorkflowDefinition$1>(schedule: ScheduleDefinition<TWorkflow>): ResolvedSchedule<TWorkflow>;
11
39
  //#endregion
12
- //#region src/register.d.ts
40
+ //#region src/core/trigger.d.ts
41
+ type TriggerDefinition = ScheduleDefinition;
42
+ type ResolvedTrigger = ResolvedSchedule;
43
+ //#endregion
44
+ //#region src/core/workflow.d.ts
13
45
  interface WorkflowsDefinition<TWorkflow extends AnyWorkflowDefinition$1 = AnyWorkflowDefinition$1> {
14
46
  readonly workflows: readonly TWorkflow[];
15
- readonly schedules: readonly ScheduleDefinition[];
47
+ readonly triggers: readonly ResolvedTrigger[];
16
48
  }
17
- declare function registerWorkflows<const TWorkflows extends readonly AnyWorkflowDefinition$1[]>({ workflows, schedules }: {
49
+ declare function registerWorkflows<const TWorkflows extends readonly AnyWorkflowDefinition$1[]>(definition: {
18
50
  workflows: TWorkflows;
19
- schedules?: readonly ScheduleDefinition[];
51
+ triggers?: readonly TriggerDefinition[];
20
52
  }): WorkflowsDefinition<TWorkflows[number]>;
21
53
  //#endregion
22
- //#region src/graph.d.ts
54
+ //#region src/core/step-metadata.d.ts
55
+ interface WorkflowStepGroup {
56
+ id: string;
57
+ label: string;
58
+ }
59
+ interface WorkflowBranchMetadata {
60
+ id: string;
61
+ description: string;
62
+ }
63
+ type WorkflowOperationMetadata = Record<string, unknown> & {
64
+ description: string;
65
+ branches?: WorkflowBranchMetadata[];
66
+ };
67
+ type WorkflowStepMetadata = WorkflowOperationMetadata & {
68
+ group?: WorkflowStepGroup;
69
+ };
70
+ //#endregion
71
+ //#region src/manifests/graph.d.ts
72
+ type WorkflowGraphNodeDetails = {
73
+ kind: "step";
74
+ stepId: string;
75
+ description: string;
76
+ } | {
77
+ kind: "parallel";
78
+ groupId: string;
79
+ cardinality: "dynamic";
80
+ operation: {
81
+ kind: "step";
82
+ stepIdTemplate: string;
83
+ description: string;
84
+ };
85
+ } | {
86
+ kind: "approve";
87
+ stepId: string;
88
+ description: string;
89
+ config: {
90
+ title: string;
91
+ description: string;
92
+ };
93
+ } | {
94
+ kind: "wait-for-event";
95
+ stepId: string;
96
+ description: string;
97
+ config: {
98
+ event: string;
99
+ deadline?: number;
100
+ };
101
+ } | {
102
+ kind: "sleep";
103
+ stepId: string;
104
+ description: string;
105
+ config: {
106
+ ms: number;
107
+ };
108
+ } | {
109
+ kind: "sleep-until";
110
+ stepId: string;
111
+ description: string;
112
+ config: {
113
+ timestamp: number;
114
+ };
115
+ } | {
116
+ kind: "now";
117
+ stepId: string;
118
+ description: string;
119
+ } | {
120
+ kind: "uuid";
121
+ stepId: string;
122
+ description: string;
123
+ } | {
124
+ kind: "branch";
125
+ branchId: string;
126
+ condition: string;
127
+ description: string;
128
+ } | {
129
+ kind: "unknown";
130
+ };
131
+ type WorkflowGraphNode = {
132
+ id: string;
133
+ label: string;
134
+ } & WorkflowGraphNodeDetails;
135
+ type WorkflowGraphEdge = {
136
+ source: string;
137
+ target: string;
138
+ kind: "order";
139
+ } | {
140
+ source: string;
141
+ target: string;
142
+ kind: "branch";
143
+ outcome: boolean;
144
+ };
23
145
  interface WorkflowGraph {
24
146
  source: "inferred";
25
147
  scope: "handler";
26
148
  complete: boolean;
27
- nodes: {
28
- id: string;
29
- kind: "step" | "unknown";
30
- label: string;
31
- stepId?: string;
32
- }[];
33
- edges: {
34
- source: string;
35
- target: string;
36
- kind: "order";
37
- }[];
149
+ nodes: WorkflowGraphNode[];
150
+ edges: WorkflowGraphEdge[];
38
151
  diagnostics: string[];
39
152
  }
40
153
  //#endregion
41
- //#region src/json.d.ts
154
+ //#region src/manifests/json.d.ts
42
155
  type JsonValue = null | boolean | number | string | JsonValue[] | {
43
156
  [key: string]: JsonValue;
44
157
  };
45
158
  //#endregion
46
- //#region src/manifest.d.ts
159
+ //#region src/manifests/generate.d.ts
47
160
  interface WorkflowManifest {
48
161
  version: 1;
49
162
  workflow: {
@@ -54,14 +167,155 @@ interface WorkflowManifest {
54
167
  outputSchema?: JsonValue;
55
168
  stateSchema?: JsonValue;
56
169
  };
57
- schedules: {
170
+ triggers: {
171
+ type: "schedule";
58
172
  id: string;
59
- cron: string;
173
+ cadence: Cadence;
60
174
  timeZone: string;
175
+ enabled: boolean;
176
+ overlapPolicy: OverlapPolicy;
61
177
  input: JsonValue;
62
178
  }[];
63
179
  graph: WorkflowGraph;
64
180
  }
65
181
  declare function generateManifests(definition: WorkflowsDefinition): Promise<WorkflowManifest[]>;
66
182
  //#endregion
67
- export { type AnyWorkflowDefinition, type Ctx, type ScheduleDefinition, type StepContext, type StepOptions, type WorkflowDefinition, type WorkflowGraph, type WorkflowInput, type WorkflowManifest, type WorkflowOutput, type WorkflowState, type WorkflowsDefinition, createMiddleware, createWorkflow, defineSchedule, generateManifests, registerWorkflows };
183
+ //#region src/stacks/tanstack/handlers.d.ts
184
+ /** The shape `registerWorkflows()` returns; only the list is needed to dispatch. */
185
+ interface WorkflowCollection {
186
+ readonly workflows: readonly AnyWorkflowDefinition$1[];
187
+ }
188
+ interface TanStackWorkflowHandlerOptions {
189
+ /** @default a process-local `inMemoryRunStore()`, lost on restart */
190
+ runStore?: RunStore;
191
+ /**
192
+ * Route parameter carrying the workflow ID.
193
+ * @default "workflowId"
194
+ */
195
+ workflowIdParam?: string;
196
+ }
197
+ interface TanStackRouteCtx {
198
+ request: Request;
199
+ params?: Record<string, string | undefined>;
200
+ }
201
+ type TanStackWorkflowHandler = (ctx: TanStackRouteCtx) => Promise<Response>;
202
+ /** Build a TanStack Start `POST` handler serving every workflow in the collection. */
203
+ declare function createTanStackWorkflowHandler(collection: WorkflowCollection, options?: TanStackWorkflowHandlerOptions): TanStackWorkflowHandler;
204
+ //#endregion
205
+ //#region src/runtime/types.d.ts
206
+ /** Durable operations a replay can answer from the memo. */
207
+ type StepKind = "step" | "sleep" | "waitForEvent" | "approve" | "now" | "uuid";
208
+ /**
209
+ * One settled durable operation. The memo is the whole run state: the caller
210
+ * carries it between calls, so no run store is involved.
211
+ */
212
+ interface MemoEntry {
213
+ /** Call order within the pass that recorded it. Reporting only: racing
214
+ * branches can order differently on a later pass, so it is not the key. */
215
+ seq: number;
216
+ stepId: string;
217
+ /** Which call of this `stepId` in the run, from 0. */
218
+ occurrence: number;
219
+ /** Key of the step whose body recorded this, if any; a memoized parent hides it. */
220
+ parent?: string;
221
+ kind: StepKind;
222
+ meta?: WorkflowMetadata;
223
+ status: "completed" | "failed";
224
+ result?: unknown;
225
+ error?: string;
226
+ }
227
+ interface StepIntentBase {
228
+ seq: number;
229
+ stepId: string;
230
+ occurrence: number;
231
+ /** Kind-specific detail: sleep `ms`, `waitForEvent` name, approval title. */
232
+ config?: Record<string, unknown>;
233
+ meta?: WorkflowMetadata;
234
+ }
235
+ /** A durable operation the replay reached but could not answer. */
236
+ type StepIntent = StepIntentBase & ({
237
+ kind: "step";
238
+ } | {
239
+ kind: Exclude<StepKind, "step">;
240
+ });
241
+ interface StepResult<K extends StepKind = StepKind> {
242
+ seq: number;
243
+ stepId: string;
244
+ occurrence: number;
245
+ kind: K;
246
+ meta?: WorkflowMetadata;
247
+ status: "completed" | "failed";
248
+ result?: unknown;
249
+ error?: string;
250
+ }
251
+ type ReplayStatus = "completed" | "failed" | "pending";
252
+ interface ReplayOutcome {
253
+ status: ReplayStatus;
254
+ /** The memo the next call should send back, including entries this pass settled. */
255
+ memo: MemoEntry[];
256
+ /** Operations that still need an answer; empty unless `status` is `pending`. */
257
+ steps: StepIntent[];
258
+ /** Operations this pass executed, in execution order. */
259
+ results: StepResult[];
260
+ /** `ctx.emit` payloads; diagnostic only, never part of replay. */
261
+ emitted: {
262
+ name: string;
263
+ value: Record<string, unknown>;
264
+ }[];
265
+ output?: unknown;
266
+ error?: string;
267
+ }
268
+ interface StepReference {
269
+ kind: "step";
270
+ stepId: string;
271
+ occurrence: number;
272
+ }
273
+ //#endregion
274
+ //#region src/stacks/tanstack/steps.d.ts
275
+ interface StepsHandlerOptions {
276
+ /** Route parameter carrying the workflow ID. @default "workflowId" */
277
+ workflowIdParam?: string;
278
+ }
279
+ interface RouteCtx {
280
+ request: Request;
281
+ params?: Record<string, string | undefined>;
282
+ }
283
+ type StepsHandler = (ctx: RouteCtx) => Promise<Response>;
284
+ interface StepsRequestBase {
285
+ input?: unknown;
286
+ memo?: MemoEntry[];
287
+ runId?: string;
288
+ inputHash?: string;
289
+ }
290
+ type StepsRequest = StepsRequestBase & ({
291
+ action?: "advance";
292
+ step?: never;
293
+ } | {
294
+ action: "execute";
295
+ step: StepReference;
296
+ });
297
+ type StepsDisposition = "advanced" | "fork" | "waiting" | "completed" | "failed";
298
+ interface StepsResponse {
299
+ runId: string;
300
+ inputHash: string;
301
+ disposition: StepsDisposition;
302
+ memoDelta: MemoEntry[];
303
+ next: StepIntent[];
304
+ executed?: StepResult<"step">;
305
+ emitted?: {
306
+ name: string;
307
+ value: Record<string, unknown>;
308
+ }[];
309
+ output?: unknown;
310
+ error?: string;
311
+ }
312
+ declare function createStepsHandler(collection: WorkflowCollection, options?: StepsHandlerOptions): StepsHandler;
313
+ //#endregion
314
+ //#region src/stacks/tanstack/sse.d.ts
315
+ /**
316
+ * Encode a workflow event stream as `text/event-stream`. Each event keeps its
317
+ * engine `type` as the SSE event name and its whole JSON as the data line.
318
+ */
319
+ declare function toServerSentEventsResponse(events: AsyncIterable<WorkflowEvent>): Response;
320
+ //#endregion
321
+ export { type AnyWorkflowDefinition, type Cadence, type Ctx, type MemoEntry, type OverlapPolicy, type ReplayOutcome, type ResolvedSchedule, type ResolvedTrigger, type ScheduleDefinition, type StepContext, type StepIntent, type StepKind, type StepOptions, type StepReference, type StepResult, type StepsDisposition, type StepsHandler, type StepsHandlerOptions, type StepsRequest, type StepsResponse, type TanStackWorkflowHandler, type TanStackWorkflowHandlerOptions, type TriggerDefinition, type Weekday, type WorkflowBranchMetadata, type WorkflowCollection, type WorkflowDefinition, type WorkflowGraph, type WorkflowGraphEdge, type WorkflowGraphNode, type WorkflowGraphNodeDetails, type WorkflowInput, type WorkflowManifest, type WorkflowOperationMetadata, type WorkflowOutput, type WorkflowState, type WorkflowStepGroup, type WorkflowStepMetadata, type WorkflowsDefinition, createMiddleware, createStepsHandler, createTanStackWorkflowHandler, createWorkflow, daily, defineSchedule, generateManifests, hourly, registerWorkflows, toServerSentEventsResponse, weekly };