@flowcore/pathways 0.8.0 → 0.9.1

package/script/pathways/session-pathway.js

@@ -24,6 +24,38 @@ function generateUUID() {
  *
  * This provides a convenient way to track operations within a user session
  * by automatically including the session ID in metadata.
+ *
+ * Key features:
+ * - Automatic session ID generation if none is provided
+ * - Cross-platform UUID generation (works in Deno, Bun, and Node.js)
+ * - Simple API for accessing the current session ID
+ * - Convenient integration with session-specific user resolvers
+ * - Automatic inclusion of session ID in all write operations
+ * - Support for overriding the session ID on specific writes
+ *
+ * Use cases:
+ * - Tracking user actions across multiple pathway writes
+ * - Connecting related events in a single user session
+ * - Supporting multi-user environments where different users' operations need to be tracked separately
+ * - Building user activity logs with session grouping
+ *
+ * @example
+ * ```typescript
+ * // Create a session pathway with auto-generated ID
+ * const session = new SessionPathwayBuilder(pathwaysBuilder);
+ *
+ * // Get the auto-generated session ID
+ * const sessionId = session.getSessionId();
+ *
+ * // Register a user resolver for this session
+ * session.withUserResolver(async () => getCurrentUserId());
+ *
+ * // Write events with session context
+ * await session.write("order/placed", orderData);
+ * await session.write("user/action", actionData);
+ *
+ * // All events will be associated with the same session ID
+ * ```
  */
 class SessionPathwayBuilder {
     /**
@@ -56,6 +88,39 @@ class SessionPathwayBuilder {
     getSessionId() {
         return this.sessionId;
     }
+    /**
+     * Registers a user resolver for this session
+     *
+     * This is a convenience method that calls `pathwaysBuilder.withSessionUserResolver`
+     * with the current session ID, allowing you to set up a resolver specific to this session
+     * without having to manually pass the session ID.
+     *
+     * The resolver will be called whenever events are written through this session,
+     * and the resolved user ID will be included in the event metadata.
+     *
+     * @param resolver The function that resolves to the user ID for this session
+     * @returns The SessionPathwayBuilder instance for chaining
+     *
+     * @throws Error if the underlying PathwaysBuilder does not have session user resolvers configured
+     *
+     * @example
+     * ```typescript
+     * const session = new SessionPathwayBuilder(pathwaysBuilder);
+     *
+     * // Register a user resolver for this session
+     * session.withUserResolver(async () => {
+     *   // Get the user ID associated with this session
+     *   return getUserIdFromSession();
+     * });
+     *
+     * // When writing events, the user ID will be automatically included
+     * await session.write("user/action", actionData);
+     * ```
+     */
+    withUserResolver(resolver) {
+        this.pathwaysBuilder.withSessionUserResolver(this.sessionId, resolver);
+        return this;
+    }
     /**
      * Writes data to a pathway, proxying to the underlying PathwaysBuilder
      *

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