@lovable.dev/workflows-sdk 0.0.0-dev.52 → 0.0.0-dev.53

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 CHANGED
@@ -65,6 +65,7 @@ Every durable operation needs a static, user-facing description:
65
65
  | --- | --- |
66
66
  | `ctx.step` | Third argument: `meta.description` |
67
67
  | `ctx.llm` | Second argument: `meta.description` |
68
+ | `ctx.connector` | Third argument: `meta.description` |
68
69
  | `ctx.sleep`, `ctx.sleepUntil` | Second argument: `meta.description` |
69
70
  | `ctx.waitForEvent` | Second argument: `meta.description` |
70
71
  | `ctx.now`, `ctx.uuid` | First argument: `meta.description` |
@@ -129,6 +130,63 @@ Keep durable control flow in the workflow handler. Do not pass, alias,
129
130
  destructure, or return `ctx`, and do not detach methods such as `ctx.step`.
130
131
  Pass extracted data such as `ctx.input.customerId` to helpers instead.
131
132
 
133
+ ### Connector callbacks
134
+
135
+ SDK `0.0.0-dev.52` is the first version that executes
136
+ `ctx.connector(stepId, callback, options)` through the generated `/steps` route.
137
+ Use it for gateway-backed App connectors: a connection linked to the app,
138
+ shared across workflow runs. App User Connectors, which act for individual app
139
+ users, are outside this authoring flow.
140
+
141
+ ```ts
142
+ const messages = await ctx.connector("read-messages", ({ signal }) => readMessages(signal), {
143
+ connectorId: "slack", connectionId: "std_REPLACE_WITH_LINKED_CONNECTION_ID",
144
+ meta: { description: "Read recent channel messages" },
145
+ });
146
+ ```
147
+
148
+ Keep `connectorId` and `connectionId` as nonempty string literals in the inline
149
+ options object. They identify the declared step in the manifest and run history;
150
+ credentials enforce access. They cannot vary by workflow input or loop item.
151
+ Use a new workflow version when changing the connection; replay rejects saved
152
+ results or failures whose connector identity differs.
153
+
154
+ The callback receives the normal step context, including `signal`. It owns
155
+ server-side credential access, URL, method, headers, encoding, `fetch`, and
156
+ provider errors. Check both HTTP success and the provider's success fields
157
+ before returning. Forward `signal` to I/O. Return compact JSON-serializable
158
+ data, including plain strings; there is no response envelope. A callback that
159
+ returns `undefined` records and returns `null`. Return parsed data or text,
160
+ never a `Response` or credentials.
161
+
162
+ Select and link an App connection with Lovable's existing connector tools.
163
+ `standard_connectors--get_connection_secrets` takes the connection's `std_...`
164
+ ID and returns exact secret names and generated-app routing, never secret
165
+ values. Follow that routing and run its read-only App credential check before
166
+ using the workflow. Secret names depend on the connection; do not derive them
167
+ from `connectorId`. Keep gateway credentials separate from
168
+ `LOVABLE_WORKFLOWS_KEY`, which authenticates the workflow endpoint.
169
+
170
+ Connector retries inherit `defaultStepRetry`. An inline `retry` replaces that
171
+ default and requires `maxAttempts`; use literal `backoff: "fixed"` or
172
+ `"exponential"` and optional `baseMs`. The engine records custom-policy flags
173
+ but does not invoke `shouldRetry` or backoff callbacks; custom backoff uses
174
+ exponential delays. `timeout` is a positive number of
175
+ milliseconds per attempt. Let the workflow engine retry: disable additional
176
+ client retries and avoid retry loops inside the callback. An external write
177
+ can repeat if its result is lost before persistence; use a provider idempotency
178
+ key derived from stable run input when the provider supports one.
179
+
180
+ Discovery, unselected branches, and completed-step replay never invoke the
181
+ callback. Saved final failures throw into the handler's `try/catch`. The
182
+ standalone `createTanStackWorkflowHandler` does not support connector callbacks.
183
+ See the [Slack digest example](examples/src/lib/workflows/slack-digest/index.ts)
184
+ for a connector read followed by an LLM summary and a saved code-step result.
185
+ The example uses hosted-app gateway authentication. Replace its marked
186
+ connection ID and secret name with the tool output, adapt routing/authentication
187
+ to that output, and select a model through the discovery procedure above before
188
+ running it.
189
+
132
190
  ### Repeated steps
133
191
 
134
192
  A step inside a loop or callback needs `meta.group` with a stable ID and
@@ -142,7 +200,9 @@ ctx.step(`process-${item.id}`, () => processItem(item), {
142
200
 
143
201
  For dynamic sequential work, await one step directly as the only statement in
144
202
  a `for...of` loop. For dynamic parallel work, use a mapped `Promise.all()`.
145
- Both forms support `ctx.step` and `ctx.llm`; see [order summaries](examples/src/lib/workflows/order-summaries/index.ts).
203
+ Both forms support `ctx.step`, `ctx.llm`, and `ctx.connector`; see [order summaries](examples/src/lib/workflows/order-summaries/index.ts).
204
+ Repeated connector steps keep the same literal connector and connection IDs
205
+ while each item gets a unique step ID.
146
206
  Use a different group ID for each repeated callsite, and derive item IDs from
147
207
  workflow input or saved step results so replay reaches the same operations.
148
208
  Fixed `Promise.all([stepA, stepB])` branches and ordinary sequential steps do
@@ -1,4 +1,4 @@
1
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-RIBcr2Xd.js";
1
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-CM_9qQRY.js";
2
2
  //#region src/manifests/branch-metadata.ts
3
3
  const optionsArgument = {
4
4
  step: 2,
@@ -1,4 +1,4 @@
1
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-RIBcr2Xd.js";
1
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-CM_9qQRY.js";
2
2
  //#region src/manifests/context-escapes.ts
3
3
  const durableMethods = /* @__PURE__ */ new Set([
4
4
  "step",
@@ -1,4 +1,4 @@
1
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-RIBcr2Xd.js";
1
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-CM_9qQRY.js";
2
2
  //#region src/manifests/duplicate-ids.ts
3
3
  /** Where an explicit `{ id }` would sit for each operation. */
4
4
  const optionsArgument = {
@@ -6626,7 +6626,7 @@ function listValueFromJson(listValue, json) {
6626
6626
  }
6627
6627
  //#endregion
6628
6628
  //#region package.json
6629
- var version = "0.0.0-dev.52";
6629
+ var version = "0.0.0-dev.53";
6630
6630
  //#endregion
6631
6631
  //#region src/proto/lovable/appworkflows/v1/workflow_manifest_pb.ts
6632
6632
  /**
@@ -6839,15 +6839,15 @@ function serializeSchema(schema, direction, label) {
6839
6839
  }
6840
6840
  }
6841
6841
  async function generateManifests(definition, options = {}) {
6842
- const { extractWorkflowGraph } = await import("./graph-RIBcr2Xd.js");
6843
- const { findBranchMetadataIssues } = await import("./branch-metadata-DIu0sMPS.js");
6844
- const { findWorkflowContextEscapes } = await import("./context-escapes-CMZlpkct.js");
6845
- const { findDuplicateOperationIds } = await import("./duplicate-ids-DiBCVnwz.js");
6842
+ const { extractWorkflowGraph } = await import("./graph-CM_9qQRY.js");
6843
+ const { findBranchMetadataIssues } = await import("./branch-metadata-CNODXoto.js");
6844
+ const { findWorkflowContextEscapes } = await import("./context-escapes-BNHZCoPP.js");
6845
+ const { findDuplicateOperationIds } = await import("./duplicate-ids-x8RBlqqt.js");
6846
6846
  const { DURABLE_ID_REQUIRED } = await import("./durable-ids-Cx341nJQ.js").then((n) => n.n);
6847
- const { findNestedDurableOperations } = await import("./nested-operations-xQdnHHR7.js");
6848
- const { findOperationDescriptionIssues } = await import("./operation-descriptions-BGSwAA0h.js");
6849
- const { findStepMetadataIssues } = await import("./step-metadata-CzUMB8XT.js");
6850
- const { findWaitDeadlineIssues } = await import("./wait-deadlines-Dg0U2ZK5.js");
6847
+ const { findNestedDurableOperations } = await import("./nested-operations-uuh9dqQ4.js");
6848
+ const { findOperationDescriptionIssues } = await import("./operation-descriptions-CckzdTDh.js");
6849
+ const { findStepMetadataIssues } = await import("./step-metadata-DKOzeqh8.js");
6850
+ const { findWaitDeadlineIssues } = await import("./wait-deadlines-Cm5bsMxr.js");
6851
6851
  const { WAIT_DEADLINE_REQUIRED } = await import("./wait-deadlines-DpK-Fgnd.js");
6852
6852
  const collection = registerWorkflows(definition);
6853
6853
  const manifests = [];
@@ -1,4 +1,4 @@
1
- import { C as WorkflowManifestWaitForEventNodeV1Schema, S as WorkflowManifestUuidNodeV1Schema, _ as WorkflowManifestSleepNodeV1Schema, a as WorkflowManifestConnectorNodeV1Schema, b as WorkflowManifestStepNodeV1Schema, c as WorkflowManifestGraphV1Schema, d as WorkflowManifestNowNodeV1Schema, f as WorkflowManifestOrderEdgeV1Schema, g as WorkflowManifestRepeatedStepV1Schema, h as WorkflowManifestRepeatedLlmV1Schema, i as WorkflowManifestBranchNodeV1Schema, l as WorkflowManifestLlmNodeV1Schema, m as WorkflowManifestRepeatedConnectorV1Schema, n as WorkflowManifestApproveNodeV1Schema, o as WorkflowManifestGraphEdgeV1Schema, p as WorkflowManifestParallelNodeV1Schema, r as WorkflowManifestBranchEdgeV1Schema, s as WorkflowManifestGraphNodeV1Schema, u as WorkflowManifestLoopNodeV1Schema, v as WorkflowManifestSleepUntilNodeV1Schema, w as create, x as WorkflowManifestUnknownNodeV1Schema, y as WorkflowManifestStepExecutionPolicyV1Schema } from "./generate-C9MJlJBn.js";
1
+ import { C as WorkflowManifestWaitForEventNodeV1Schema, S as WorkflowManifestUuidNodeV1Schema, _ as WorkflowManifestSleepNodeV1Schema, a as WorkflowManifestConnectorNodeV1Schema, b as WorkflowManifestStepNodeV1Schema, c as WorkflowManifestGraphV1Schema, d as WorkflowManifestNowNodeV1Schema, f as WorkflowManifestOrderEdgeV1Schema, g as WorkflowManifestRepeatedStepV1Schema, h as WorkflowManifestRepeatedLlmV1Schema, i as WorkflowManifestBranchNodeV1Schema, l as WorkflowManifestLlmNodeV1Schema, m as WorkflowManifestRepeatedConnectorV1Schema, n as WorkflowManifestApproveNodeV1Schema, o as WorkflowManifestGraphEdgeV1Schema, p as WorkflowManifestParallelNodeV1Schema, r as WorkflowManifestBranchEdgeV1Schema, s as WorkflowManifestGraphNodeV1Schema, u as WorkflowManifestLoopNodeV1Schema, v as WorkflowManifestSleepUntilNodeV1Schema, w as create, x as WorkflowManifestUnknownNodeV1Schema, y as WorkflowManifestStepExecutionPolicyV1Schema } from "./generate-Cn2I_zLU.js";
2
2
  import { n as assertLlmOptions, t as assertLlmModel } from "./llm-validation-DdDO6csU.js";
3
3
  //#region src/manifests/handler-source.ts
4
4
  const nativeFunctionSource = /\{\s*\[native code\]\s*\}\s*$/;
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { t as DURABLE_ID_REQUIRED } from "./durable-ids-Cx341nJQ.js";
2
- import { A as daily, D as registerWorkflows, E as createWorkflow, M as weekly, O as workflowVersions, T as createMiddleware, j as hourly, k as defineSchedule, t as generateManifests } from "./generate-C9MJlJBn.js";
2
+ import { A as daily, D as registerWorkflows, E as createWorkflow, M as weekly, O as workflowVersions, T as createMiddleware, j as hourly, k as defineSchedule, t as generateManifests } from "./generate-Cn2I_zLU.js";
3
3
  import { n as assertLlmOptions, r as assertLlmRequest } from "./llm-validation-DdDO6csU.js";
4
4
  import { WorkflowRequestParseError, inMemoryRunStore, parseWorkflowRequest, runWorkflow } from "@tanstack/workflow-core";
5
5
  import { generateChatCompletion } from "@lovable.dev/ai-gateway";
@@ -1,4 +1,4 @@
1
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-RIBcr2Xd.js";
1
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-CM_9qQRY.js";
2
2
  //#region src/manifests/nested-operations.ts
3
3
  const durableMethods = [
4
4
  "step",
@@ -1,4 +1,4 @@
1
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-RIBcr2Xd.js";
1
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-CM_9qQRY.js";
2
2
  //#region src/manifests/operation-descriptions.ts
3
3
  const optionsArgument = {
4
4
  approve: 0,
@@ -1,4 +1,4 @@
1
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-RIBcr2Xd.js";
1
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-CM_9qQRY.js";
2
2
  //#region src/manifests/step-metadata.ts
3
3
  async function findStepMetadataIssues(handler) {
4
4
  const api = await loadTypeScript();
package/dist/vite.js CHANGED
@@ -1,4 +1,4 @@
1
- import { t as generateManifests } from "./generate-C9MJlJBn.js";
1
+ import { t as generateManifests } from "./generate-Cn2I_zLU.js";
2
2
  import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
3
3
  import { createServer } from "vite";
4
4
  import { lstat, mkdir, mkdtemp, readdir, rename, rm, writeFile } from "node:fs/promises";
@@ -1,4 +1,4 @@
1
- import { loadTypeScript, t as workflowHandlerSource } from "./graph-RIBcr2Xd.js";
1
+ import { loadTypeScript, t as workflowHandlerSource } from "./graph-CM_9qQRY.js";
2
2
  //#region src/manifests/wait-deadlines.ts
3
3
  const optionsArgument = {
4
4
  approve: 0,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lovable.dev/workflows-sdk",
3
- "version": "0.0.0-dev.52",
3
+ "version": "0.0.0-dev.53",
4
4
  "publishConfig": {
5
5
  "access": "public",
6
6
  "tag": "dev",
@@ -31,7 +31,7 @@
31
31
  "dependencies": {
32
32
  "@standard-schema/spec": "^1.1.0",
33
33
  "@tanstack/workflow-core": "0.0.4",
34
- "@lovable.dev/ai-gateway": "0.1.9"
34
+ "@lovable.dev/ai-gateway": "0.1.10"
35
35
  },
36
36
  "devDependencies": {
37
37
  "@bufbuild/protobuf": "^2.10.1",