@flowcore/pathways 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [0.2.2](https://github.com/flowcore-io/flowcore-pathways/compare/v0.2.1...v0.2.2) (2025-03-15)
+
+
+### Bug Fixes
+
+* **deno.json:** :memo: Update library description to specify TypeScript ([014f1fc](https://github.com/flowcore-io/flowcore-pathways/commit/014f1fc88d5e5545dd92ff78fa0aae86a9aceebb))
+* **mod:** :memo: Add module declaration comments to pathways and mod files ([275f41a](https://github.com/flowcore-io/flowcore-pathways/commit/275f41ac9d75b2f2509ddf78ddbd31fc8cd3914a))
+* **types:** :memo: Add module declaration comments and improve JSDoc formatting ([21781f2](https://github.com/flowcore-io/flowcore-pathways/commit/21781f2ab8b8064935d831dfc9f2965f703af343))
+
 ## [0.2.1](https://github.com/flowcore-io/flowcore-pathways/compare/v0.2.0...v0.2.1) (2025-03-15)
 
 

package/esm/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/esm/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/esm/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/esm/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/esm/common/index.js

@@ -2,5 +2,7 @@
  * 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";

package/esm/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/esm/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/esm/compatibility/flowcore-transformer-core.sdk.js

@@ -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";
 /**

package/esm/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/esm/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/esm/contracts/index.js

@@ -1,4 +1,6 @@
 /**
  * Export all contract types and schemas for Flowcore events
+ *
+ * @module
  */
 export * from "./event.js";

package/esm/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/esm/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/esm/mod.js

@@ -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/esm/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/esm/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/esm/pathways/builder.js

@@ -3,10 +3,43 @@ import { Subject } from "rxjs";
 import { WebhookBuilder } from "../compatibility/flowcore-transformer-core.sdk.js";
 import { InternalPathwayState } from "./internal-pathway.state.js";
 import { NoopLogger } from "./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
+ */
 export 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,
@@ -147,6 +180,11 @@ export 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;
@@ -224,10 +262,9 @@ export 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
                     });
@@ -277,6 +314,15 @@ export 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;
@@ -325,10 +371,28 @@ export 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 });
@@ -433,12 +497,12 @@ export class PathwaysBuilder {
         }
         const schema = this.schemas[path];
         if (!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 } : {};
@@ -490,6 +554,17 @@ export 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;
@@ -502,14 +577,14 @@ export 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/esm/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/esm/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/esm/pathways/index.js

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

package/esm/pathways/internal-pathway.state.d.ts

@@ -2,8 +2,6 @@ import type { PathwayState } from "./types.js";
 /**
  * Internal implementation of PathwayState interface that uses KV storage
  * for tracking processed events to prevent duplicate processing
- *
- * @implements {PathwayState}
  */
 export declare class InternalPathwayState implements PathwayState {
     /**
@@ -20,21 +18,21 @@ export declare class InternalPathwayState implements PathwayState {
      * Gets or initializes the KV adapter
      *
      * @private
-     * @returns {Promise<KvAdapter>} The KV adapter instance
+     * @returns The KV adapter instance
      */
     private getKv;
     /**
      * Checks if an event has already been processed
      *
-     * @param {string} eventId - The ID of the event to check
-     * @returns {Promise<boolean>} True if the event has been processed, false otherwise
+     * @param eventId The ID of the event to check
+     * @returns True if the event has been processed, false otherwise
      */
     isProcessed(eventId: string): Promise<boolean>;
     /**
      * Marks an event as processed
      *
-     * @param {string} eventId - The ID of the event to mark as processed
-     * @returns {Promise<void>}
+     * @param eventId The ID of the event to mark as processed
+     * @returns Promise that resolves when the operation completes
      */
     setProcessed(eventId: string): Promise<void>;
 }

package/esm/pathways/internal-pathway.state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal-pathway.state.d.ts","sourceRoot":"","sources":["../../src/pathways/internal-pathway.state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;GAKG;AACH,qBAAa,oBAAqB,YAAW,YAAY;IACvD;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAEvD;;;OAGG;IACH,OAAO,CAAC,EAAE,CAA0B;IAEpC;;;;;OAKG;YACW,KAAK;IAOnB;;;;;OAKG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMpD;;;;;OAKG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAInD"}
+{"version":3,"file":"internal-pathway.state.d.ts","sourceRoot":"","sources":["../../src/pathways/internal-pathway.state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;GAGG;AACH,qBAAa,oBAAqB,YAAW,YAAY;IACvD;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAEvD;;;OAGG;IACH,OAAO,CAAC,EAAE,CAA0B;IAEpC;;;;;OAKG;YACW,KAAK;IAOnB;;;;;OAKG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMpD;;;;;OAKG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAInD"}

package/esm/pathways/internal-pathway.state.js

@@ -2,8 +2,6 @@ import { createKvAdapter } from "./kv/kv-adapter.js";
 /**
  * Internal implementation of PathwayState interface that uses KV storage
  * for tracking processed events to prevent duplicate processing
- *
- * @implements {PathwayState}
  */
 export class InternalPathwayState {
     constructor() {
@@ -22,7 +20,7 @@ export class InternalPathwayState {
      * Gets or initializes the KV adapter
      *
      * @private
-     * @returns {Promise<KvAdapter>} The KV adapter instance
+     * @returns The KV adapter instance
      */
     async getKv() {
         if (!this.kv) {
@@ -33,8 +31,8 @@ export class InternalPathwayState {
     /**
      * Checks if an event has already been processed
      *
-     * @param {string} eventId - The ID of the event to check
-     * @returns {Promise<boolean>} True if the event has been processed, false otherwise
+     * @param eventId The ID of the event to check
+     * @returns True if the event has been processed, false otherwise
      */
     async isProcessed(eventId) {
         const kv = await this.getKv();
@@ -44,8 +42,8 @@ export class InternalPathwayState {
     /**
      * Marks an event as processed
      *
-     * @param {string} eventId - The ID of the event to mark as processed
-     * @returns {Promise<void>}
+     * @param eventId The ID of the event to mark as processed
+     * @returns Promise that resolves when the operation completes
      */
     async setProcessed(eventId) {
         const kv = await this.getKv();

package/esm/pathways/kv/bun-kv-adapter.d.ts

@@ -3,8 +3,6 @@ import type { KvAdapter } from "./kv-adapter.js";
  * KV adapter implementation for Bun runtime
  *
  * Uses Bun's SQLite-based key-value store for storage
- *
- * @implements {KvAdapter}
  */
 export declare class BunKvAdapter implements KvAdapter {
     /**
@@ -20,16 +18,16 @@ export declare class BunKvAdapter implements KvAdapter {
      * Retrieves a value from the Bun KV store
      *
      * @template T The expected type of the stored value
-     * @param {string} key The key to retrieve
-     * @returns {T | null} The stored value or null if not found
+     * @param key The key to retrieve
+     * @returns The stored value or null if not found
      */
     get<T>(key: string): T | null;
     /**
      * Stores a value in the Bun KV store with the specified TTL
      *
-     * @param {string} key The key to store the value under
-     * @param {unknown} value The value to store
-     * @param {number} ttlMs Time-to-live in milliseconds
+     * @param key The key to store the value under
+     * @param value The value to store
+     * @param ttlMs Time-to-live in milliseconds
      */
     set(key: string, value: unknown, ttlMs: number): void;
 }

package/esm/pathways/kv/bun-kv-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bun-kv-adapter.d.ts","sourceRoot":"","sources":["../../../src/pathways/kv/bun-kv-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;GAMG;AACH,qBAAa,YAAa,YAAW,SAAS;IAC5C;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAoB;IAEjC;;OAEG;;IAKH;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAK7B;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;CAGtD"}
+{"version":3,"file":"bun-kv-adapter.d.ts","sourceRoot":"","sources":["../../../src/pathways/kv/bun-kv-adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;GAIG;AACH,qBAAa,YAAa,YAAW,SAAS;IAC5C;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAoB;IAEjC;;OAEG;;IAKH;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAK7B;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;CAGtD"}

package/esm/pathways/kv/bun-kv-adapter.js

@@ -3,8 +3,6 @@ import { BunSqliteKeyValue } from "bun-sqlite-key-value";
  * KV adapter implementation for Bun runtime
  *
  * Uses Bun's SQLite-based key-value store for storage
- *
- * @implements {KvAdapter}
  */
 export class BunKvAdapter {
     /**
@@ -27,8 +25,8 @@ export class BunKvAdapter {
      * Retrieves a value from the Bun KV store
      *
      * @template T The expected type of the stored value
-     * @param {string} key The key to retrieve
-     * @returns {T | null} The stored value or null if not found
+     * @param key The key to retrieve
+     * @returns The stored value or null if not found
      */
     get(key) {
         const value = this.store.get(key);
@@ -37,9 +35,9 @@ export class BunKvAdapter {
     /**
      * Stores a value in the Bun KV store with the specified TTL
      *
-     * @param {string} key The key to store the value under
-     * @param {unknown} value The value to store
-     * @param {number} ttlMs Time-to-live in milliseconds
+     * @param key The key to store the value under
+     * @param value The value to store
+     * @param ttlMs Time-to-live in milliseconds
      */
     set(key, value, ttlMs) {
         this.store.set(key, value, ttlMs);