@flowcore/pathways 0.2.1 → 0.2.2

package/esm/pathways/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/pathways/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAEzF;;GAEG;AACH,KAAK,uBAAuB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,GAAG;IACnD,QAAQ,CAAC,yBAAyB,EAAE,wGAAwG,CAAA;CAC7I,CAAA;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO;IACpF,QAAQ,EAAE,CAAC,CAAA;IACX,SAAS,EAAE,CAAC,CAAA;IACZ,MAAM,EAAE,CAAC,CAAA;IACT;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC3B;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,EAAE,CAAA;AAExE,MAAM,WAAW,aAAc,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAAG;AAEjE,MAAM,MAAM,WAAW,CAAC,YAAY,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,kBAAkB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;AAC1I,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,kBAAkB,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;AAElI;;GAEG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,UAAU,SAAS,OAAO,IAAI,UAAU,SAAS,KAAK,GAAG,uBAAuB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;AAErI,MAAM,MAAM,YAAY,GAAG;IACzB,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAA;IAC9D,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;CAC1D,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,GAAG;IACrD,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/pathways/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAEzF;;;GAGG;AACH,KAAK,uBAAuB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,GAAG;IACnD,QAAQ,CAAC,yBAAyB,EAAE,wGAAwG,CAAA;CAC7I,CAAA;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO;IACpF;;OAEG;IACH,QAAQ,EAAE,CAAC,CAAA;IAEX;;OAEG;IACH,SAAS,EAAE,CAAC,CAAA;IAEZ;;OAEG;IACH,MAAM,EAAE,CAAC,CAAA;IAET;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;IAE3B;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,EAAE,CAAA;AAExE;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAAG;AAEjE;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,YAAY,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,kBAAkB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;AAE1I;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,kBAAkB,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;AAElI;;;;GAIG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,UAAU,SAAS,OAAO,IAAI,UAAU,SAAS,KAAK,GAAG,uBAAuB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;AAErI;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB;;;;OAIG;IACH,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAA;IAE9D;;;OAGG;IACH,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;CAC1D,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,GAAG;IACrD;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IAEvB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC,CAAA"}

package/esm/router/index.d.ts

@@ -1,10 +1,16 @@
+/**
+ * Router module for Flowcore Pathways
+ *
+ * This module provides routing functionality to direct incoming events
+ * to the appropriate pathway handlers based on flow type and event type.
+ *
+ * @module
+ */
 import type { FlowcoreLegacyEvent } from "../common/flowcore.type.js";
 import type { PathwaysBuilder } from "../pathways/index.js";
 import type { Logger } from "../pathways/logger.js";
 /**
  * Router class that handles directing events to the appropriate pathway handlers
- *
- * @class PathwayRouter
  */
 export declare class PathwayRouter {
     private readonly pathways;
@@ -13,19 +19,19 @@ export declare class PathwayRouter {
     /**
      * Creates a new instance of PathwayRouter
      *
-     * @param {PathwaysBuilder<Record<string, any>>} pathways - The pathways builder instance that contains all registered pathways
-     * @param {string} secretKey - Secret key used for authentication when processing events
-     * @param {Logger} [logger] - Optional logger instance (defaults to NoopLogger if not provided)
-     * @throws {Error} Will throw an error if secretKey is empty or not provided
+     * @param pathways The pathways builder instance that contains all registered pathways
+     * @param secretKey Secret key used for authentication when processing events
+     * @param logger Optional logger instance (defaults to NoopLogger if not provided)
+     * @throws Error if secretKey is empty or not provided
      */
     constructor(pathways: PathwaysBuilder<Record<string, any>>, secretKey: string, logger?: Logger);
     /**
-     * Processes an incoming event by routing it to the appropriate pathway
+     * Process an incoming event by routing it to the appropriate pathway handler
      *
-     * @param {FlowcoreLegacyEvent} event - The event to process
-     * @param {string} providedSecret - The secret key provided for authentication
-     * @returns {Promise<{ success: boolean; message: string }>} Result of the event processing
-     * @throws {Error} Will throw an error if authentication fails, pathway is not found, or processing fails
+     * @param event The event to process
+     * @param providedSecret The secret key provided for authentication
+     * @returns Result of the event processing with success status and message
+     * @throws Error if authentication fails, pathway is not found, or processing fails
      */
     processEvent(event: FlowcoreLegacyEvent, providedSecret: string): Promise<{
         success: boolean;

package/esm/router/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/router/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAErE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAGnD;;;;GAIG;AACH,qBAAa,aAAa;IAatB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAb5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC;;;;;;;OAOG;gBAGgB,QAAQ,EAAE,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,EAC9C,SAAS,EAAE,MAAM,EAClC,MAAM,CAAC,EAAE,MAAM;IAYjB;;;;;;;OAOG;IACG,YAAY,CAAC,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAoDvH"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAErE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAGnD;;GAEG;AACH,qBAAa,aAAa;IAatB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAb5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC;;;;;;;OAOG;gBAGgB,QAAQ,EAAE,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,EAC9C,SAAS,EAAE,MAAM,EAClC,MAAM,CAAC,EAAE,MAAM;IAajB;;;;;;;OAOG;IACG,YAAY,CAAC,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAkDvH"}

package/esm/router/index.js

@@ -1,17 +1,15 @@
 import { NoopLogger } from "../pathways/logger.js";
 /**
  * Router class that handles directing events to the appropriate pathway handlers
- *
- * @class PathwayRouter
  */
 export class PathwayRouter {
     /**
      * Creates a new instance of PathwayRouter
      *
-     * @param {PathwaysBuilder<Record<string, any>>} pathways - The pathways builder instance that contains all registered pathways
-     * @param {string} secretKey - Secret key used for authentication when processing events
-     * @param {Logger} [logger] - Optional logger instance (defaults to NoopLogger if not provided)
-     * @throws {Error} Will throw an error if secretKey is empty or not provided
+     * @param pathways The pathways builder instance that contains all registered pathways
+     * @param secretKey Secret key used for authentication when processing events
+     * @param logger Optional logger instance (defaults to NoopLogger if not provided)
+     * @throws Error if secretKey is empty or not provided
      */
     constructor(
     // deno-lint-ignore no-explicit-any
@@ -36,24 +34,26 @@ export class PathwayRouter {
         });
         this.logger = logger ?? new NoopLogger();
         if (!secretKey || secretKey.trim() === "") {
-            this.logger.error("Secret key is required for PathwayRouter");
-            throw new Error("Secret key is required for PathwayRouter");
+            const errorMsg = "Secret key is required for PathwayRouter";
+            this.logger.error(errorMsg, new Error(errorMsg));
+            throw new Error(errorMsg);
         }
         this.logger.debug("PathwayRouter initialized");
     }
     /**
-     * Processes an incoming event by routing it to the appropriate pathway
+     * Process an incoming event by routing it to the appropriate pathway handler
      *
-     * @param {FlowcoreLegacyEvent} event - The event to process
-     * @param {string} providedSecret - The secret key provided for authentication
-     * @returns {Promise<{ success: boolean; message: string }>} Result of the event processing
-     * @throws {Error} Will throw an error if authentication fails, pathway is not found, or processing fails
+     * @param event The event to process
+     * @param providedSecret The secret key provided for authentication
+     * @returns Result of the event processing with success status and message
+     * @throws Error if authentication fails, pathway is not found, or processing fails
      */
     async processEvent(event, providedSecret) {
         // Validate secret key
         if (!providedSecret || providedSecret !== this.secretKey) {
-            this.logger.error("Invalid secret key provided");
-            throw new Error("Invalid secret key");
+            const errorMsg = "Invalid secret key";
+            this.logger.error(errorMsg, new Error(errorMsg));
+            throw new Error(errorMsg);
         }
         const compatibleEvent = {
             ...event,
@@ -65,9 +65,9 @@ export class PathwayRouter {
         });
         const pathway = this.pathways.get(pathwayKey);
         if (!pathway) {
-            const error = `Pathway ${pathwayKey} not found`;
-            this.logger.error(error);
-            throw new Error(error);
+            const errorMsg = `Pathway ${pathwayKey} not found`;
+            this.logger.error(errorMsg, new Error(errorMsg));
+            throw new Error(errorMsg);
         }
         try {
             this.logger.debug(`Delegating event processing to pathway handler`, {
@@ -82,15 +82,12 @@ export class PathwayRouter {
             return { success: true, message: `Event processed through pathway ${pathwayKey}` };
         }
         catch (error) {
-            const errorMessage = error instanceof Error
-                ? error.message
-                : String(error);
-            this.logger.error(`Error processing pathway ${pathwayKey}`, {
-                error: errorMessage,
+            const errorObj = error instanceof Error ? error : new Error(String(error));
+            this.logger.error(`Error processing pathway ${pathwayKey}`, errorObj, {
                 eventId: compatibleEvent.eventId
             });
             // Rethrow the error with additional context
-            throw new Error(`Failed to process event in pathway ${pathwayKey}: ${errorMessage}`);
+            throw new Error(`Failed to process event in pathway ${pathwayKey}: ${errorObj.message}`);
         }
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flowcore/pathways",
-  "version": "0.2.1",
-  "description": "A Deno Library for creating Flowcore Pathways, simplifying the integration with the flowcore platform",
+  "version": "0.2.2",
+  "description": "A TypeScript Library for creating Flowcore Pathways, simplifying the integration with the flowcore platform",
   "homepage": "https://github.com/flowcore-io/flowcore-sdk#readme",
   "repository": {
     "type": "git",

package/script/common/flowcore.type.d.ts

@@ -1,11 +1,11 @@
 import type { FlowcoreEvent } from "../contracts/event.js";
 /**
  * Extends the FlowcoreEvent with legacy fields
- *
- * @typedef {Object} FlowcoreLegacyEvent
- * @property {string} [aggregator] - Optional aggregator information for legacy support
  */
 export type FlowcoreLegacyEvent = FlowcoreEvent & {
+    /**
+     * Optional aggregator information for legacy support
+     */
     aggregator?: string;
 };
 //# sourceMappingURL=flowcore.type.d.ts.map

package/script/common/flowcore.type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flowcore.type.d.ts","sourceRoot":"","sources":["../../src/common/flowcore.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,aAAa,GAAG;IAChD,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA"}
+{"version":3,"file":"flowcore.type.d.ts","sourceRoot":"","sources":["../../src/common/flowcore.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE1D;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,aAAa,GAAG;IAChD;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,CAAA"}

package/script/common/index.d.ts

@@ -2,6 +2,8 @@
  * Common types and utilities for Flowcore Pathways
  *
  * This module exports common types and utilities that are used across the Flowcore Pathways library.
+ *
+ * @module
  */
 export * from "./flowcore.type.js";
 //# sourceMappingURL=index.d.ts.map

package/script/common/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/common/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/common/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,oBAAoB,CAAC"}

package/script/common/index.js

@@ -18,5 +18,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Common types and utilities for Flowcore Pathways
  *
  * This module exports common types and utilities that are used across the Flowcore Pathways library.
+ *
+ * @module
  */
 __exportStar(require("./flowcore.type.js"), exports);

package/script/compatibility/flowcore-transformer-core.sdk.d.ts

@@ -3,6 +3,8 @@
  *
  * This module re-exports components from the @flowcore/sdk-transformer-core package
  * to provide backwards compatibility with existing transformer implementations.
+ *
+ * @module
  */
 import transformerCore from "@flowcore/sdk-transformer-core";
 /**
@@ -11,6 +13,8 @@ import transformerCore from "@flowcore/sdk-transformer-core";
 export declare const WebhookBuilder: typeof transformerCore.WebhookBuilder;
 /**
  * Options for configuring webhook send operations
+ *
+ * These options control how webhook requests are sent, including timestamps and headers.
  */
 export type { WebhookSendOptions } from "@flowcore/sdk-transformer-core";
 //# sourceMappingURL=flowcore-transformer-core.sdk.d.ts.map

package/script/compatibility/flowcore-transformer-core.sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flowcore-transformer-core.sdk.d.ts","sourceRoot":"","sources":["../../src/compatibility/flowcore-transformer-core.sdk.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,eAAe,MAAM,gCAAgC,CAAA;AAE5D;;GAEG;AACH,eAAO,MAAQ,cAAc,uCAAoB,CAAA;AAEjD;;GAEG;AACH,YAAY,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA"}
+{"version":3,"file":"flowcore-transformer-core.sdk.d.ts","sourceRoot":"","sources":["../../src/compatibility/flowcore-transformer-core.sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,eAAe,MAAM,gCAAgC,CAAA;AAE5D;;GAEG;AACH,eAAO,MAAQ,cAAc,uCAAoB,CAAA;AAEjD;;;;GAIG;AACH,YAAY,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA"}

package/script/compatibility/flowcore-transformer-core.sdk.js

@@ -9,6 +9,8 @@ exports.WebhookBuilder = void 0;
  *
  * This module re-exports components from the @flowcore/sdk-transformer-core package
  * to provide backwards compatibility with existing transformer implementations.
+ *
+ * @module
  */
 const sdk_transformer_core_1 = __importDefault(require("@flowcore/sdk-transformer-core"));
 /**

package/script/contracts/index.d.ts

@@ -1,5 +1,7 @@
 /**
  * Export all contract types and schemas for Flowcore events
+ *
+ * @module
  */
 export * from "./event.js";
 //# sourceMappingURL=index.d.ts.map

package/script/contracts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contracts/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contracts/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,YAAY,CAAC"}

package/script/contracts/index.js

@@ -16,5 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * Export all contract types and schemas for Flowcore events
+ *
+ * @module
  */
 __exportStar(require("./event.js"), exports);

package/script/mod.d.ts

@@ -6,6 +6,8 @@
  * - Event contracts and schemas
  * - Pathway definitions and builders
  * - Event routing functionality
+ *
+ * @module
  */
 export * from "./common/index.js";
 export * from "./contracts/index.js";

package/script/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC"}

package/script/mod.js

@@ -22,6 +22,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * - Event contracts and schemas
  * - Pathway definitions and builders
  * - Event routing functionality
+ *
+ * @module
  */
 __exportStar(require("./common/index.js"), exports);
 __exportStar(require("./contracts/index.js"), exports);

package/script/pathways/builder.d.ts

@@ -3,12 +3,46 @@ import type { WebhookSendOptions } from "@flowcore/sdk-transformer-core";
 import type { FlowcoreEvent } from "../contracts/event.js";
 import type { Logger } from "./logger.js";
 import type { EventMetadata, PathwayContract, PathwayKey, PathwayState, PathwayWriteOptions, WritablePathway } from "./types.js";
+/**
+ * Defines the mode for auditing pathway operations
+ * - "user": Normal user-initiated operations
+ * - "system": System-initiated operations on behalf of a user
+ */
 export type AuditMode = "user" | "system";
+/**
+ * Handler function for auditing pathway events
+ * @param path The pathway path being audited
+ * @param event The event data being processed
+ */
 export type AuditHandler = (path: string, event: FlowcoreEvent) => void;
+/**
+ * Async function that resolves to the current user ID
+ * Used for audit functionality to track which user initiated an action
+ */
 export type UserIdResolver = () => Promise<string>;
+/**
+ * Extended webhook send options with additional audit-specific options
+ */
 export interface AuditWebhookSendOptions extends WebhookSendOptions {
+    /**
+     * Custom HTTP headers to include with the webhook request
+     */
     headers?: Record<string, string>;
 }
+/**
+ * Main builder class for creating and managing Flowcore pathways
+ *
+ * The PathwaysBuilder provides an interface for:
+ * - Registering pathways with type-safe schemas
+ * - Handling events sent to pathways
+ * - Writing data to pathways
+ * - Managing event processing and retries
+ * - Observing event lifecycle (before/after/error)
+ * - Audit logging of pathway operations
+ *
+ * @template TPathway Record type that maps pathway keys to their payload types
+ * @template TWritablePaths Union type of pathway keys that can be written to
+ */
 export declare class PathwaysBuilder<TPathway extends Record<string, unknown> = {}, TWritablePaths extends keyof TPathway = never> {
     private readonly pathways;
     private readonly handlers;
@@ -29,6 +63,16 @@ export declare class PathwaysBuilder<TPathway extends Record<string, unknown> =
     private auditHandler?;
     private userIdResolver?;
     private readonly logger;
+    /**
+     * Creates a new PathwaysBuilder instance
+     * @param options Configuration options for the PathwaysBuilder
+     * @param options.baseUrl The base URL for the Flowcore API
+     * @param options.tenant The tenant name
+     * @param options.dataCore The data core name
+     * @param options.apiKey The API key for authentication
+     * @param options.pathwayTimeoutMs Optional timeout for pathway processing in milliseconds
+     * @param options.logger Optional logger instance
+     */
     constructor({ baseUrl, tenant, dataCore, apiKey, pathwayTimeoutMs, logger, }: {
         baseUrl: string;
         tenant: string;
@@ -37,6 +81,11 @@ export declare class PathwaysBuilder<TPathway extends Record<string, unknown> =
         pathwayTimeoutMs?: number;
         logger?: Logger;
     });
+    /**
+     * Configures the PathwaysBuilder to use a custom pathway state implementation
+     * @param state The PathwayState implementation to use
+     * @returns The PathwaysBuilder instance with custom state configured
+     */
     withPathwayState(state: PathwayState): PathwaysBuilder<TPathway, TWritablePaths>;
     /**
      * Configures the PathwaysBuilder to use audit functionality
@@ -52,12 +101,39 @@ export declare class PathwaysBuilder<TPathway extends Record<string, unknown> =
      * @returns Promise that resolves when processing is complete
      */
     process(pathway: keyof TPathway, data: FlowcoreEvent): Promise<void>;
+    /**
+     * Registers a new pathway with the given contract
+     * @template F The flow type string
+     * @template E The event type string
+     * @template S The schema type extending TSchema
+     * @template W Boolean indicating if the pathway is writable (defaults to true)
+     * @param contract The pathway contract describing the pathway
+     * @returns The PathwaysBuilder instance with the new pathway registered
+     */
     register<F extends string, E extends string, S extends TSchema, W extends boolean = true>(contract: PathwayContract<F, E, S> & {
         writable?: W;
         maxRetries?: number;
         retryDelayMs?: number;
     }): PathwaysBuilder<TPathway & Record<PathwayKey<F, E>, Static<S>>, TWritablePaths | WritablePathway<PathwayKey<F, E>, W>>;
+    /**
+     * Gets a pathway instance by its path
+     *
+     * @template TPath The specific pathway key to retrieve
+     * @param path The pathway key to get
+     * @returns The pathway instance
+     */
     get<TPath extends keyof TPathway>(path: TPath): TPathway[TPath];
+    /**
+     * Sets a handler function for a pathway
+     *
+     * This handler will be called whenever an event is received for the specified pathway.
+     * Only one handler can be registered per pathway in a given PathwaysBuilder instance.
+     *
+     * @template TPath The specific pathway key to handle
+     * @param path The pathway key to handle
+     * @param handler The function that will process events for this pathway
+     * @throws Error if the pathway doesn't exist or already has a handler
+     */
     handle<TPath extends keyof TPathway>(path: TPath, handler: (event: FlowcoreEvent) => (Promise<void> | void)): void;
     /**
      * Subscribe to pathway events (before or after processing)
@@ -86,6 +162,17 @@ export declare class PathwaysBuilder<TPathway extends Record<string, unknown> =
      * @returns A promise that resolves to the event ID(s)
      */
     write<TPath extends TWritablePaths>(path: TPath, data: TPathway[TPath], metadata?: EventMetadata, options?: PathwayWriteOptions): Promise<string | string[]>;
+    /**
+     * Waits for a specific event to be processed
+     *
+     * This method polls the pathway state to check if an event has been processed,
+     * with a configurable timeout. It will throw an error if the timeout is exceeded.
+     *
+     * @private
+     * @param eventId The ID of the event to wait for
+     * @returns Promise that resolves when the event is processed
+     * @throws Error if the timeout is exceeded
+     */
     private waitForPathwayToBeProcessed;
 }
 //# sourceMappingURL=builder.d.ts.map

package/script/pathways/builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/pathways/builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/pathways/builder.ts"],"names":[],"mappings":"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"}

package/script/pathways/builder.js

@@ -6,10 +6,43 @@ const rxjs_1 = require("rxjs");
 const flowcore_transformer_core_sdk_js_1 = require("../compatibility/flowcore-transformer-core.sdk.js");
 const internal_pathway_state_js_1 = require("./internal-pathway.state.js");
 const logger_js_1 = require("./logger.js");
+/**
+ * Default timeout for pathway processing in milliseconds (10 seconds)
+ */
 const DEFAULT_PATHWAY_TIMEOUT_MS = 10000;
+/**
+ * Default maximum number of retry attempts for failed pathway processing
+ */
 const DEFAULT_MAX_RETRIES = 3;
+/**
+ * Default delay between retry attempts in milliseconds
+ */
 const DEFAULT_RETRY_DELAY_MS = 500;
+/**
+ * Main builder class for creating and managing Flowcore pathways
+ *
+ * The PathwaysBuilder provides an interface for:
+ * - Registering pathways with type-safe schemas
+ * - Handling events sent to pathways
+ * - Writing data to pathways
+ * - Managing event processing and retries
+ * - Observing event lifecycle (before/after/error)
+ * - Audit logging of pathway operations
+ *
+ * @template TPathway Record type that maps pathway keys to their payload types
+ * @template TWritablePaths Union type of pathway keys that can be written to
+ */
 class PathwaysBuilder {
+    /**
+     * Creates a new PathwaysBuilder instance
+     * @param options Configuration options for the PathwaysBuilder
+     * @param options.baseUrl The base URL for the Flowcore API
+     * @param options.tenant The tenant name
+     * @param options.dataCore The data core name
+     * @param options.apiKey The API key for authentication
+     * @param options.pathwayTimeoutMs Optional timeout for pathway processing in milliseconds
+     * @param options.logger Optional logger instance
+     */
     constructor({ baseUrl, tenant, dataCore, apiKey, pathwayTimeoutMs, logger, }) {
         Object.defineProperty(this, "pathways", {
             enumerable: true,
@@ -150,6 +183,11 @@ class PathwaysBuilder {
             this.pathwayTimeoutMs = pathwayTimeoutMs;
         }
     }
+    /**
+     * Configures the PathwaysBuilder to use a custom pathway state implementation
+     * @param state The PathwayState implementation to use
+     * @returns The PathwaysBuilder instance with custom state configured
+     */
     withPathwayState(state) {
         this.logger.debug('Setting custom pathway state');
         this.pathwayState = state;
@@ -227,10 +265,9 @@ class PathwaysBuilder {
                 catch (error) {
                     // Create error object if needed
                     const errorObj = error instanceof Error ? error : new Error(String(error));
-                    this.logger.error(`Error processing pathway event`, {
+                    this.logger.error(`Error processing pathway event`, errorObj, {
                         pathway: pathwayStr,
                         eventId: data.eventId,
-                        error: errorObj.message,
                         retryCount,
                         maxRetries
                     });
@@ -280,6 +317,15 @@ class PathwaysBuilder {
             await this.pathwayState.setProcessed(data.eventId);
         }
     }
+    /**
+     * Registers a new pathway with the given contract
+     * @template F The flow type string
+     * @template E The event type string
+     * @template S The schema type extending TSchema
+     * @template W Boolean indicating if the pathway is writable (defaults to true)
+     * @param contract The pathway contract describing the pathway
+     * @returns The PathwaysBuilder instance with the new pathway registered
+     */
     register(contract) {
         const path = `${contract.flowType}/${contract.eventType}`;
         const writable = contract.writable ?? true;
@@ -328,10 +374,28 @@ class PathwaysBuilder {
         });
         return this;
     }
+    /**
+     * Gets a pathway instance by its path
+     *
+     * @template TPath The specific pathway key to retrieve
+     * @param path The pathway key to get
+     * @returns The pathway instance
+     */
     get(path) {
         this.logger.debug(`Getting pathway`, { pathway: String(path) });
         return this.pathways[path];
     }
+    /**
+     * Sets a handler function for a pathway
+     *
+     * This handler will be called whenever an event is received for the specified pathway.
+     * Only one handler can be registered per pathway in a given PathwaysBuilder instance.
+     *
+     * @template TPath The specific pathway key to handle
+     * @param path The pathway key to handle
+     * @param handler The function that will process events for this pathway
+     * @throws Error if the pathway doesn't exist or already has a handler
+     */
     handle(path, handler) {
         const pathStr = String(path);
         this.logger.debug(`Setting handler for pathway`, { pathway: pathStr });
@@ -436,12 +500,12 @@ class PathwaysBuilder {
         }
         const schema = this.schemas[path];
         if (!value_1.Value.Check(schema, data)) {
-            const error = `Invalid data for pathway ${pathStr}`;
-            this.logger.error(error, {
+            const errorMessage = `Invalid data for pathway ${pathStr}`;
+            this.logger.error(errorMessage, new Error(errorMessage), {
                 pathway: pathStr,
                 schema: schema.toString()
             });
-            throw new Error(error);
+            throw new Error(errorMessage);
         }
         // Create a copy of the metadata to avoid modifying the original
         const finalMetadata = metadata ? { ...metadata } : {};
@@ -493,6 +557,17 @@ class PathwaysBuilder {
         }
         return eventIds;
     }
+    /**
+     * Waits for a specific event to be processed
+     *
+     * This method polls the pathway state to check if an event has been processed,
+     * with a configurable timeout. It will throw an error if the timeout is exceeded.
+     *
+     * @private
+     * @param eventId The ID of the event to wait for
+     * @returns Promise that resolves when the event is processed
+     * @throws Error if the timeout is exceeded
+     */
     async waitForPathwayToBeProcessed(eventId) {
         const startTime = Date.now();
         const timeoutMs = this.timeouts[eventId] ?? this.pathwayTimeoutMs;
@@ -505,14 +580,14 @@ class PathwaysBuilder {
             attempts++;
             const elapsedTime = Date.now() - startTime;
             if (elapsedTime > timeoutMs) {
-                const error = `Pathway processing timed out after ${timeoutMs}ms for event ${eventId}`;
-                this.logger.error(error, {
+                const errorMessage = `Pathway processing timed out after ${timeoutMs}ms for event ${eventId}`;
+                this.logger.error(errorMessage, new Error(errorMessage), {
                     eventId,
                     timeoutMs,
                     elapsedTime,
                     attempts
                 });
-                throw new Error(error);
+                throw new Error(errorMessage);
             }
             if (attempts % 10 === 0) { // Log every 10 attempts (1 second)
                 this.logger.debug(`Still waiting for event to be processed`, {

package/script/pathways/index.d.ts

@@ -7,6 +7,8 @@
  * - Storage adapters (KV, Postgres)
  * - Logging
  * - Type definitions
+ *
+ * @module
  */
 export * from "./builder.js";
 export * from "./internal-pathway.state.js";

package/script/pathways/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pathways/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,cAAc,cAAc,CAAC;AAC7B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pathways/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,cAAc,cAAc,CAAC;AAC7B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC"}

package/script/pathways/index.js

@@ -23,6 +23,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * - Storage adapters (KV, Postgres)
  * - Logging
  * - Type definitions
+ *
+ * @module
  */
 __exportStar(require("./builder.js"), exports);
 __exportStar(require("./internal-pathway.state.js"), exports);