@versori/run 0.4.0-alpha.1 → 0.4.0-docs.14

package/esm/src/dsl/http/versori/proxyroundtripper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxyroundtripper.d.ts","sourceRoot":"","sources":["../../../../../src/src/dsl/http/versori/proxyroundtripper.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AACvD,OAAO,EAAE,WAAW,EAAmB,MAAM,mCAAmC,CAAC;AACjF,OAAO,EAEH,cAAc,EACd,YAAY,EACZ,cAAc,EACd,mBAAmB,EACtB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAU9D,qBAAa,iBAAkB,YAAW,mBAAmB;IACzD,OAAO,CAAC,kBAAkB,CAAS;IAEnC,OAAO,CAAC,SAAS,CAAe;IAEhC,OAAO,CAAC,WAAW,CAAc;IAEjC,OAAO,CAAC,YAAY,CAAe;IAEnC,OAAO,CAAC,GAAG,CAAS;IAEpB,OAAO,CAAC,cAAc,CAAS;IAE/B,OAAO,CAAC,KAAK,CAAS;gBAGlB,GAAG,EAAE,MAAM,EACX,kBAAkB,EAAE,MAAM,EAC1B,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,YAAY,EACvB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM;IAWjB,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB;IA2B9C,OAAO,CAAC,kBAAkB;IAa1B,OAAO,CAAC,cAAc;YA6BR,aAAa;IA4B3B,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,KAAK,GAAG,SAAS,CAAC;IAoB3D,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAwCxE,WAAW,IAAI,mBAAmB;IAoBlC,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,cAAc;CAKxD"}

package/esm/src/dsl/http/versori/proxyroundtripper.js

@@ -0,0 +1,208 @@
+/*
+ * Copyright (c) 2025 Versori Group Inc
+ *
+ * Use of this software is governed by the Business Source License 1.1
+ * included in the LICENSE file at the root of this repository.
+ *
+ * Change Date: 2029-01-01
+ * Change License: Apache License, Version 2.0
+ *
+ * As of the Change Date, in accordance with the Business Source License,
+ * use of this software will be governed by the Apache License, Version 2.0.
+ */
+import { PlatformApiImpl } from '../../../services/platform/mod.js';
+import { VersoriConfigReader } from './configloader.js';
+import { envVarEnvId, envVarOrgId, envVarPlatformApiBaseURL } from './constants.js';
+import { isValidURL } from './helpers.js';
+import { InternalAuth } from './internalauth.js';
+// TODO(@teo): there's a stub implementation of this at src/connection/ProxyConnectionFactory.ts, it may be worth
+//  skipping this for getting performance tests over the line, and implement this next week when things calm down. We
+//  can sort out running locally another day.
+// ProxyRoundTripper is a factory for creating roundtrippers that use the Versori Platform API proxy endpoints.
+// this should allow code from the platform to be run locally.
+export class ProxyRoundTripper {
+    constructor(log, platformApiBaseUrl, platformApi, cfgReader, orgId, envId) {
+        Object.defineProperty(this, "platformApiBaseUrl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "cfgReader", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "platformApi", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "internalAuth", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "log", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "organisationId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "envId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.cfgReader = cfgReader;
+        this.log = log;
+        this.platformApiBaseUrl = platformApiBaseUrl;
+        this.platformApi = platformApi;
+        this.internalAuth = new InternalAuth();
+        this.organisationId = orgId;
+        this.envId = envId;
+    }
+    static fromEnv(log) {
+        const baseUrl = Deno.env.get(envVarPlatformApiBaseURL);
+        const orgId = Deno.env.get(envVarOrgId);
+        const envId = Deno.env.get(envVarEnvId);
+        const cfgReader = VersoriConfigReader.fromEnv(log);
+        if (!baseUrl || !orgId || !envId) {
+            const missingVars = [];
+            if (!baseUrl)
+                missingVars.push(envVarPlatformApiBaseURL);
+            if (!orgId)
+                missingVars.push(envVarOrgId);
+            if (!envId)
+                missingVars.push(envVarEnvId);
+            log.error(`Missing required environment variables: ${missingVars.join(', ')}`);
+            throw new Error('Missing required environment variables: ' + missingVars.join(', '));
+        }
+        return new ProxyRoundTripper(log, baseUrl, PlatformApiImpl.create(baseUrl), cfgReader, orgId, envId);
+    }
+    makeProxyUrlString(url, cnxId) {
+        if (isValidURL(url)) {
+            const _url = new URL(url);
+            const proxyUrl = `${this.platformApiBaseUrl}/proxy/${cnxId}${_url.pathname}${_url.search}`;
+            return proxyUrl;
+        }
+        // here we assume we just have the path and query string
+        // although we could have a leading slash
+        const proxyPath = url.startsWith('/') ? url : `/${url}`;
+        return `${this.platformApiBaseUrl}/proxy/${cnxId}${proxyPath}`;
+    }
+    makeProxyInput(input, cnxId) {
+        if (typeof input === 'string') {
+            return this.makeProxyUrlString(input, cnxId);
+        }
+        if (input instanceof URL) {
+            const proxyUrl = new URL(input);
+            proxyUrl.hostname = this.platformApiBaseUrl.replace(/^https?:\/\//, '');
+            proxyUrl.pathname = `/proxy/${cnxId}${input.pathname}`;
+            return proxyUrl;
+        }
+        if (input instanceof Request) {
+            const requestUrl = this.makeProxyUrlString(input.url, cnxId);
+            // not actually sure if these headers overwrite whatever is in init but I have never seen
+            // the AI use the Request type
+            const proxyRequest = new Request(requestUrl, {
+                ...input,
+                headers: new Headers(input.headers),
+            });
+            return proxyRequest;
+        }
+        return input;
+    }
+    async makeProxyInit(init) {
+        if (!init) {
+            init = {};
+        }
+        if (!init.headers) {
+            init.headers = new Headers();
+        }
+        // could be tidied up but this'll do
+        const authHeader = await this.internalAuth.getAuthHeader();
+        const cookie = authHeader['Cookie'];
+        // insert the auth cookie into the headers
+        if (init.headers instanceof Headers) {
+            init.headers.set('Cookie', cookie);
+        }
+        else if (init.headers instanceof Array) {
+            init.headers.push(['Cookie', cookie]);
+        }
+        else {
+            init.headers = {
+                ...init.headers,
+                ['Cookie']: cookie,
+            };
+        }
+        return init;
+    }
+    create(connName) {
+        const cnxId = this.cfgReader.getConnectionID(connName);
+        if (!cnxId) {
+            this.log.error(`Connection ${connName} not found in configuration`);
+            return Promise.resolve(undefined);
+        }
+        const _fn = async (input, init) => {
+            const proxyInput = this.makeProxyInput(input, cnxId);
+            const proxyInit = await this.makeProxyInit(init);
+            this.log.info('proxy input and init', { input: proxyInput, init: proxyInit });
+            return globalThis.fetch(proxyInput, proxyInit);
+        };
+        return Promise.resolve(_fn);
+    }
+    createDynamic(templateName) {
+        const template = this.cfgReader.getTemplateID(templateName);
+        if (!template) {
+            this.log.error(`Template ${templateName} not found in configuration, could be a static connection`);
+            return Promise.resolve(undefined);
+        }
+        const _fn = async (activation, input, init) => {
+            const { data: conn } = await this.platformApi.getActivationConnection({
+                path: {
+                    organisation_id: this.organisationId,
+                    env_system_id: template,
+                    activation_id: activation.id,
+                },
+            });
+            if (!conn) {
+                this.log.error(`Connection not found for activation ${activation.id} and template ${template}, using default fetch`);
+                return globalThis.fetch(input, init);
+            }
+            const proxyInput = this.makeProxyInput(input, conn.id);
+            const proxyInit = await this.makeProxyInit(init);
+            this.log.info('proxy input and init', { input: proxyInput, init: proxyInit });
+            return globalThis.fetch(proxyInput, proxyInit);
+        };
+        return Promise.resolve(_fn);
+    }
+    credentials() {
+        return {
+            getRaw: (_name, _actId) => {
+                return Promise.reject(new Error('Not implemented, getRaw is not supported in proxy mode'));
+            },
+            getAccessToken: (_name, _forceRefresh, _actId) => {
+                return Promise.reject(new Error('Not implemented, getAccessToken is not supported in proxy mode'));
+            },
+            getOAuth1Metadata: (_name, _actId) => {
+                return Promise.reject(new Error('Not implemented, getOAuth1Metadata is not supported in proxy mode'));
+            },
+        };
+    }
+    baseUrlFetcher(_templateName) {
+        return async (_activationId) => {
+            return Promise.resolve('do not use this here');
+        };
+    }
+}

package/esm/src/dsl/http/versori/webhookmiddleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webhookmiddleware.d.ts","sourceRoot":"","sources":["../../../../../src/src/dsl/http/versori/webhookmiddleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAEjE,OAAO,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AACvD,OAAO,EAAc,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAU3C,MAAM,MAAM,2BAA2B,GAAG;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,WAAW,CAAC;IACzB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,SAAS,EAAE,YAAY,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;CACf,CAAC;AAiCF,wBAAgB,6BAA6B,CACzC,IAAI,EAAE,2BAA2B,GAClC,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAkFpE;AAED,wBAAgB,mCAAmC,CAC/C,IAAI,EAAE,2BAA2B,GAClC,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CA6DpE;AAED,wBAAgB,oCAAoC,CAChD,IAAI,EAAE,2BAA2B,GAClC,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAqFpE"}
+{"version":3,"file":"webhookmiddleware.d.ts","sourceRoot":"","sources":["../../../../../src/src/dsl/http/versori/webhookmiddleware.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAG1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AACvD,OAAO,EAAc,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,EAAwB,YAAY,EAAE,MAAM,aAAa,CAAC;AAUjE,MAAM,MAAM,2BAA2B,GAAG;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,WAAW,CAAC;IACzB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,SAAS,EAAE,YAAY,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;CACf,CAAC;AAmCF,wBAAgB,6BAA6B,CACzC,IAAI,EAAE,2BAA2B,GAClC,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CA2EpE;AAED,wBAAgB,mCAAmC,CAC/C,IAAI,EAAE,2BAA2B,GAClC,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CA6DpE;AAED,wBAAgB,oCAAoC,CAChD,IAAI,EAAE,2BAA2B,GAClC,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAqFpE"}

package/esm/src/dsl/http/versori/webhookmiddleware.js

@@ -1,4 +1,15 @@
-import { enabled as supervisorEnabled } from '../../../internal/supervisor.js';
+/*
+ * Copyright (c) 2025 Versori Group Inc
+ *
+ * Use of this software is governed by the Business Source License 1.1
+ * included in the LICENSE file at the root of this repository.
+ *
+ * Change Date: 2029-01-01
+ * Change License: Apache License, Version 2.0
+ *
+ * As of the Change Date, in accordance with the Business Source License,
+ * use of this software will be governed by the Apache License, Version 2.0.
+ */
 // TODO: this gets called for every request for all endpoints, can we cache this?
 async function getStaticActivation(opts) {
     const { data: activations } = await opts.platformApi.listActivations({
@@ -30,19 +41,7 @@ export function createStaticWebhookMiddleware(opts) {
     if (opts.connName === undefined) {
         opts.log.warn(`No connection ID found for webhook, accepting any requests which is unsecure!`, { webhookId: opts.id });
         return async (_req, res, next) => {
-            try {
-                res.locals.activation = await getStaticActivation(opts);
-            }
-            catch (err) {
-                if (supervisorEnabled) {
-                    res.locals.activation = {};
-                    next();
-                    return;
-                }
-                opts.log.error('Failed to get static activation', { error: err });
-                res.status(500).json({ error: 'Failed to get static activation' });
-                return;
-            }
+            res.locals.activation = await getStaticActivation(opts);
             next();
         };
     }
@@ -62,7 +61,10 @@ export function createStaticWebhookMiddleware(opts) {
         }
         const activation = await getStaticActivation(opts);
         if (!activation) {
-            opts.log.error('No activation found for static webhook', { webhookId: opts.id, connName: opts.connName });
+            opts.log.error('No activation found for static webhook', {
+                webhookId: opts.id,
+                connName: opts.connName,
+            });
             res.status(500).json({ error: 'No activation found for static webhook' });
             return;
         }
@@ -74,7 +76,10 @@ export function createStaticWebhookMiddleware(opts) {
             },
         });
         if (!cnx) {
-            opts.log.error(`No connection found for webhook`, { webhookId: opts.id, connName: opts.connName });
+            opts.log.error(`No connection found for webhook`, {
+                webhookId: opts.id,
+                connName: opts.connName,
+            });
             res.status(500).json({ error: 'No connection found for webhook' });
             return;
         }

package/esm/src/dsl/mod.d.ts

@@ -1,4 +1,20 @@
-export type { Task, Taskable, ArrayTask, } from './Task.js';
+/**
+ * The dsl module provides the functionality for defining workflows. Workflows created via this module must be
+ * registered with an interpreter to be executed, see the {@link interpreter} module for more information.
+ *
+ * The main exports you will need to use from this module are:
+ *
+ * - {@link http}: Provides the functionality for defining tasks which inject a `fetch` function onto the context with
+ *   authentication automatically configured for the provided connection.
+ * - {@link schedule}: Provides the functionality for defining workflows which are triggered on a cron schedule.
+ * - {@link webhook}: Provides the functionality for defining workflows which are triggered when a webhook is received.
+ *
+ * @module
+ */
+export * from './http/mod.js';
 export * from './tasks/mod.js';
 export * from './triggers/mod.js';
+export type { Trigger } from './Trigger.js';
+export type { Task, Taskable, TaskType } from './Task.js';
+export type { Workflow } from './Workflow.js';
 //# sourceMappingURL=mod.d.ts.map

package/esm/src/dsl/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../src/src/dsl/mod.ts"],"names":[],"mappings":"AACA,YAAY,EACR,IAAI,EACJ,QAAQ,EACR,SAAS,GACZ,MAAM,WAAW,CAAC;AAGnB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../src/src/dsl/mod.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;GAYG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAElC,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1D,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/esm/src/dsl/mod.js

@@ -1,3 +1,28 @@
-// Re-export types from Trigger base interfaces
+/*
+ * Copyright (c) 2025 Versori Group Inc
+ *
+ * Use of this software is governed by the Business Source License 1.1
+ * included in the LICENSE file at the root of this repository.
+ *
+ * Change Date: 2029-01-01
+ * Change License: Apache License, Version 2.0
+ *
+ * As of the Change Date, in accordance with the Business Source License,
+ * use of this software will be governed by the Apache License, Version 2.0.
+ */
+/**
+ * The dsl module provides the functionality for defining workflows. Workflows created via this module must be
+ * registered with an interpreter to be executed, see the {@link interpreter} module for more information.
+ *
+ * The main exports you will need to use from this module are:
+ *
+ * - {@link http}: Provides the functionality for defining tasks which inject a `fetch` function onto the context with
+ *   authentication automatically configured for the provided connection.
+ * - {@link schedule}: Provides the functionality for defining workflows which are triggered on a cron schedule.
+ * - {@link webhook}: Provides the functionality for defining workflows which are triggered when a webhook is received.
+ *
+ * @module
+ */
+export * from './http/mod.js';
 export * from './tasks/mod.js';
 export * from './triggers/mod.js';

package/esm/src/dsl/tasks/BackgroundTask.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BackgroundTask.d.ts","sourceRoot":"","sources":["../../../../src/src/dsl/tasks/BackgroundTask.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAKjE,qBAAa,cAAc,CAAC,EAAE,EAAE,GAAG,CAAE,YAAW,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC;IAC1D,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAgB;IAElC,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;gBAET,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC;IAI/B,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC;IAI/D,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC;IAIjE,UAAU,IAAI,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC;IAI5B,MAAM,CAAC,OAAO,GAAG,GAAG,SAAS,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,GAAG,KAAK,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC;IACtF,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,EAAE,GAAG,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC;IAS1E,KAAK,IAAI,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC;CAG1B"}
+{"version":3,"file":"BackgroundTask.d.ts","sourceRoot":"","sources":["../../../../src/src/dsl/tasks/BackgroundTask.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAKjE,qBAAa,cAAc,CAAC,EAAE,EAAE,GAAG,CAAE,YAAW,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC;IAC1D,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAgB;IAElC,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;gBAET,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC;IAI/B,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC;IAI/D,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC;IAIjE,UAAU,IAAI,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC;IAI5B,MAAM,CAAC,OAAO,GAAG,GAAG,SAAS,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,GAAG,KAAK,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC;IACtF,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,EAAE,GAAG,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC;IAS1E,KAAK,IAAI,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC;CAG1B"}

package/esm/src/dsl/tasks/BackgroundTask.js

@@ -1,3 +1,15 @@
+/*
+ * Copyright (c) 2025 Versori Group Inc
+ *
+ * Use of this software is governed by the Business Source License 1.1
+ * included in the LICENSE file at the root of this repository.
+ *
+ * Change Date: 2029-01-01
+ * Change License: Apache License, Version 2.0
+ *
+ * As of the Change Date, in accordance with the Business Source License,
+ * use of this software will be governed by the Apache License, Version 2.0.
+ */
 var _a;
 import { ensureTask } from '../ensureTask.js';
 import { TaskType } from '../Task.js';

package/esm/src/dsl/tasks/CatchTask.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CatchTask.d.ts","sourceRoot":"","sources":["../../../../src/src/dsl/tasks/CatchTask.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAKjE,qBAAa,SAAS,CAAC,EAAE,EAAE,GAAG,CAAE,YAAW,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC;IACpD,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAW;IAE7B,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IAChB,aAAa,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;gBAEpB,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC;IAK1D,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC;IAI9D,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC;IAIjE,UAAU,IAAI,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC;IAI5B,MAAM,CAAC,OAAO,GAAG,GAAG,SAAS,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,GAAG,KAAK,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC;IACtF,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,EAAE,GAAG,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC;IASzE,KAAK,IAAI,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC;CAGzB"}
+{"version":3,"file":"CatchTask.d.ts","sourceRoot":"","sources":["../../../../src/src/dsl/tasks/CatchTask.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAKjE,qBAAa,SAAS,CAAC,EAAE,EAAE,GAAG,CAAE,YAAW,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC;IACpD,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAW;IAE7B,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IAChB,aAAa,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;gBAEpB,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC;IAK1D,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC;IAI9D,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC;IAIjE,UAAU,IAAI,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC;IAI5B,MAAM,CAAC,OAAO,GAAG,GAAG,SAAS,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,GAAG,KAAK,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC;IACtF,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,EAAE,GAAG,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC;IASzE,KAAK,IAAI,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC;CAGzB"}

package/esm/src/dsl/tasks/CatchTask.js

@@ -1,3 +1,15 @@
+/*
+ * Copyright (c) 2025 Versori Group Inc
+ *
+ * Use of this software is governed by the Business Source License 1.1
+ * included in the LICENSE file at the root of this repository.
+ *
+ * Change Date: 2029-01-01
+ * Change License: Apache License, Version 2.0
+ *
+ * As of the Change Date, in accordance with the Business Source License,
+ * use of this software will be governed by the Apache License, Version 2.0.
+ */
 var _a;
 import { ensureTask } from '../ensureTask.js';
 import { TaskType } from '../Task.js';

package/esm/src/dsl/tasks/ChainTask.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChainTask.d.ts","sourceRoot":"","sources":["../../../../src/src/dsl/tasks/ChainTask.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAKjE,qBAAa,SAAS,CAAC,EAAE,EAAE,GAAG,CAAE,YAAW,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC;IACpD,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAW;IAE7B,KAAK,EAAE,IAAI,EAAE,CAAM;gBAEP,GAAG,KAAK,EAAE,IAAI,EAAE;IAI5B,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC;IAI9D,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC;IAIjE,UAAU,IAAI,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC;IAI5B,MAAM,CAAC,OAAO,GAAG,GAAG,SAAS,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,GAAG,KAAK,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC;IACtF,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,EAAE,GAAG,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC;IASzE,KAAK,IAAI,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC;CAGzB"}
+{"version":3,"file":"ChainTask.d.ts","sourceRoot":"","sources":["../../../../src/src/dsl/tasks/ChainTask.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAKjE,qBAAa,SAAS,CAAC,EAAE,EAAE,GAAG,CAAE,YAAW,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC;IACpD,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAW;IAE7B,KAAK,EAAE,IAAI,EAAE,CAAM;gBAEP,GAAG,KAAK,EAAE,IAAI,EAAE;IAI5B,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC;IAI9D,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC;IAIjE,UAAU,IAAI,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC;IAI5B,MAAM,CAAC,OAAO,GAAG,GAAG,SAAS,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,GAAG,KAAK,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC;IACtF,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,EAAE,GAAG,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC;IASzE,KAAK,IAAI,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC;CAGzB"}

package/esm/src/dsl/tasks/ChainTask.js

@@ -1,3 +1,15 @@
+/*
+ * Copyright (c) 2025 Versori Group Inc
+ *
+ * Use of this software is governed by the Business Source License 1.1
+ * included in the LICENSE file at the root of this repository.
+ *
+ * Change Date: 2029-01-01
+ * Change License: Apache License, Version 2.0
+ *
+ * As of the Change Date, in accordance with the Business Source License,
+ * use of this software will be governed by the Apache License, Version 2.0.
+ */
 var _a;
 import { ensureTask } from '../ensureTask.js';
 import { TaskType } from '../Task.js';
@@ -21,7 +33,7 @@ export class ChainTask {
         this.tasks = tasks;
     }
     then(task) {
-        return new ChainTask(...this.tasks.map(t => t.clone()), ensureTask(task));
+        return new ChainTask(...this.tasks.map((t) => t.clone()), ensureTask(task));
     }
     catch(task) {
         return new CatchTask(this.clone(), ensureTask(task));
@@ -36,7 +48,7 @@ export class ChainTask {
         return new UnpackTask(this.clone());
     }
     clone() {
-        return new ChainTask(...this.tasks.map(t => t.clone()));
+        return new ChainTask(...this.tasks.map((t) => t.clone()));
     }
 }
 _a = TaskType;

package/esm/src/dsl/tasks/FnTask.d.ts

@@ -10,7 +10,31 @@ export declare class FnTask<In, Out, Index = void> implements Task<In, Out> {
     background(): Task<In, void>;
     unpack<NextOut = Out extends Array<infer Elem> ? Elem : Out>(): ArrayTask<In, NextOut>;
     unpack<NextOut>(mapper: (data: Out) => NextOut[]): ArrayTask<In, NextOut>;
-    clone(): FnTask<In, Out, Index>;
+    clone(): Task<In, Out>;
 }
+/**
+ * Create a task that executes a function with access to the workflow context.
+ *
+ * The provided function receives a {@link Context} object containing the current workflow data, logger, and other
+ * utilities for implementing workflow logic. This is the primary building block for custom workflow tasks.
+ *
+ * @template I The input type expected by the function.
+ * @template O The output type produced by the function.
+ * @template Index Optional index parameter used when processing arrays.
+ * @param id A unique identifier for this task, this will be used in execution traces to identify spans in the
+ *        execution.
+ * @param fn The function to execute, which receives a context object.
+ * @returns A task that can be chained in a workflow.
+ *
+ * @example
+ * ```typescript
+ * import { fn } from '@versori/run';
+ *
+ * const myTask = fn('process-data', (ctx) => {
+ *   ctx.log.info('Processing data', { input: ctx.data });
+ *   return { result: ctx.data * 2 };
+ * });
+ * ```
+ */
 export declare function fn<I, O, Index = void>(id: string, fn: ContextFunc<I, O, Index>): Task<I, O>;
 //# sourceMappingURL=FnTask.d.ts.map

package/esm/src/dsl/tasks/FnTask.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FnTask.d.ts","sourceRoot":"","sources":["../../../../src/src/dsl/tasks/FnTask.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAE3D,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAMjE,qBAAa,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,CAAE,YAAW,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC;IAC/D,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAQ;IAC1B,EAAE,EAAE,MAAM,CAAC;IAEX,GAAG,EAAE,WAAW,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;gBAErB,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC;IAKvD,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC;IAI9D,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC;IAIjE,UAAU,IAAI,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC;IAI5B,MAAM,CAAC,OAAO,GAAG,GAAG,SAAS,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,GAAG,KAAK,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC;IACtF,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,EAAE,GAAG,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC;IASzE,KAAK;CAGR;AAED,wBAAgB,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,GAAG,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAE3F"}
+{"version":3,"file":"FnTask.d.ts","sourceRoot":"","sources":["../../../../src/src/dsl/tasks/FnTask.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAE3D,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAMjE,qBAAa,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,CAAE,YAAW,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC;IAC/D,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAQ;IAC1B,EAAE,EAAE,MAAM,CAAC;IAEX,GAAG,EAAE,WAAW,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;gBAErB,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC;IAKvD,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC;IAI9D,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC;IAIjE,UAAU,IAAI,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC;IAI5B,MAAM,CAAC,OAAO,GAAG,GAAG,SAAS,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,GAAG,KAAK,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC;IACtF,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,EAAE,GAAG,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC;IASzE,KAAK,IAAI,IAAI,CAAC,EAAE,EAAE,GAAG,CAAC;CAGzB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,GAAG,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAE3F"}

package/esm/src/dsl/tasks/FnTask.js

@@ -1,3 +1,15 @@
+/*
+ * Copyright (c) 2025 Versori Group Inc
+ *
+ * Use of this software is governed by the Business Source License 1.1
+ * included in the LICENSE file at the root of this repository.
+ *
+ * Change Date: 2029-01-01
+ * Change License: Apache License, Version 2.0
+ *
+ * As of the Change Date, in accordance with the Business Source License,
+ * use of this software will be governed by the Apache License, Version 2.0.
+ */
 var _a;
 import { ensureTask } from '../ensureTask.js';
 import { TaskType } from '../Task.js';
@@ -48,6 +60,30 @@ export class FnTask {
     }
 }
 _a = TaskType;
+/**
+ * Create a task that executes a function with access to the workflow context.
+ *
+ * The provided function receives a {@link Context} object containing the current workflow data, logger, and other
+ * utilities for implementing workflow logic. This is the primary building block for custom workflow tasks.
+ *
+ * @template I The input type expected by the function.
+ * @template O The output type produced by the function.
+ * @template Index Optional index parameter used when processing arrays.
+ * @param id A unique identifier for this task, this will be used in execution traces to identify spans in the
+ *        execution.
+ * @param fn The function to execute, which receives a context object.
+ * @returns A task that can be chained in a workflow.
+ *
+ * @example
+ * ```typescript
+ * import { fn } from '@versori/run';
+ *
+ * const myTask = fn('process-data', (ctx) => {
+ *   ctx.log.info('Processing data', { input: ctx.data });
+ *   return { result: ctx.data * 2 };
+ * });
+ * ```
+ */
 export function fn(id, fn) {
     return new FnTask(id, fn);
 }

package/esm/src/dsl/tasks/HttpTask.d.ts

@@ -1,35 +1,85 @@
 import type * as express from 'express';
 import { AsyncWorkflow } from '../../context/AsyncWorkflow.js';
-import { Context, ContextImpl, CreateIssue } from '../../context/Context.js';
+import { Context, ContextImpl, CreateIssue, WorkflowOpts } from '../../context/Context.js';
 import { Issue } from '../../issues/Issues.js';
 import { KeyValue, KeyValueScope } from '../../kv/KeyValue.js';
-import { WorkflowOpts } from '../../mod.js';
 import { Logger } from '../../observability/logging/Logger.js';
 import { CredentialsProvider } from '../http/versori/contextcredentials.js';
 import { ArrayTask, Task, Taskable, TaskType } from '../Task.js';
 import { ActivationImpl } from '../../context/ActivationImpl.js';
 import { FetchLike } from '../../connection/types.js';
+/**
+ * HttpContext extends the standard {@link Context} with HTTP-specific functionality including an authenticated
+ * `fetch` function and connection variables.
+ *
+ * @template Data The type of data being processed by the workflow.
+ * @template PageParams Optional pagination parameters type.
+ */
 export interface HttpContext<Data, PageParams = undefined> extends Context<Data> {
+    /**
+     * An authenticated fetch function preconfigured with the base URL and authentication from the connection
+     * configuration.
+     */
     fetch: typeof fetch;
+    /**
+     * Variables configured for this connection, which can include dynamic values set by the user.
+     */
     connectionVariables: Record<string, any>;
+    /**
+     * Current pagination parameters when using pagination.
+     */
     pageParams?: PageParams;
+    /**
+     * Function to trigger the next page of results when using pagination.
+     *
+     * @param nextParams The parameters for the next page.
+     */
     nextPage: (nextParams: PageParams) => Promise<void>;
+    /**
+     * The base URL for the connection, resolved asynchronously.
+     */
     baseUrl: Promise<string>;
 }
+/**
+ * HttpContextFunc is the function signature for HTTP task implementations.
+ *
+ * @template In The input type expected by the function.
+ * @template Out The output type produced by the function.
+ * @template PageParams Optional pagination parameters type.
+ */
 export type HttpContextFunc<In, Out, PageParams> = (ctx: HttpContext<In, PageParams>) => Promise<Out>;
+/**
+ * PaginateOptions configures pagination for an HTTP task.
+ *
+ * @template P The type of pagination parameters.
+ */
 export type PaginateOptions<P> = {
+    /**
+     * The initial pagination parameters to start with.
+     */
     initialParams: P;
 };
-export type HttpOptions<In, Out, PageParams> = {
+/**
+ * HttpOptions configures an HTTP task with connection and pagination settings.
+ *
+ * @template PageParams Optional pagination parameters type.
+ */
+export type HttpOptions<PageParams> = {
+    /**
+     * The name of the connection to use for authentication and base URL configuration.
+     */
     connection: string;
+    /**
+     * Optional pagination configuration.
+     */
     pagination?: PaginateOptions<PageParams>;
 };
 export declare class HttpTaskImpl<In, Out, PageParams> implements Task<In, Out> {
     [TaskType]: string;
     id: string;
     fn: HttpContextFunc<In, Out, PageParams>;
-    opts: HttpOptions<In, Out, PageParams>;
-    constructor(id: string, opts: HttpOptions<In, Out, PageParams>, fn: HttpContextFunc<In, Out, PageParams>);
+    opts: HttpOptions<PageParams>;
+    constructor(id: string, opts: HttpOptions<PageParams>, fn: HttpContextFunc<In, Out, PageParams>);
     then<NextOut>(task: Taskable<Out, NextOut>): Task<In, NextOut>;
     catch<NextOut>(task: Taskable<Error, NextOut>): Task<In, NextOut>;
     background(): Task<In, void>;
@@ -60,5 +110,30 @@ export declare class HttpContextImpl<D, PageParams> implements HttpContext<D, Pa
     nextPage(_nextParams: PageParams): Promise<void>;
     request(): express.Request | undefined;
 }
-export declare function http<In = any, Out = any, PageParams = unknown>(taskId: string, opts: HttpOptions<In, Out, PageParams>, fn: HttpContextFunc<In, Out, PageParams>): Task<In, Out>;
+/**
+ * Create a task that makes HTTP requests using an authenticated connection.
+ *
+ * The provided function receives an {@link HttpContext} with a pre-configured `fetch` function that includes
+ * authentication and the base URL from the specified connection. This is the primary way to interact with external
+ * APIs in Versori workflows.
+ *
+ * @template In The input type expected by the function.
+ * @template Out The output type produced by the function.
+ * @template PageParams Optional pagination parameters type.
+ * @param taskId A unique identifier for this task.
+ * @param opts Configuration including the connection name and optional pagination settings.
+ * @param fn The function to execute, which receives an HTTP context.
+ * @returns A task that can be chained in a workflow.
+ *
+ * @example
+ * ```typescript
+ * import { http } from '@versori/run';
+ *
+ * const fetchUsers = http('get-users', { connection: 'my-api' }, async ({ fetch }) => {
+ *   const response = await fetch('/users');
+ *   return response.json();
+ * });
+ * ```
+ */
+export declare function http<In = any, Out = any, PageParams = unknown>(taskId: string, opts: HttpOptions<PageParams>, fn: HttpContextFunc<In, Out, PageParams>): Task<In, Out>;
 //# sourceMappingURL=HttpTask.d.ts.map