@flowcore/pathways 0.7.0 → 0.9.0

package/script/router/index.d.ts

@@ -11,6 +11,49 @@ 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
+ *
+ * The PathwayRouter serves as a bridge between incoming webhook events and the PathwaysBuilder,
+ * ensuring events are routed to the correct pathway handlers based on flow type and event type.
+ *
+ * Key features:
+ * - Secure authentication using a secret key
+ * - Automatic mapping of events to the correct pathway handlers
+ * - Compatibility with both legacy and modern Flowcore event formats
+ * - Detailed error handling and logging
+ *
+ * Use cases:
+ * - Building webhook endpoints that receive Flowcore events
+ * - Creating API routes that process events from external systems
+ * - Implementing event-driven microservices that consume Flowcore events
+ *
+ * @example
+ * ```typescript
+ * // Create a router with authentication
+ * const SECRET_KEY = "your-webhook-secret";
+ * const router = new PathwayRouter(pathwaysBuilder, SECRET_KEY);
+ *
+ * // In your HTTP handler:
+ * async function handleWebhook(req: Request) {
+ *   const event = await req.json();
+ *   const secret = req.headers.get("X-Webhook-Secret");
+ *
+ *   try {
+ *     const result = await router.processEvent(event, secret);
+ *     return new Response(JSON.stringify(result), {
+ *       status: 200,
+ *       headers: { "Content-Type": "application/json" }
+ *     });
+ *   } catch (error) {
+ *     console.error("Error processing event:", error);
+ *     return new Response(JSON.stringify({
+ *       error: error.message
+ *     }), {
+ *       status: 401,
+ *       headers: { "Content-Type": "application/json" }
+ *     });
+ *   }
+ * }
+ * ```
  */
 export declare class PathwayRouter {
     private readonly pathways;
@@ -28,10 +71,48 @@ export declare class PathwayRouter {
     /**
      * Process an incoming event by routing it to the appropriate pathway handler
      *
-     * @param event The event to process
+     * This method handles the complete lifecycle of an incoming event:
+     * 1. Validates the authentication using the provided secret key
+     * 2. Maps the event to the correct pathway based on flowType and eventType
+     * 3. Delegates processing to the PathwaysBuilder
+     * 4. Provides detailed error handling and feedback
+     *
+     * The method supports both modern Flowcore events and legacy events that used
+     * the "aggregator" field instead of "flowType". It automatically converts legacy
+     * events to the modern format before processing.
+     *
+     * @param event The event to process, containing flowType, eventType, and payload
      * @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
+     *
+     * @throws Error if authentication fails (401 unauthorized)
+     * @throws Error if the pathway is not found (404 not found)
+     * @throws Error if processing fails (includes the original error message)
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * try {
+     *   const result = await router.processEvent(incomingEvent, secretFromHeader);
+     *   console.log("Success:", result.message);
+     * } catch (error) {
+     *   console.error("Failed to process event:", error.message);
+     * }
+     *
+     * // With error handling for different error types
+     * try {
+     *   const result = await router.processEvent(event, secret);
+     *   return { status: 200, body: result };
+     * } catch (error) {
+     *   if (error.message.includes("Invalid secret key")) {
+     *     return { status: 401, body: { error: "Unauthorized" } };
+     *   } else if (error.message.includes("not found")) {
+     *     return { status: 404, body: { error: "Pathway not found" } };
+     *   } else {
+     *     return { status: 500, body: { error: "Processing failed" } };
+     *   }
+     * }
+     * ```
      */
     processEvent(event: FlowcoreLegacyEvent, providedSecret: string): Promise<{
         success: boolean;

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

@@ -1 +1 @@
-{"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"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6CG;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/script/router/index.js

@@ -4,6 +4,49 @@ exports.PathwayRouter = void 0;
 const logger_js_1 = require("../pathways/logger.js");
 /**
  * Router class that handles directing events to the appropriate pathway handlers
+ *
+ * The PathwayRouter serves as a bridge between incoming webhook events and the PathwaysBuilder,
+ * ensuring events are routed to the correct pathway handlers based on flow type and event type.
+ *
+ * Key features:
+ * - Secure authentication using a secret key
+ * - Automatic mapping of events to the correct pathway handlers
+ * - Compatibility with both legacy and modern Flowcore event formats
+ * - Detailed error handling and logging
+ *
+ * Use cases:
+ * - Building webhook endpoints that receive Flowcore events
+ * - Creating API routes that process events from external systems
+ * - Implementing event-driven microservices that consume Flowcore events
+ *
+ * @example
+ * ```typescript
+ * // Create a router with authentication
+ * const SECRET_KEY = "your-webhook-secret";
+ * const router = new PathwayRouter(pathwaysBuilder, SECRET_KEY);
+ *
+ * // In your HTTP handler:
+ * async function handleWebhook(req: Request) {
+ *   const event = await req.json();
+ *   const secret = req.headers.get("X-Webhook-Secret");
+ *
+ *   try {
+ *     const result = await router.processEvent(event, secret);
+ *     return new Response(JSON.stringify(result), {
+ *       status: 200,
+ *       headers: { "Content-Type": "application/json" }
+ *     });
+ *   } catch (error) {
+ *     console.error("Error processing event:", error);
+ *     return new Response(JSON.stringify({
+ *       error: error.message
+ *     }), {
+ *       status: 401,
+ *       headers: { "Content-Type": "application/json" }
+ *     });
+ *   }
+ * }
+ * ```
  */
 class PathwayRouter {
     /**
@@ -46,10 +89,48 @@ class PathwayRouter {
     /**
      * Process an incoming event by routing it to the appropriate pathway handler
      *
-     * @param event The event to process
+     * This method handles the complete lifecycle of an incoming event:
+     * 1. Validates the authentication using the provided secret key
+     * 2. Maps the event to the correct pathway based on flowType and eventType
+     * 3. Delegates processing to the PathwaysBuilder
+     * 4. Provides detailed error handling and feedback
+     *
+     * The method supports both modern Flowcore events and legacy events that used
+     * the "aggregator" field instead of "flowType". It automatically converts legacy
+     * events to the modern format before processing.
+     *
+     * @param event The event to process, containing flowType, eventType, and payload
      * @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
+     *
+     * @throws Error if authentication fails (401 unauthorized)
+     * @throws Error if the pathway is not found (404 not found)
+     * @throws Error if processing fails (includes the original error message)
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * try {
+     *   const result = await router.processEvent(incomingEvent, secretFromHeader);
+     *   console.log("Success:", result.message);
+     * } catch (error) {
+     *   console.error("Failed to process event:", error.message);
+     * }
+     *
+     * // With error handling for different error types
+     * try {
+     *   const result = await router.processEvent(event, secret);
+     *   return { status: 200, body: result };
+     * } catch (error) {
+     *   if (error.message.includes("Invalid secret key")) {
+     *     return { status: 401, body: { error: "Unauthorized" } };
+     *   } else if (error.message.includes("not found")) {
+     *     return { status: 404, body: { error: "Pathway not found" } };
+     *   } else {
+     *     return { status: 500, body: { error: "Processing failed" } };
+     *   }
+     * }
+     * ```
      */
     async processEvent(event, providedSecret) {
         // Validate secret key